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
`description`	string	Full content description (HTML allowed)
`published_at`	string	Publication date (YYYY-MM-DD only)
`audience`	string	Target audience
`subtitle`	string	Content subtitle (max 255 chars)
`publication_place`	string	Place of publication (max 255 chars)
`edition_year`	integer	Edition year (4 digits, e.g., `2025`)

Identifiers

Field	Type	Description
`identifiers`	array	Array of identifier objects (max 20)
`identifiers[].type`	string	Identifier type: `isbn_digital`, `isbn_printed`, `uuid`, `ddc`, `external_id`
`identifiers[].value`	string	Identifier value (max 255 chars). Validated per type (e.g., ISBN-13 checksum)
`identifiers[].is_primary`	boolean	Mark as primary identifier (optional, defaults to `false`)

Primary Identifier

The primary identifier's value is automatically synced to the external_id field for backward compatibility. If no identifier is marked as primary, the first one in the array is auto-promoted. Only one identifier can be marked as primary.

Types isbn_digital, isbn_printed, uuid, and external_id require tenant-level uniqueness — two content items cannot share the same identifier of these types. The ddc type does not require uniqueness.

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

Marketplace

Field	Type	Description
`show_in_marketplace`	boolean	Make content available in the Publica.la marketplace. When `true`, the content is listed for other tenants to discover and add to their stores. Defaults to `false` if not provided.

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",
    "file_url": "https://example.com/files/ml-intro.pdf",
    "identifiers": [
      { "type": "isbn_digital", "value": "978-1-234-56789-0", "is_primary": true }
    ]
  }'

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",
    "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" }
    ],
    "identifiers": [
      { "type": "isbn_digital", "value": "978-0-987-65432-1", "is_primary": true }
    ]
  }'

Content with Multiple Identifiers

curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Data Structures",
    "file_type": "epub",
    "lang": "en",
    "file_url": "https://example.com/files/data-structures.epub",
    "identifiers": [
      { "type": "isbn_digital", "value": "978-0-306-40615-7", "is_primary": true },
      { "type": "ddc", "value": "005.73" }
    ]
  }'

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",
    "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",
    "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",
    "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",
    "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": "978-1-234-56789-0",
    "name": "Introduction to Machine Learning",
    "slug": "introduction-to-machine-learning",
    "lang": "en",
    "file_type": "pdf",
    "audience": null,
    "subtitle": null,
    "publication_place": null,
    "edition_year": 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": [],
    "thema": [],
    "series": [],
    "category": [],
    "collection": [],
    "metrics": {
      "total_pages": 0,
      "total_words": 0,
      "total_seconds": 0
    },
    "custom_metadata": {},
    "geographic_restrictions": null,
    "identifiers": [
      {
        "type": "isbn_digital",
        "value": "978-1-234-56789-0",
        "is_primary": true
      }
    ]
  }
}

Always Included

The create response always includes prices, description, metadata, geographic_restrictions, and identifiers 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 Identifier (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "identifiers.0.value": [
      "This isbn_digital identifier is already in use as primary for another content."
    ]
  }
}

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
`subtitle`	Optional, max 255 chars
`publication_place`	Optional, max 255 chars
`edition_year`	Optional, 4 digits
`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
`identifiers`	Optional, array, max 20 items
`identifiers[].type`	Required, one of: `isbn_digital`, `isbn_printed`, `uuid`, `ddc`, `external_id`
`identifiers[].value`	Required, max 255 chars. Validated per type (ISBN-10/ISBN-13 checksum, UUID format, DDC format)
`identifiers[].is_primary`	Optional, boolean

Best Practices

Use identifiers - Always set identifiers (ISBN, UUID, etc.) 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

Identifiers

File Upload (digital content only)

Pricing

Access Settings

Marketplace

Metadata

Geographic Restrictions

Physical Product Fields

Request Examples

Basic PDF Content

EPUB with Full Metadata

Content with Multiple Identifiers

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 Identifier (422)

File Processing Error (422)

Authentication Error (401)

Common Validation Rules

Best Practices

See Also

Graph View

Endpoint​

Request Body​

Required Fields​

Optional Fields​

Identifiers​

File Upload (digital content only)​

Pricing​

Access Settings​

Marketplace​

Metadata​

Geographic Restrictions​

Physical Product Fields​

Request Examples​

Basic PDF Content​

EPUB with Full Metadata​

Content with Multiple Identifiers​

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 Identifier (422)​

File Processing Error (422)​

Authentication Error (401)​

Common Validation Rules​

Best Practices​

See Also​

Graph View

Endpoint

Request Body

Required Fields

Optional Fields

Identifiers

File Upload (digital content only)

Pricing

Access Settings

Marketplace

Metadata

Geographic Restrictions

Physical Product Fields

Request Examples

Basic PDF Content

EPUB with Full Metadata

Content with Multiple Identifiers

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 Identifier (422)

File Processing Error (422)

Authentication Error (401)

Common Validation Rules

Best Practices

See Also