API reference

Conversation shares

3 operations. Base URL https://api.scarleta.ai. Select an operation to see its parameters, samples and errors.

Jump to an operation

GET/v1/conversations/{conversationId}/shares

List the share links of a conversation

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

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

Response fields

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.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "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
  }
}

200 `meta.request_id` is present.
401 Missing, malformed, unknown or revoked API key.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Sends this request from your browser to https://api.scarleta.ai with your own key. The key stays in this page only (never saved or put in the address) and is cleared when you leave. Revoke any key you have shared.

Other error codes this operation can return: invalid_auth_format, invalid_key_format, list_failed, missing_api_key, missing_auth, missing_conversation_id, rate_limit_unavailable, unauthorized.

POST/v1/conversations/{conversationId}/shares

Create a share link for a conversation

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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
  }'

Parameters

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

Request body

Name	Type	Required	Description
expires_in_secondsbody	number	Optional	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

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.

Errors

Status	Code	Description
400	invalid_expiry	The body is not valid JSON (`invalid_json`), or `expires_in_seconds` is not a positive number within the limit (`invalid_expiry`).
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	You do not own this conversation, or it does not exist.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "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"
  }
}

201 Created. `meta.request_id` is present.
400 The body is not valid JSON (`invalid_json`), or `expires_in_seconds` is not a positive number within the limit (`invalid_expiry`).
401 Missing, malformed, unknown or revoked API key.
404 You do not own this conversation, or it does not exist.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_json, invalid_key_format, mint_failed, missing_api_key, missing_auth, missing_conversation_id, rate_limit_unavailable, unauthorized.

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

Revoke a share link

Free and paid accounts

API key required
Free and paid accounts
No token cost

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.

Cost. Free of charge.

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

Parameters

Name	Type	Required	Description
conversationIdpath	string	Required	The conversation id, for example `3f9c1d2e-7b44-4c1a-8e0f-5a6b7c8d9e01`. Allowed: at least 1 character.
shareIdpath	string	Required	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

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.

Errors

Status	Code	Description
401	invalid_key	Missing, malformed, unknown or revoked API key.
404	not_found	The share does not exist, is not yours, or is already revoked.
429	rate_limit_exceeded	Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503	auth_unavailable	Temporary platform condition; retry shortly.

Example responses

{
  "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"
  }
}

200 Revoked. `meta.request_id` is present.
401 Missing, malformed, unknown or revoked API key.
404 The share does not exist, is not yours, or is already revoked.
429 Over the account request budget for the hour. Wait for the `Retry-After` header, then retry.
503 Temporary platform condition; retry shortly.

Try it

Other error codes this operation can return: invalid_auth_format, invalid_key_format, missing_api_key, missing_auth, missing_conversation_id, missing_share_id, rate_limit_unavailable, revoke_failed, unauthorized.