# Conversation shares: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/conversation-shares
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 3.

## GET /v1/conversations/{conversationId}/shares

Operation id: `list_conversation_shares`

**List the share links of a conversation**

Returns every share link you created for one conversation, newest first, including revoked and expired ones (check `active`). `meta.count` is the number of shares returned and `meta.active_count` how many of them currently work. A conversation that is not yours, or does not exist, answers `200` with an empty list.

Access: API key required; free and paid accounts. Cost: no token cost.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `conversationId` | path | string | yes | The conversation id, for example `3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01`. Allowed: at least 1 character. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `[].id` | string | Identifier of the share. Use it to revoke the share. |
| `[].token` | string | The secret in the link. Anyone who has it can read the conversation until the share is revoked or expires. |
| `[].public_url` | string | Path of the public page, to append to `https://www.scarleta.ai`. |
| `[].conversation_id` | string | The shared conversation. |
| `[].expires_at` | integer \| null | When the link stops working, in milliseconds since the Unix epoch; null when it never expires. Allowed: -9007199254740991 to 9007199254740991. |
| `[].revoked_at` | integer \| null | When the share was revoked, in milliseconds since the Unix epoch; null while it is not revoked. Allowed: -9007199254740991 to 9007199254740991. |
| `[].created_at` | integer | When the share was created, in milliseconds since the Unix epoch. Allowed: -9007199254740991 to 9007199254740991. |
| `[].active` | boolean | True when the link currently works: not revoked and not expired. |

### Responses

200: `meta.request_id` is present.

```json
{
  "data": [
    {
      "id": "9b1e5c7a-2d3f-4a68-b0c4-7e8f9a0b1c2d",
      "token": "example-share-token",
      "public_url": "/share/chat/example-share-token",
      "conversation_id": "3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01",
      "expires_at": null,
      "revoked_at": null,
      "created_at": 1792554097272,
      "active": true
    }
  ],
  "meta": {
    "request_id": "0cf07e8d-6f86-47b3-8a35-35499a651571",
    "count": 1,
    "active_count": 1
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

429: Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`list_failed`](https://www.scarleta.ai/docs/errors#list_failed), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`missing_conversation_id`](https://www.scarleta.ai/docs/errors#missing_conversation_id), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
CONVERSATIONID="YOUR_CONVERSATIONID"
curl "https://api.scarleta.ai/v1/conversations/$CONVERSATIONID/shares" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## POST /v1/conversations/{conversationId}/shares

Operation id: `create_conversation_share`

**Create a share link for a conversation**

Creates a public link to one of your conversations and returns it with `201`. Anyone who has the link can read the conversation without an API key, so treat `token` like a password and revoke the share when it is no longer needed. Open the link at `https://www.scarleta.ai` followed by `public_url`. The link never expires unless you send `expires_in_seconds`. The request body is optional; send none to create a link that does not expire. Each call creates a new link; list them with `GET /v1/conversations/{conversationId}/shares`.

Access: API key required; free and paid accounts. Cost: no token cost.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `conversationId` | path | string | yes | The conversation id, for example `3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01`. Allowed: at least 1 character. |

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `expires_in_seconds` | number | How long the link works, in seconds, from now. Send a JSON number of at least 1, at most 315360000; fractions are rounded down, so a value below 1 gives a link that is already expired. Leave it out for a link that does not expire. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the share. Use it to revoke the share. |
| `token` | string | The secret in the link. Anyone who has it can read the conversation until the share is revoked or expires. |
| `public_url` | string | Path of the public page, to append to `https://www.scarleta.ai`. |
| `conversation_id` | string | The shared conversation. |
| `expires_at` | integer \| null | When the link stops working, in milliseconds since the Unix epoch; null when it never expires. Allowed: -9007199254740991 to 9007199254740991. |
| `revoked_at` | integer \| null | When the share was revoked, in milliseconds since the Unix epoch; null while it is not revoked. Allowed: -9007199254740991 to 9007199254740991. |
| `created_at` | integer | When the share was created, in milliseconds since the Unix epoch. Allowed: -9007199254740991 to 9007199254740991. |
| `active` | boolean | True when the link currently works: not revoked and not expired. |

### Responses

201: Created. `meta.request_id` is present.

```json
{
  "data": {
    "id": "9b1e5c7a-2d3f-4a68-b0c4-7e8f9a0b1c2d",
    "token": "example-share-token",
    "public_url": "/share/chat/example-share-token",
    "conversation_id": "3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01",
    "expires_at": null,
    "revoked_at": null,
    "created_at": 1792554097272,
    "active": true
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is not valid JSON (`invalid_json`), or `expires_in_seconds` is not a positive number within the limit (`invalid_expiry`).

```json
{
  "error": {
    "code": "invalid_expiry",
    "message": "expires_in_seconds must be a positive number of seconds",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_expiry"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

404: You do not own this conversation, or it does not exist.

```json
{
  "error": {
    "code": "not_found",
    "message": "Conversation 3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01 not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#not_found"
  }
}
```

429: Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_expiry`](https://www.scarleta.ai/docs/errors#invalid_expiry), [`invalid_json`](https://www.scarleta.ai/docs/errors#invalid_json), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`mint_failed`](https://www.scarleta.ai/docs/errors#mint_failed), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`missing_conversation_id`](https://www.scarleta.ai/docs/errors#missing_conversation_id), [`not_found`](https://www.scarleta.ai/docs/errors#not_found), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
CONVERSATIONID="YOUR_CONVERSATIONID"
curl -X POST "https://api.scarleta.ai/v1/conversations/$CONVERSATIONID/shares" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_seconds": 3600
  }'
```

## DELETE /v1/conversations/{conversationId}/shares/{shareId}

Operation id: `revoke_conversation_share`

**Revoke a share link**

Turns a share link off right away: the public page stops working and `revoked_at` is set. The share stays in `GET /v1/conversations/{conversationId}/shares` with `active: false`. A revoked link cannot be turned back on; create a new one instead. Revoking a share that is already revoked answers `404 not_found`.

Access: API key required; free and paid accounts. Cost: no token cost.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `conversationId` | path | string | yes | The conversation id, for example `3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01`. Allowed: at least 1 character. |
| `shareId` | path | string | yes | The share id (the `id` of a share, not its `token`), for example `9b1e5c7a-2d3f-4a68-b0c4-7e8f9a0b1c2d`. Allowed: at least 1 character. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the share. Use it to revoke the share. |
| `token` | string | The secret in the link. Anyone who has it can read the conversation until the share is revoked or expires. |
| `public_url` | string | Path of the public page, to append to `https://www.scarleta.ai`. |
| `conversation_id` | string | The shared conversation. |
| `expires_at` | integer \| null | When the link stops working, in milliseconds since the Unix epoch; null when it never expires. Allowed: -9007199254740991 to 9007199254740991. |
| `revoked_at` | integer \| null | When the share was revoked, in milliseconds since the Unix epoch; null while it is not revoked. Allowed: -9007199254740991 to 9007199254740991. |
| `created_at` | integer | When the share was created, in milliseconds since the Unix epoch. Allowed: -9007199254740991 to 9007199254740991. |
| `active` | boolean | True when the link currently works: not revoked and not expired. |

### Responses

200: Revoked. `meta.request_id` is present.

```json
{
  "data": {
    "id": "9b1e5c7a-2d3f-4a68-b0c4-7e8f9a0b1c2d",
    "token": "example-share-token",
    "public_url": "/share/chat/example-share-token",
    "conversation_id": "3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01",
    "expires_at": null,
    "revoked_at": 1792554157272,
    "created_at": 1792554097272,
    "active": false
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

401: Missing, malformed, unknown or revoked API key.

```json
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid or revoked API key",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_key"
  }
}
```

404: The share does not exist, is not yours, or is already revoked.

```json
{
  "error": {
    "code": "not_found",
    "message": "Share 9b1e5c7a-2d3f-4a68-b0c4-7e8f9a0b1c2d not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#not_found"
  }
}
```

429: Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#rate_limit_exceeded"
  }
}
```

503: Temporary platform condition; retry shortly.

```json
{
  "error": {
    "code": "auth_unavailable",
    "message": "Authentication service temporarily unavailable",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#auth_unavailable"
  }
}
```

### Error codes

[`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_key`](https://www.scarleta.ai/docs/errors#invalid_key), [`invalid_key_format`](https://www.scarleta.ai/docs/errors#invalid_key_format), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`missing_conversation_id`](https://www.scarleta.ai/docs/errors#missing_conversation_id), [`missing_share_id`](https://www.scarleta.ai/docs/errors#missing_share_id), [`not_found`](https://www.scarleta.ai/docs/errors#not_found), [`rate_limit_exceeded`](https://www.scarleta.ai/docs/errors#rate_limit_exceeded), [`rate_limit_unavailable`](https://www.scarleta.ai/docs/errors#rate_limit_unavailable), [`revoke_failed`](https://www.scarleta.ai/docs/errors#revoke_failed), [`unauthorized`](https://www.scarleta.ai/docs/errors#unauthorized)

### Example

```bash
CONVERSATIONID="YOUR_CONVERSATIONID"
SHAREID="YOUR_SHAREID"
curl -X DELETE "https://api.scarleta.ai/v1/conversations/$CONVERSATIONID/shares/$SHAREID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```