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 lookup by primary identifier value
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",
    "subtitle": "Interviews spanning five decades",
    "publication_place": "Jackson, MS",
    "edition_year": 2019,
    "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",
    "identifiers": [
      {
        "type": "isbn_digital",
        "value": "978-1-496-82248-2",
        "is_primary": true
      }
    ]
  }
}

Identifiers Always Included

The identifiers array is always present in every response. You do not need to request it via the include parameter.

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",
    "subtitle": "Interviews spanning five decades",
    "publication_place": "Jackson, MS",
    "edition_year": 2019,
    "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": [],
    "thema": ["DSB"],
    "series": [],
    "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,
    "identifiers": [
      {
        "type": "isbn_digital",
        "value": "978-1-496-82248-2",
        "is_primary": true
      },
      {
        "type": "ddc",
        "value": "811.54",
        "is_primary": false
      }
    ]
  }
}

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",
    "subtitle": null,
    "publication_place": null,
    "edition_year": 2025,
    "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": [],
    "thema": [],
    "series": [],
    "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	Deprecated. Synced from primary identifier value. Use identifiers instead. Will be removed in a future version.
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
subtitle	string	Content subtitle
publication_place	string	Place of publication
edition_year	integer	Edition year (4 digits)
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
thema	array	Thema subject codes
series	array	Series 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

Identifiers (always included)

The identifiers array is always present in every response. It contains the identifier objects associated with the content.

Field	Type	Description
type	string	Identifier type: isbn_digital, isbn_printed, uuid, ddc, external_id
value	string	Identifier value
is_primary	boolean	Whether this is the primary identifier. The primary identifier value is synced to external_id

Identifier Types

Type	Description	Example
isbn_digital	ISBN-10 or ISBN-13 for digital editions	978-0-306-40615-7, 0306406152
isbn_printed	ISBN-10 or ISBN-13 for printed editions	978-3-16-148410-0
uuid	UUID (any standard version)	f47ac10b-58cc-4372-a567-0e02b2c3d479
ddc	Dewey Decimal Classification	823.914
external_id	Generic external identifiers	BOOK-001

Types isbn_digital, isbn_printed, uuid, and external_id require tenant-level uniqueness. Two different content items in the same store cannot share the same identifier of these types (regardless of which is primary). The ddc type does not require uniqueness.

---

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

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

---

See Also

• List Content - Query multiple content items
• Create Content - Add new content
• Update Content - Modify content
• Overview - API overview

---