Send to AI

Bulk Operations

Create multiple content items in a single API call. Files are not processed immediately, processing is triggered on-demand when a user accesses the content (publication page or reader).

When to Use Bulk Operations

Catalog imports: Migrating content from another system
ONIX synchronization: Batch ingestion from publisher feeds
Mass uploads: Adding multiple titles at once
Scheduled releases: Publishing multiple items simultaneously

Creating Content in Bulk

Endpoint

POST /api/v3/content/bulk

Request Body

{
  "contents": [
    {
      "name": "Book Title One",
      "file_type": "pdf",
      "lang": "en",
      "external_id": "9781234567890",
      "file_url": "https://example.com/files/book1.pdf"
    },
    {
      "name": "Book Title Two",
      "file_type": "epub",
      "lang": "en",
      "external_id": "9780987654321",
      "file_url": "https://example.com/files/book2.epub"
    }
  ]
}

Request Structure

Field	Type	Description
`contents`	array	Array of content objects (1-100 items)

Each content object supports the same fields as individual creation. See Create Content for all available fields.

Bulk Limitations

share_with_tenants_ids is not supported in bulk operations. See Content Sharing for sharing content across tenants.

Limits

Limit	Value
Maximum items per request	100
Minimum items per request	1

Request Examples

Bulk PDF Import

curl -X POST "https://yourstore.publica.la/api/v3/content/bulk" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "name": "Introduction to Data Science",
        "file_type": "pdf",
        "lang": "en",
        "external_id": "9781111111111",
        "file_url": "https://example.com/files/data-science.pdf",
        "prices": [{ "currency_id": "USD", "amount": 29.99 }],
        "author": ["Jane Smith"],
        "publisher": ["Tech Publishing"]
      },
      {
        "name": "Machine Learning Basics",
        "file_type": "pdf",
        "lang": "en",
        "external_id": "9782222222222",
        "file_url": "https://example.com/files/ml-basics.pdf",
        "prices": [{ "currency_id": "USD", "amount": 24.99 }],
        "author": ["John Doe"],
        "publisher": ["Tech Publishing"]
      },
      {
        "name": "Deep Learning Advanced",
        "file_type": "pdf",
        "lang": "en",
        "external_id": "9783333333333",
        "file_url": "https://example.com/files/deep-learning.pdf",
        "prices": [{ "currency_id": "USD", "amount": 34.99 }],
        "author": ["Alice Johnson"],
        "publisher": ["Tech Publishing"]
      }
    ]
  }'

Mixed Content Types

curl -X POST "https://yourstore.publica.la/api/v3/content/bulk" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "name": "Mystery Novel",
        "file_type": "epub",
        "lang": "en",
        "external_id": "EPUB-001",
        "file_url": "https://example.com/files/mystery.epub",
        "prices": [{ "currency_id": "USD", "amount": 12.99 }]
      },
      {
        "name": "Mystery Novel - Audiobook",
        "file_type": "audio",
        "lang": "en",
        "external_id": "AUDIO-001",
        "prices": [{ "currency_id": "USD", "amount": 19.99 }]
      },
      {
        "name": "Mystery Novel - Hardcover",
        "file_type": "physical",
        "lang": "en",
        "external_id": "PHYSICAL-001",
        "prices": [{ "currency_id": "USD", "amount": 24.99 }],
        "binding_type": "hardcover",
        "pages": 320,
        "stock": true
      }
    ]
  }'

With Complete Metadata

curl -X POST "https://yourstore.publica.la/api/v3/content/bulk" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "name": "Complete Guide to Investing",
        "file_type": "pdf",
        "lang": "en",
        "external_id": "9784444444444",
        "file_url": "https://example.com/files/investing.pdf",
        "cover_url": "https://example.com/covers/investing.jpg",
        "description": "<p>A comprehensive guide to personal finance...</p>",
        "published_at": "2025-01-15",
        "prices": [
          { "currency_id": "USD", "amount": 19.99 },
          { "currency_id": "EUR", "amount": 17.99 }
        ],
        "author": ["Finance Expert"],
        "publisher": ["Business Books Inc"],
        "keywords": ["investing", "finance", "money"],
        "bisac": [{ "code": "BUS036000" }],
        "preview": true
      },
      {
        "name": "Retirement Planning Essentials",
        "file_type": "pdf",
        "lang": "en",
        "external_id": "9785555555555",
        "file_url": "https://example.com/files/retirement.pdf",
        "cover_url": "https://example.com/covers/retirement.jpg",
        "description": "<p>Everything you need to know about retirement...</p>",
        "published_at": "2025-02-01",
        "prices": [
          { "currency_id": "USD", "amount": 14.99 },
          { "currency_id": "EUR", "amount": 12.99 }
        ],
        "author": ["Finance Expert"],
        "publisher": ["Business Books Inc"],
        "keywords": ["retirement", "planning", "savings"],
        "bisac": [{ "code": "BUS050000" }],
        "preview": true
      }
    ]
  }'

Response

Success Response (200 OK)

{
  "data": {
    "total": 3,
    "created": 3,
    "failed": 0,
    "contents": [
      {
        "id": "468170",
        "external_id": "9781111111111",
        "name": "Introduction to Data Science"
      },
      {
        "id": "468171",
        "external_id": "9782222222222",
        "name": "Machine Learning Basics"
      },
      {
        "id": "468172",
        "external_id": "9783333333333",
        "name": "Deep Learning Advanced"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`total`	integer	Total number of items in request
`created`	integer	Number of successfully created items
`failed`	integer	Number of failed items
`contents`	array	Created content with `id`, `external_id`, `name`
`errors`	array	Only present if there are failures

Retrieving Full Details

The bulk response returns minimal data for performance. Use Get Content or List Content to get full details after creation.

Deferred Processing

Bulk-created content uses deferred file processing. Files are not processed until a user accesses the content. The first access to the publication page or reader triggers file processing.

Partial Success Handling

Bulk operations support partial success. Some items may succeed while others fail:

{
  "data": {
    "total": 3,
    "created": 2,
    "failed": 1,
    "contents": [
      {
        "id": "468170",
        "external_id": "9781111111111",
        "name": "Introduction to Data Science"
      },
      {
        "id": "468172",
        "external_id": "9783333333333",
        "name": "Deep Learning Advanced"
      }
    ],
    "errors": [
      {
        "index": 1,
        "external_id": "9782222222222",
        "error": "The external id has already been taken."
      }
    ]
  }
}

Partial Success

Successfully validated items are created even if other items in the batch fail. Check the failed count and errors array to identify and retry failed items.

Error Handling

Validation Errors (422)

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

Too Many Items (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "contents": ["The contents may not have more than 100 items."]
  }
}

Common Error Causes

Error	Cause
`contents field is required`	Missing `contents` array
`contents must be an array`	`contents` is not an array
`contents may not have more than 100 items`	Exceeded 100 item limit
`contents.N.name is required`	Item at index N missing name
`contents.N.file_type is invalid`	Invalid file type at index N
`contents.N.external_id has already been taken`	Duplicate external ID
`contents.N.file_url is not accessible`	Cannot download from URL

Best Practices

external_id must be unique per tenant - Duplicate external IDs within the same batch or against existing content will fail for that item
Bulk-created content uses deferred file processing - Files are not processed until a user first accesses the content (publication page or reader). Use Get Content to check conversion_status if needed

Performance Considerations

Aspect	Recommendation
Batch size	Use 50-100 items for optimal throughput
File URLs	Use fast, reliable CDN URLs for file downloads
Retry logic	Implement exponential backoff for rate limiting
Parallel requests	Avoid parallel bulk requests; process sequentially
Timeout	Allow 60+ seconds for large batches with files

Use Cases

Publisher Catalog Import

Import titles from an ONIX feed or catalog:

{
  "contents": [
    {
      "name": "Spring 2025 Catalog Title 1",
      "file_type": "epub",
      "lang": "en",
      "external_id": "ISBN-9781111111111",
      "file_url": "https://publisher-cdn.com/files/title1.epub",
      "cover_url": "https://publisher-cdn.com/covers/title1.jpg",
      "prices": [{ "currency_id": "USD", "amount": 14.99 }],
      "author": ["Author Name"],
      "publisher": ["Publisher Name"],
      "published_at": "2025-03-15",
      "bisac": [{ "code": "FIC000000" }]
    }
  ]
}

Format Group Creation

Create multiple formats of the same title:

{
  "contents": [
    {
      "name": "Complete JavaScript Guide - EPUB",
      "file_type": "epub",
      "lang": "en",
      "external_id": "JS-GUIDE-EPUB",
      "file_url": "https://example.com/js-guide.epub"
    },
    {
      "name": "Complete JavaScript Guide - PDF",
      "file_type": "pdf",
      "lang": "en",
      "external_id": "JS-GUIDE-PDF",
      "file_url": "https://example.com/js-guide.pdf"
    },
    {
      "name": "Complete JavaScript Guide - Audio",
      "file_type": "audio",
      "lang": "en",
      "external_id": "JS-GUIDE-AUDIO"
    }
  ]
}

Free Content Distribution

Add promotional or sample content:

{
  "contents": [
    {
      "name": "Sample Chapter - Book One",
      "file_type": "pdf",
      "lang": "en",
      "external_id": "SAMPLE-001",
      "file_url": "https://example.com/samples/book1-ch1.pdf",
      "free": true,
      "free_until": "2025-12-31"
    },
    {
      "name": "Sample Chapter - Book Two",
      "file_type": "pdf",
      "lang": "en",
      "external_id": "SAMPLE-002",
      "file_url": "https://example.com/samples/book2-ch1.pdf",
      "free": true,
      "free_until": "2025-12-31"
    }
  ]
}

Bulk Operations

When to Use Bulk Operations

Creating Content in Bulk

Endpoint

Request Body

Request Structure

Limits

Request Examples

Bulk PDF Import

Mixed Content Types

With Complete Metadata

Response

Success Response (200 OK)

Response Fields

Partial Success Handling

Error Handling

Validation Errors (422)

Too Many Items (422)

Common Error Causes

Best Practices

Performance Considerations

Use Cases

Publisher Catalog Import

Format Group Creation

Free Content Distribution

See Also

Graph View

When to Use Bulk Operations​

Creating Content in Bulk​

Endpoint​

Request Body​

Request Structure​

Limits​

Request Examples​

Bulk PDF Import​

Mixed Content Types​

With Complete Metadata​

Response​

Success Response (200 OK)​

Response Fields​

Partial Success Handling​

Error Handling​

Validation Errors (422)​

Too Many Items (422)​

Common Error Causes​

Best Practices​

Performance Considerations​

Use Cases​

Publisher Catalog Import​

Format Group Creation​

Free Content Distribution​

See Also​

Graph View

When to Use Bulk Operations

Creating Content in Bulk

Endpoint

Request Body

Request Structure

Limits

Request Examples

Bulk PDF Import

Mixed Content Types

With Complete Metadata

Response

Success Response (200 OK)

Response Fields

Partial Success Handling

Error Handling

Validation Errors (422)

Too Many Items (422)

Common Error Causes

Best Practices

Performance Considerations

Use Cases

Publisher Catalog Import

Format Group Creation

Free Content Distribution

See Also