# Shares: Scarleta API reference

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

## GET /v1/audio/{audioId}/shares

Operation id: `list_audio_shares`

**List the share links of a file**

Returns every link you created for one file, newest first, including revoked and expired ones (check `active`). A file that is not yours simply has none. On success this route answers `{ data, meta }`, and `meta.request_id` is not the id used in error bodies; errors use the standard error body.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or file id of one of your files. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `[].id` | string | Identifier of the share. |
| `[].token` | string | The secret part of the link. Anyone with the link can open the file, so treat it like a password. |
| `[].public_url` | string | Path of the public page: `/share/<token>` on www.scarleta.ai. |
| `[].audio_id` | string |   |
| `[].allow_download` | boolean | True when visitors may download the file. |
| `[].include_analyses` | boolean | True when visitors also see the analysis results. |
| `[].expires_at` | number \| null | When the link stops working, in milliseconds since the Unix epoch; null for a link that never expires. |
| `[].revoked_at` | number \| null | When you revoked the link, in milliseconds since the Unix epoch, or null. |
| `[].created_at` | number | Milliseconds since the Unix epoch. |
| `[].active` | boolean | False once the link is revoked or has expired. |

### Responses

200: The links, newest first.

```json
{
  "data": [
    {
      "id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
      "token": "example-share-token",
      "public_url": "/share/example-share-token",
      "audio_id": "audio_3f9c1a7d2b60",
      "allow_download": false,
      "include_analyses": false,
      "expires_at": null,
      "revoked_at": null,
      "created_at": 1791333870854,
      "active": true
    }
  ],
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03",
    "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 or the per-minute cap of this route. 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), [`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
AUDIOID="YOUR_AUDIOID"
curl "https://api.scarleta.ai/v1/audio/$AUDIOID/shares" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```

## POST /v1/audio/{audioId}/shares

Operation id: `create_audio_share`

**Create a public share link for a file**

Creates a link that lets anyone open one of your files without an account. The defaults are the most private: no download and no analysis results. Send `expires_in_seconds` for a link that stops working, otherwise it never expires. The body is optional; an empty body uses the defaults. `expires_in_seconds` must be positive and at most 315360000. A file that is not yours, or does not exist, is 404 `not_found`. On success this route answers `{ data, meta }`, and `meta.request_id` is not the id used in error bodies; errors use the standard error body.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or file id of one of your files. |

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `expires_in_seconds` | number | Seconds until the link stops working, above 0 and at most 315360000. Omit for a link that never expires. |
| `allow_download` | boolean | True lets visitors download the file. Defaults to false. |
| `include_analyses` | boolean | True shows visitors the analysis results. Defaults to false. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the share. |
| `token` | string | The secret part of the link. Anyone with the link can open the file, so treat it like a password. |
| `public_url` | string | Path of the public page: `/share/<token>` on www.scarleta.ai. |
| `audio_id` | string |   |
| `allow_download` | boolean | True when visitors may download the file. |
| `include_analyses` | boolean | True when visitors also see the analysis results. |
| `expires_at` | number \| null | When the link stops working, in milliseconds since the Unix epoch; null for a link that never expires. |
| `revoked_at` | number \| null | When you revoked the link, in milliseconds since the Unix epoch, or null. |
| `created_at` | number | Milliseconds since the Unix epoch. |
| `active` | boolean | False once the link is revoked or has expired. |

### Responses

201: The link was created.

```json
{
  "data": {
    "id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
    "token": "example-share-token",
    "public_url": "/share/example-share-token",
    "audio_id": "audio_3f9c1a7d2b60",
    "allow_download": false,
    "include_analyses": false,
    "expires_at": null,
    "revoked_at": null,
    "created_at": 1791333870854,
    "active": true
  },
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03"
  }
}
```

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: The file does not exist in your library.

```json
{
  "error": {
    "code": "not_found",
    "message": "Version audio_0123456789ab 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 or the per-minute cap of this route. 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), [`missing_api_key`](https://www.scarleta.ai/docs/errors#missing_api_key), [`missing_auth`](https://www.scarleta.ai/docs/errors#missing_auth), [`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
AUDIOID="YOUR_AUDIOID"
curl -X POST "https://api.scarleta.ai/v1/audio/$AUDIOID/shares" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in_seconds": 3600,
    "allow_download": false,
    "include_analyses": false
  }'
```

## DELETE /v1/audio/{audioId}/shares/{shareId}

Operation id: `revoke_audio_share`

**Revoke a share link**

Stops a link from working. The answer is the link with `revoked_at` set and `active` false. Revoking a link twice, a link that is not yours, or an id that is not a UUID is 404 `not_found`. On success this route answers `{ data, meta }`, and `meta.request_id` is not the id used in error bodies; errors use the standard error body.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audioId` | path | string | yes | The `audio_id` or file id of one of your files. |
| `shareId` | path | string | yes | The `id` of the share. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier of the share. |
| `token` | string | The secret part of the link. Anyone with the link can open the file, so treat it like a password. |
| `public_url` | string | Path of the public page: `/share/<token>` on www.scarleta.ai. |
| `audio_id` | string |   |
| `allow_download` | boolean | True when visitors may download the file. |
| `include_analyses` | boolean | True when visitors also see the analysis results. |
| `expires_at` | number \| null | When the link stops working, in milliseconds since the Unix epoch; null for a link that never expires. |
| `revoked_at` | number \| null | When you revoked the link, in milliseconds since the Unix epoch, or null. |
| `created_at` | number | Milliseconds since the Unix epoch. |
| `active` | boolean | False once the link is revoked or has expired. |

### Responses

200: The link is revoked.

```json
{
  "data": {
    "id": "7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52",
    "token": "example-share-token",
    "public_url": "/share/example-share-token",
    "audio_id": "audio_3f9c1a7d2b60",
    "allow_download": false,
    "include_analyses": false,
    "expires_at": null,
    "revoked_at": 1791333930854,
    "created_at": 1791333870854,
    "active": false
  },
  "meta": {
    "request_id": "1f6c2a9e-3b47-4d58-9a10-6e2d8c4b7f03"
  }
}
```

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 link does not exist, is already revoked, or is not yours.

```json
{
  "error": {
    "code": "not_found",
    "message": "Share 7d2c9e1a-4b3f-4c68-9a5d-1e0f8b7c6a52 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 or the per-minute cap of this route. 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), [`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
AUDIOID="YOUR_AUDIOID"
SHAREID="YOUR_SHAREID"
curl -X DELETE "https://api.scarleta.ai/v1/audio/$AUDIOID/shares/$SHAREID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```