Send to AI

Get Content

Retrieve a specific content item by its internal ID or external ID.

Endpoint

GET /api/v3/content/{content_id}

Path Parameters

Parameter	Type	Description
`content_id`	string	Content internal ID or external ID

Query Parameters

Parameter	Type	Default	Description
`id_type`	string	`internal`	`internal` for numeric ID, `external` for external ID (ISBN, SKU)
`include`	string	-	Comma-separated: `prices`, `description`, `metadata`, `geographic_restrictions`
`fields`	string	-	Comma-separated list of fields to return

Response Structure

Base Response

{
  "data": {
    "id": "468166",
    "external_id": "9781496822482",
    "name": "Conversations with Donald Hall",
    "slug": "conversations-with-donald-hall",
    "lang": "en",
    "file_type": "epub",
    "audience": "adult",
    "cover_url": "https://cdn.publica.la/covers/468166.jpg",
    "reader_url": "https://yourstore.publica.la/reader/conversations-with-donald-hall",
    "product_url": "https://yourstore.publica.la/library/publication/conversations-with-donald-hall",
    "created_at": "2021-03-19T00:00:00.000000Z",
    "updated_at": "2025-12-03T15:30:00.000000Z",
    "published_at": "2019-09-13T00:00:00.000000Z",
    "license": "retail",
    "free": {
      "enabled": false,
      "until": null,
      "require_login": false
    },
    "preview": {
      "enabled": true,
      "require_login": false
    },
    "conversion_status": "done"
  }
}

Full Response with All Includes

Request with ?include=prices,description,metadata,geographic_restrictions:

{
  "data": {
    "id": "468166",
    "external_id": "9781496822482",
    "name": "Conversations with Donald Hall",
    "slug": "conversations-with-donald-hall",
    "lang": "en",
    "file_type": "epub",
    "audience": "adult",
    "cover_url": "https://cdn.publica.la/covers/468166.jpg",
    "reader_url": "https://yourstore.publica.la/reader/conversations-with-donald-hall",
    "product_url": "https://yourstore.publica.la/library/publication/conversations-with-donald-hall",
    "created_at": "2021-03-19T00:00:00.000000Z",
    "updated_at": "2025-12-03T15:30:00.000000Z",
    "published_at": "2019-09-13T00:00:00.000000Z",
    "license": "retail",
    "free": {
      "enabled": false,
      "until": null,
      "require_login": false
    },
    "preview": {
      "enabled": true,
      "require_login": false
    },
    "conversion_status": "done",
    "prices": [
      { "currency_id": "USD", "amount": 9.99 },
      { "currency_id": "EUR", "amount": 8.5 }
    ],
    "description": "A comprehensive collection of interviews with Donald Hall spanning his literary career...",
    "publisher": ["University Press of Mississippi"],
    "author": ["Jane Doe", "John Smith"],
    "bisac": [
      {
        "code": "LIT004020",
        "label": "Literary Criticism > American > General"
      }
    ],
    "keywords": ["poetry", "interviews", "american literature"],
    "country": [],
    "edition": [],
    "narrator": [],
    "publishing_group": [],
    "category": ["Literature"],
    "collection": [],
    "metrics": {
      "total_pages": 320,
      "total_words": 85000,
      "total_seconds": 0
    },
    "custom_metadata": {
      "genre": ["Literary Criticism", "American Literature"],
      "reading_level": ["Academic"]
    },
    "geographic_restrictions": null
  }
}

Audiobook Example

{
  "data": {
    "id": "502310",
    "external_id": "AUDIO-978123",
    "name": "The Art of Storytelling",
    "slug": "the-art-of-storytelling",
    "lang": "en",
    "file_type": "audio",
    "audience": "adult",
    "cover_url": "https://cdn.publica.la/covers/502310.jpg",
    "reader_url": "https://yourstore.publica.la/reader/the-art-of-storytelling",
    "product_url": "https://yourstore.publica.la/library/publication/the-art-of-storytelling",
    "created_at": "2025-06-10T00:00:00.000000Z",
    "updated_at": "2025-06-10T12:00:00.000000Z",
    "published_at": "2025-06-01T00:00:00.000000Z",
    "license": "retail",
    "free": {
      "enabled": false,
      "until": null,
      "require_login": false
    },
    "preview": {
      "enabled": false,
      "require_login": false
    },
    "conversion_status": "done",
    "prices": [{ "currency_id": "USD", "amount": 14.99 }],
    "description": "A masterclass in narrative techniques, professionally narrated.",
    "publisher": ["Audiobook Press"],
    "author": ["Sarah Johnson"],
    "bisac": [],
    "keywords": ["storytelling", "narration", "craft"],
    "country": [],
    "edition": [],
    "narrator": ["Michael Adams"],
    "publishing_group": [],
    "category": ["Non-Fiction"],
    "collection": [],
    "metrics": {
      "total_pages": null,
      "total_words": 0,
      "total_seconds": 28800
    },
    "custom_metadata": {},
    "geographic_restrictions": null
  }
}

Field Reference

Core Fields

Field	Type	Description
`id`	string	Content internal ID (numeric as string)
`external_id`	string	External ID (ISBN-13, SKU, or custom)
`name`	string	Content title
`slug`	string	URL-friendly identifier
`lang`	string	Language code (e.g., `en`, `es`)
`file_type`	string	Content type: `pdf`, `epub`, `audio`, `physical`
`audience`	string	Target audience
`cover_url`	string	Cover image URL
`reader_url`	string	Direct reader link
`product_url`	string	Storefront product page URL
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp
`published_at`	string	ISO 8601 publication date
`license`	string	License type: `retail`, `shared`, `owner`
`free`	object	Free access configuration
`preview`	object	Preview access configuration
`conversion_status`	string	File processing status (see Conversion Status)

Free Access Object

Field	Type	Description
`enabled`	boolean	Whether free access is enabled
`until`	string\|null	ISO 8601 free access expiration date
`require_login`	boolean	Whether login is required for free access

Preview Object

Field	Type	Description
`enabled`	boolean	Whether preview is enabled
`require_login`	boolean	Whether login is required for preview

Prices Block (include=prices)

Field	Type	Description
`currency_id`	string	ISO 4217 currency code
`amount`	float	Price amount

Description Block (include=description)

Returns a single description string field with the full content description.

Metadata Block (include=metadata)

Field	Type	Description
`publisher`	array	Publisher names
`author`	array	Author names
`bisac`	array	BISAC classification codes with labels
`keywords`	array	Content keywords/tags
`country`	array	Country names
`edition`	array	Edition names
`narrator`	array	Narrator names (for audiobooks)
`publishing_group`	array	Publishing group names
`category`	array	Category names (tenant-specific)
`collection`	array	Collection names (tenant-specific)
`metrics`	object	Content metrics (total_pages, total_words, total_seconds)
`custom_metadata`	object	Custom taxonomy groups with their assigned values

Geographic Restrictions Block (include=geographic_restrictions)

Value	Description
`null`	No restrictions, available worldwide
`{ included: [...], excluded: [...] }`	Country codes for territorial rights

Examples

Get by Internal ID

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

Get by External ID (ISBN)

curl -X GET "https://yourstore.publica.la/api/v3/content/9781496822482?id_type=external" \
  -H "X-User-Token: your-api-token"

With Includes

curl -X GET "https://yourstore.publica.la/api/v3/content/468166?include=prices,description,metadata" \
  -H "X-User-Token: your-api-token"

Sparse Fieldsets

curl -X GET "https://yourstore.publica.la/api/v3/content/468166?fields=id,name,cover_url,file_type" \
  -H "X-User-Token: your-api-token"

Get by ISBN with Prices Only

curl -X GET "https://yourstore.publica.la/api/v3/content/9781496822482?id_type=external&include=prices&fields=id,name,prices" \
  -H "X-User-Token: your-api-token"

Error Responses

Content Not Found (404)

{
  "message": "Content not found."
}

This occurs when:

The internal ID doesn't exist
The external ID doesn't exist (with id_type=external)
The content does not belong to your store (it may belong to another store)

Invalid Include (422)

{
  "message": "Requested include(s) are not allowed. Allowed include(s) are: prices, description, metadata, geographic_restrictions"
}

Authentication Error (401)

{
  "message": "Unauthenticated."
}

Best Practices

Use external IDs - Store content with ISBN or SKU for easy cross-system lookup
Request only needed includes - Reduce payload size and response time
Cache responses - Content data changes infrequently
Handle 404 gracefully - Content may be deleted or not belong to your store (it may belong to another store)

Get Content

Endpoint

Path Parameters

Query Parameters

Response Structure

Base Response

Full Response with All Includes

Audiobook Example

Field Reference

Core Fields

Free Access Object

Preview Object

Prices Block (include=prices)

Description Block (include=description)

Metadata Block (include=metadata)

Geographic Restrictions Block (include=geographic_restrictions)

Examples

Get by Internal ID

Get by External ID (ISBN)

With Includes

Sparse Fieldsets

Get by ISBN with Prices Only

Error Responses

Content Not Found (404)

Invalid Include (422)

Authentication Error (401)

Best Practices

See Also

Graph View

Endpoint​

Path Parameters​

Query Parameters​

Response Structure​

Base Response​

Full Response with All Includes​

Audiobook Example​

Field Reference​

Core Fields​

Free Access Object​

Preview Object​

Prices Block (include=prices)​

Description Block (include=description)​

Metadata Block (include=metadata)​

Geographic Restrictions Block (include=geographic_restrictions)​

Examples​

Get by Internal ID​

Get by External ID (ISBN)​

With Includes​

Sparse Fieldsets​

Get by ISBN with Prices Only​

Error Responses​

Content Not Found (404)​

Invalid Include (422)​

Authentication Error (401)​

Best Practices​

See Also​

Graph View

Endpoint

Path Parameters

Query Parameters

Response Structure

Base Response

Full Response with All Includes

Audiobook Example

Field Reference

Core Fields

Free Access Object

Preview Object

Prices Block (include=prices)

Description Block (include=description)

Metadata Block (include=metadata)

Geographic Restrictions Block (include=geographic_restrictions)

Examples

Get by Internal ID

Get by External ID (ISBN)

With Includes

Sparse Fieldsets

Get by ISBN with Prices Only

Error Responses

Content Not Found (404)

Invalid Include (422)

Authentication Error (401)

Best Practices

See Also