Send to AI

Create Content

Add new content items to your catalog. Supports all content types: PDF, EPUB, audiobooks, physical products, and external links.

Endpoint

POST /api/v3/content

Request Body

Required Fields

Field	Type	Description
`name`	string	Content title (max 255 chars)
`file_type`	string	Content type: `pdf`, `epub`, `audio`, `physical`
`lang`	string	ISO 639-1 language code. See Supported Content Languages

Optional Fields

Field	Type	Description
`external_id`	string	Your unique ID (ISBN, SKU, etc., max 64 chars)
`description`	string	Full content description (HTML allowed)
`published_at`	string	Publication date (YYYY-MM-DD only)
`audience`	string	Target audience

File Upload (digital content only)

Field	Type	Description
`file`	string	Storage path to uploaded file (mutually exclusive with `file_url`)
`file_url`	string	External URL to download file from (mutually exclusive with `file`)
`cover`	string	Storage path to uploaded cover image (mutually exclusive with `cover_url`)
`cover_url`	string	External URL for cover image (mutually exclusive with `cover`)

File Upload Options

file_url / cover_url: Provide a publicly accessible URL. The platform will download the file automatically.
file / cover: Provide a storage path from SFTP upload. Contact support to enable SFTP access for your account.

File Processing

Files are processed asynchronously. The content is created immediately with conversion_status: awaiting. Use Get Content to poll for processing completion.

Pricing

Field	Type	Description
`prices`	array	Price array: `[{currency_id, amount}]`

Scheduled Pricing

Prices support starts_at and ends_at fields for scheduled pricing: [{currency_id, amount, starts_at, ends_at}]. Dates should be in YYYY-MM-DD format.

Access Settings

Field	Type	Description
`free`	boolean	Enable free access
`free_until`	string	Free access expiration (YYYY-MM-DD)
`require_login`	boolean	Require login for free access
`preview`	boolean	Enable content preview
`preview_require_login`	boolean	Require login for preview

Metadata

Field	Type	Description
`author`	array	Author names (max 200 chars each)
`publisher`	array	Publisher names (max 200 chars each)
`keywords`	array	Keywords/tags (max 200 chars each)
`bisac`	array	BISAC codes: `[{code: "FIC000000"}]` (max 4 codes)
`category`	array	Category names (max 200 chars each)
`collection`	array	Collection names (max 200 chars each)
`country`	array	Country names (max 200 chars each)
`edition`	array	Edition names (max 200 chars each)
`narrator`	array	Narrator names for audiobooks (max 200 chars each)
`publishing_group`	array	Publishing group names (max 200 chars each)
`custom_metadata`	object	Custom taxonomy groups: `{"group_slug": ["value1", "value2"]}`
`share_with_tenants_ids`	array	Tenant IDs (strings) to share this content with. See Content Sharing
`format_group_ids`	array	Format group IDs (strings) to associate this content with

Geographic Restrictions

Field	Type	Description
`geographic_restrictions`	object	`{included: [...], excluded: [...]}`

Physical Product Fields

Field	Type	Description
`binding_type`	string	Binding type (hardcover, paperback, etc.)
`pages`	integer	Number of pages (min: 0)
`height`	float	Height in cm (min: 0)
`width`	float	Width in cm (min: 0)
`weight`	float	Weight in grams (min: 0)
`stock`	boolean	In stock status
`editing_location`	string	Editing/printing location
`thickness`	float	Thickness in cm (min: 0)

Request Examples

Basic PDF Content

curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Introduction to Machine Learning",
    "file_type": "pdf",
    "lang": "en",
    "external_id": "9781234567890",
    "file_url": "https://example.com/files/ml-intro.pdf"
  }'

EPUB with Full Metadata

curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "The Complete Guide to Digital Publishing",
    "file_type": "epub",
    "lang": "en",
    "external_id": "9780987654321",
    "description": "<p>A comprehensive guide to digital publishing...</p>",
    "published_at": "2025-01-15",
    "file_url": "https://example.com/files/publishing-guide.epub",
    "cover_url": "https://example.com/covers/publishing-guide.jpg",
    "prices": [
      { "currency_id": "USD", "amount": 19.99 },
      { "currency_id": "EUR", "amount": 17.99 }
    ],
    "author": ["Jane Smith", "John Doe"],
    "publisher": ["Tech Publishing House"],
    "keywords": ["publishing", "digital", "ebooks"],
    "bisac": [
      { "code": "COM000000" }
    ]
  }'

Free Content with Expiration

curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sample Chapter - Preview Edition",
    "file_type": "pdf",
    "lang": "en",
    "external_id": "SAMPLE-001",
    "file_url": "https://example.com/samples/chapter1.pdf",
    "free": true,
    "free_until": "2025-06-30",
    "require_login": true
  }'

Audiobook

curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mystery Novel - Narrated Edition",
    "file_type": "audio",
    "lang": "en",
    "external_id": "AUDIO-001",
    "description": "Award-winning mystery novel, professionally narrated",
    "prices": [
      { "currency_id": "USD", "amount": 14.99 }
    ],
    "author": ["Mystery Author"],
    "publisher": ["Audiobook Productions"]
  }'

Audiobook Tracks

After creating an audiobook, use the Audiobook Tracks API to add individual audio tracks.

Physical Product

curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Collector Edition Hardcover",
    "file_type": "physical",
    "lang": "en",
    "external_id": "PHYSICAL-001",
    "cover_url": "https://example.com/covers/collector.jpg",
    "prices": [
      { "currency_id": "USD", "amount": 49.99 }
    ],
    "binding_type": "hardcover",
    "pages": 450,
    "height": 24.5,
    "width": 16.0,
    "weight": 650,
    "stock": true
  }'

Content with Geographic Restrictions

curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Regional Edition",
    "file_type": "epub",
    "lang": "es",
    "external_id": "REGIONAL-001",
    "file_url": "https://example.com/files/regional.epub",
    "prices": [
      { "currency_id": "USD", "amount": 9.99 }
    ],
    "geographic_restrictions": {
      "included": ["AR", "CL", "UY", "MX"],
      "excluded": []
    }
  }'

Response

Success Response (201 Created)

{
  "data": {
    "id": "468170",
    "external_id": "9781234567890",
    "name": "Introduction to Machine Learning",
    "slug": "introduction-to-machine-learning",
    "lang": "en",
    "file_type": "pdf",
    "audience": null,
    "cover_url": null,
    "reader_url": "https://yourstore.publica.la/reader/introduction-to-machine-learning",
    "product_url": "https://yourstore.publica.la/library/publication/introduction-to-machine-learning",
    "created_at": "2025-12-23T10:30:00.000000Z",
    "updated_at": "2025-12-23T10:30:00.000000Z",
    "published_at": "2025-12-23T00:00:00.000000Z",
    "license": "retail",
    "free": {
      "enabled": false,
      "until": null,
      "require_login": false
    },
    "preview": {
      "enabled": false,
      "require_login": false
    },
    "conversion_status": "awaiting",
    "prices": [],
    "description": null,
    "publisher": [],
    "author": [],
    "bisac": [],
    "keywords": [],
    "country": [],
    "edition": [],
    "narrator": [],
    "publishing_group": [],
    "category": [],
    "collection": [],
    "metrics": {
      "total_pages": 0,
      "total_words": 0,
      "total_seconds": 0
    },
    "custom_metadata": {},
    "geographic_restrictions": null
  }
}

Always Included

The create response always includes prices, description, metadata, and geographic_restrictions data regardless of the include parameter.

Conversion Status

Digital content undergoes asynchronous processing. Track the status via the conversion_status field returned in the content response.

Status	Description
`awaiting_*`	Content is queued or waiting for processing to begin
`started_*`	Processing in progress (varies by file type)
`done`	Processing complete, content available
`deferred`	Awaiting first user access to trigger processing (bulk imports)
`error_*`	Processing failed (varies by file type)

Intermediate statuses may change

Do not couple your logic to specific intermediate status values (awaiting_*, started_*, error_*) as they may change without notice. If you need to check whether content is ready, use done as the only stable status to rely on.

Polling for Completion

curl -X GET "https://yourstore.publica.la/api/v3/content/468170" \
  -H "X-User-Token: your-api-token"

Error Handling

Validation Errors (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "file_type": ["The selected file type is invalid."]
  }
}

Duplicate External ID (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "external_id": ["The external id has already been taken."]
  }
}

File Processing Error (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "file_url": ["Unable to download file from the provided URL."]
  }
}

Authentication Error (401)

{
  "message": "Unauthenticated."
}

Common Validation Rules

Field	Rules
`name`	Required, max 255 chars
`file_type`	Required, one of: `pdf`, `epub`, `audio`, `physical`
`lang`	Required, valid language code
`external_id`	Optional, max 64 chars, unique per tenant
`description`	Optional, max 20,000 chars, HTML allowed
`prices[].currency_id`	Valid ISO 4217 currency code
`prices[].amount`	Number, min: 0 (zero allowed for free pricing)
`file_url`	Valid URL, accessible for download
`published_at`	Valid date (YYYY-MM-DD only)
`bisac[].code`	Valid BISAC code
`geographic_restrictions.included`	Array of ISO 3166-1 alpha-2 country codes
`geographic_restrictions.excluded`	Array of ISO 3166-1 alpha-2 country codes

Best Practices

Use external IDs - Always set a unique external_id for cross-system synchronization
Poll for completion - Check conversion_status before assuming content is available
Include complete metadata - Better discoverability with author, publisher, and BISAC codes
Set prices upfront - Configure pricing at creation to avoid separate update calls

Create Content

Endpoint

Request Body

Required Fields

Optional Fields

File Upload (digital content only)

Pricing

Access Settings

Metadata

Geographic Restrictions

Physical Product Fields

Request Examples

Basic PDF Content

EPUB with Full Metadata

Free Content with Expiration

Audiobook

Physical Product

Content with Geographic Restrictions

Response

Success Response (201 Created)

Conversion Status

Polling for Completion

Error Handling

Validation Errors (422)

Duplicate External ID (422)

File Processing Error (422)

Authentication Error (401)

Common Validation Rules

Best Practices

See Also

Graph View

Endpoint​

Request Body​

Required Fields​

Optional Fields​

File Upload (digital content only)​

Pricing​

Access Settings​

Metadata​

Geographic Restrictions​

Physical Product Fields​

Request Examples​

Basic PDF Content​

EPUB with Full Metadata​

Free Content with Expiration​

Audiobook​

Physical Product​

Content with Geographic Restrictions​

Response​

Success Response (201 Created)​

Conversion Status​

Polling for Completion​

Error Handling​

Validation Errors (422)​

Duplicate External ID (422)​

File Processing Error (422)​

Authentication Error (401)​

Common Validation Rules​

Best Practices​

See Also​

Graph View

Endpoint

Request Body

Required Fields

Optional Fields

File Upload (digital content only)

Pricing

Access Settings

Metadata

Geographic Restrictions

Physical Product Fields

Request Examples

Basic PDF Content

EPUB with Full Metadata

Free Content with Expiration

Audiobook

Physical Product

Content with Geographic Restrictions

Response

Success Response (201 Created)

Conversion Status

Polling for Completion

Error Handling

Validation Errors (422)

Duplicate External ID (422)

File Processing Error (422)

Authentication Error (401)

Common Validation Rules

Best Practices

See Also