> ## 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.

# Content Sharing

Distribute content to other tenants' catalogs using the `share_with_tenants_ids` field. This allows a content owner to make their content available in other tenants' stores without duplicating the content item.

---

## How It Works

1. The **content owner** sets `share_with_tenants_ids` on a content item with an array of target tenant IDs.
2. Each **receiving tenant** gets a read-only catalog entry for that content.
3. The receiving tenant can list and view the shared content but cannot modify or delete it.
4. The owner can update or remove sharing at any time by changing the `share_with_tenants_ids` array.

---

## Using `share_with_tenants_ids`

The `share_with_tenants_ids` field is available on the [Create Content](./content-v3-create.md) and [Update Content](./content-v3-update.md) endpoints.

| Behavior           | Description                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **Availability**   | Create and Update endpoints only (not supported in [Bulk Operations](./content-v3-bulk.md)) |
| **Type**           | Array of string tenant IDs                                                                  |
| **Replacement**    | Full replacement — the array you send replaces the current sharing list                     |
| **Remove sharing** | Send an empty array `[]` to remove all sharing                                              |
| **Owner-only**     | Only the content owner can manage sharing (403 if not owner)                                |

:::warning Full Replacement
The `share_with_tenants_ids` array is **not merged** with existing values. Every update replaces the entire sharing list. To add a new tenant, include all previously shared tenant IDs plus the new one.
:::

---

## Request Examples

### Share During Creation

```bash
curl -X POST "https://yourstore.publica.la/api/v3/content" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shared Publication",
    "file_type": "pdf",
    "lang": "en",
    "external_id": "SHARED-001",
    "file_url": "https://example.com/files/shared-pub.pdf",
    "share_with_tenants_ids": ["42", "87", "153"]
  }'
```

### Update Sharing List

Add or change which tenants receive the content. Remember this replaces the full list.

```bash
curl -X PUT "https://yourstore.publica.la/api/v3/content/468170" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "share_with_tenants_ids": ["42", "87", "153", "201"]
  }'
```

### Remove All Sharing

```bash
curl -X PUT "https://yourstore.publica.la/api/v3/content/468170" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "share_with_tenants_ids": []
  }'
```

---

## Permissions & Restrictions

| Rule                         | Details                                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Owner-only**               | Only the content owner can set or change `share_with_tenants_ids`                                                   |
| **Target tenant validation** | Target tenant must have share permission (check with support) or be an aggregated tenant, a sub-tenant of the owner |
| **Invalid IDs**              | Invalid or unauthorized tenant IDs are silently skipped (not rejected)                                              |
| **Non-owner update**         | Returns `403 Forbidden` if a non-owner tenant attempts to manage sharing                                            |

---

## Behavior for Receiving Tenant

When content is shared with a tenant:

- The content **appears in their catalog** (returned by [List Content](./content-v3-list.md) and [Get Content](./content-v3-get.md) endpoints).
- The content is **read-only**: the receiving tenant cannot update or delete it. Attempting to do so returns `403 Forbidden`.
- **Access settings** (free, preview, require_login) are copied from the owner's configuration.

---

## Withdrawal Behavior

When a tenant ID is removed from the `share_with_tenants_ids` array:

- The content is **withdrawn from that tenant's catalog** and is no longer available for new purchases.
- Users who **already purchased or were assigned** the content retain their access.
- The content stops appearing in catalog listings (via plans) for that tenant.

---

## See Also

- [Create Content](./content-v3-create.md) - Add new content with sharing
- [Update Content](./content-v3-update.md) - Modify sharing on existing content
- [Bulk Share Collections](./content-v3-bulk-share.md) - Share whole collections with up to 50 tenants in one call
- [Overview](./content-v3-overview.md) - API overview

---