Bulk Share Collections

Share every owned content item that belongs to one or more collections with a list of target tenants in a single API call. The endpoint validates the request synchronously and queues the sharing work in the background.

For per-item sharing using the share_with_tenants_ids field, see Content Sharing.

---

Endpoint

POST /api/v3/content/share

Headers

Header	Required	Description
X-User-Token	Yes	API token of the content owner
Content-Type	Yes	Must be application/json
Accept	No	application/json (recommended)

All requests must use HTTPS.

---

Request Body

{
  "collection_slugs": ["fall-releases-2026", "nonfiction-bestsellers"],
  "tenant_ids": [42, 87, 153]
}

Fields

Field	Type	Required	Description
collection_slugs	array of strings	Yes	Slugs of collections owned by your tenant (1 to 50, max 200 chars)
tenant_ids	array of integers	One of these is required	Internal IDs of the target tenants (1 to 50)
tenant_external_ids	array of strings	One of these is required	External IDs of the target tenants (1 to 50, max 255 chars)

Mutually Exclusive

Send either tenant_ids or tenant_external_ids, never both. Including both fields returns a 422 validation error.

Limits

Limit	Value
Maximum collection slugs per request	50
Maximum target tenants per request	50

The endpoint shares the bulk rate limit bucket with Bulk Operations: 10 requests per minute per API token.

---

How It Works

1. The endpoint validates the request: collection slugs must exist and belong to your tenant, and every target tenant must be authorized to receive shared content.
2. The endpoint queues one background job per target tenant. Each job iterates through the matching content items in chunks and inserts the corresponding catalog entries on the target tenant.
3. The endpoint returns 202 Accepted immediately. Sharing completes asynchronously; the receiving tenant's catalog updates as the jobs run.
4. The endpoint is idempotent: items already shared are skipped, so re-running the same request does not create duplicates.

Owned content only

Only content owned by your tenant is shared. Items that you received as shared from a third-party owner, or that came from the marketplace as retail, are skipped without being reported in the response.

---

Authorized Targets

A target tenant is accepted in two cases:

Case	Description
Aggregated tenants	Tenants that list your tenant as their aggregator
Explicit share permission	Tenants for which you have been granted the content_share permission (configured by support)

Tenants that fall outside both cases are rejected with 422, and the response lists the unauthorized IDs. Validation is all-or-nothing: if any target is unauthorized, no jobs are queued.

---

Request Examples

Share One Collection With One Tenant

curl -X POST "https://yourstore.publica.la/api/v3/content/share" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_slugs": ["fall-releases-2026"],
    "tenant_ids": [42]
  }'

Share Multiple Collections With Multiple Tenants

curl -X POST "https://yourstore.publica.la/api/v3/content/share" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_slugs": ["fall-releases-2026", "nonfiction-bestsellers"],
    "tenant_ids": [42, 87, 153]
  }'

Use External Tenant IDs

curl -X POST "https://yourstore.publica.la/api/v3/content/share" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_slugs": ["fall-releases-2026"],
    "tenant_external_ids": ["partner-store-eu", "partner-store-us"]
  }'

---

Response

Success (202 Accepted)

{
  "queued": true,
  "resolved": {
    "collections": 2,
    "target_tenants": 3
  }
}

Field	Type	Description
queued	boolean	Always true on success; sharing has been scheduled
resolved.collections	integer	Number of collection slugs accepted from the request
resolved.target_tenants	integer	Number of authorized target tenants for which a job was queued

Verifying the Result

The response confirms the request was accepted, not that sharing has finished. Use List Content or Get Content on the receiving tenant to confirm that items have appeared in its catalog.

---

Error Handling

Validation Errors (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "collection_slugs": ["Unknown collection slugs: fall-releases-2026"]
  }
}

{
  "message": "The given data was invalid.",
  "errors": {
    "tenant_ids": ["Not authorized to share with tenants: 87, 153"]
  }
}

Common Validation Causes

Error message	Cause
collection_slugs field is required	Missing collection_slugs array
collection_slugs may not have more than 50 items	Sent more than 50 collection slugs
Unknown collection slugs: ...	One or more slugs do not exist for your tenant or are not collections
tenant_ids field is required when tenant_external_ids is not present	Neither tenant identifier list was provided
tenant_ids field prohibits tenant_external_ids from being present	Both tenant identifier lists were provided
tenant_ids may not have more than 50 items	Sent more than 50 target tenants
Unknown tenant_ids: ...	One or more target IDs do not match an existing tenant
Not authorized to share with tenants: ...	One or more targets are neither aggregated tenants nor have content_share

Authentication Errors (401)

{
  "message": "Unauthenticated."
}

Rate Limit Errors (429)

The endpoint shares the bulk operations rate limiter (10 requests per minute per API token). When exceeded:

{
  "message": "Too Many Attempts."
}

---

See Also

• Content Sharing - Per-item sharing using share_with_tenants_ids
• Bulk Operations - Create up to 50 content items in one request
• List Content - Verify shared items appear in the receiving tenant's catalog
• Overview - API overview

---