> ## Documentation Index > Fetch the complete documentation index at: https://docs.publica.la/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```json { "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 }, "subscribers_only": false, "conversion_status": "done", "identifiers": [ { "type": "isbn_digital", "value": "978-1-496-82248-2", "is_primary": true } ] } } ``` :::info 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`: ```json { "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 }, "subscribers_only": 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 ```json { "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 }, "subscribers_only": 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 | | `subscribers_only` | boolean | Whether content is restricted to subscribers (see [Subscribers-Only Access](./content-v3-create.md#subscribers-only-access)) | | `conversion_status` | string | File processing status (see [Conversion Status](./content-v3-create.md#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` | :::info 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. ::: ### Physical Stock (physical content only) Content with `file_type: physical` carries two extra fields. They are always present for those items and are never returned for any other content type, regardless of `include`. | Field | Type | Description | | ---------------- | ------------- | ---------------------------------------------------------------------------------------------------- | | `stock_quantity` | integer\|null | Units available for sale. `null` means the store does not track stock for this product | | `stock` | boolean\|null | **Deprecated.** Mirrors `stock_quantity` (`false` when it reaches `0`). Use `stock_quantity` instead | A product is sold out, and cannot be bought, when `stock_quantity` is `0`. A `null` quantity is untracked, not sold out: the product stays on sale. ```json { "id": "468166", "name": "Mystery Novel - Hardcover", "file_type": "physical", "stock_quantity": 48, "stock": true } ``` --- ## Examples ### Get by Internal ID ```bash 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) ```bash curl -X GET "https://yourstore.publica.la/api/v3/content/9781496822482?id_type=external" \ -H "X-User-Token: your-api-token" ``` ### With Includes ```bash curl -X GET "https://yourstore.publica.la/api/v3/content/468166?include=prices,description,metadata" \ -H "X-User-Token: your-api-token" ``` ### Sparse Fieldsets ```bash 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 ```bash 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) ```json { "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) ```json { "message": "Requested include(s) are not allowed. Allowed include(s) are: prices, description, metadata, geographic_restrictions" } ``` ### Authentication Error (401) ```json { "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](./content-v3-list.md) - Query multiple content items - [Create Content](./content-v3-create.md) - Add new content - [Update Content](./content-v3-update.md) - Modify content - [Overview](./content-v3-overview.md) - API overview ---