# Similar sounds: Scarleta API reference

Page: https://www.scarleta.ai/docs/reference/similar-sounds
Base URL: https://api.scarleta.ai. Authentication: `Authorization: Bearer $SCARLETA_API_KEY`.
Operations: 2.

## POST /v1/audio/library/similar

Operation id: `search_similar_files`

**Find files that sound like a file or a link**

Same search as the GET route, with the reference given in the body: send exactly one of `audio_id` or `reference_url` (the address of one of your files, as in an `audio_url`). The reference file needs a sound fingerprint (the embedding analysis). A file you own without one is 409 `embedding_missing`; a file that does not exist or is not yours is 404 `audio_not_found`. A `reference_url` that is not one of your files is 404 `audio_not_found`. `limit` is a whole number from 1 to 100 (default 20); `min_score` is a number from -1 to 1 (default -1, which keeps everything). The search compares only your own files and is exact, so on a large library it can take a moment. Any field the route does not know is 400 `invalid_config`; neither or both references is 400 `invalid_reference`.

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

### Request body

| Field | Type | Description |
| --- | --- | --- |
| `audio_id` | string | The `audio_id` or file id of the reference file. Send this or `reference_url`. |
| `reference_url` | string | The address of the reference file in your library. Send this or `audio_id`. |
| `limit` | integer | How many results to return, 1 to 100. Defaults to 20. |
| `min_score` | number | Leave out files scoring below this, -1 to 1. Defaults to -1. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `reference_audio_id` | string | The file the search compared against. |
| `embedding_model` | string | Name of the fingerprint kind that was compared. Only files with a fingerprint of the same kind can match. |
| `results` | array<object> | Your most similar files, best first. The reference itself is never listed. |
| `results[].audio_id` | string | Registry identifier of the similar file; it starts with `audio_`. |
| `results[].original_filename` | string | Name the file was uploaded under. |
| `results[].display_name` | string \| null | Name you gave the file, or null. |
| `results[].similarity_score` | number | How alike the sound is, from -1 to 1, to four decimals. Higher is closer. |
| `results[].bpm` | number \| null | Tempo of the file, or null when it has none. |
| `results[].key_label` | string \| null | Musical key of the file, for example `A minor`, or null. |
| `results[].analyzed_categories` | array<string> | Analysis categories this file has results for. |
| `count` | integer | Entries in `results`. Allowed: -9007199254740991 to 9007199254740991. |
| `note` | string | A fixed sentence on what similarity means. |

### Responses

200: The closest files, best first.

```json
{
  "data": {
    "reference_audio_id": "audio_3f9c1a7d2b60",
    "embedding_model": "fingerprint-6144",
    "results": [
      {
        "audio_id": "audio_a81e5c40d7f2",
        "original_filename": "demo-mix-2.wav",
        "display_name": null,
        "similarity_score": 0.9312,
        "bpm": 119.8,
        "key_label": "A minor",
        "analyzed_categories": [
          "rhythm",
          "embedding"
        ]
      }
    ],
    "count": 1,
    "note": "Similarity is acoustic character (timbre/texture), not structural or temporal match."
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: The body is not valid JSON (`invalid_json`), has an unknown field (`invalid_config`), does not name exactly one reference (`invalid_reference`), or `limit` / `min_score` is not allowed (`invalid_limit`, `invalid_min_score`).

```json
{
  "error": {
    "code": "invalid_reference",
    "message": "Give exactly one of audio_id or reference_url",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_reference"
  }
}
```

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

```json
{
  "error": {
    "code": "audio_not_found",
    "message": "Audio file not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#audio_not_found"
  }
}
```

409: The reference file has no sound fingerprint yet.

```json
{
  "error": {
    "code": "embedding_missing",
    "message": "Run embedding analysis on this file first.",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#embedding_missing"
  }
}
```

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

[`audio_not_found`](https://www.scarleta.ai/docs/errors#audio_not_found), [`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`embedding_missing`](https://www.scarleta.ai/docs/errors#embedding_missing), [`invalid_auth_format`](https://www.scarleta.ai/docs/errors#invalid_auth_format), [`invalid_config`](https://www.scarleta.ai/docs/errors#invalid_config), [`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), [`invalid_limit`](https://www.scarleta.ai/docs/errors#invalid_limit), [`invalid_min_score`](https://www.scarleta.ai/docs/errors#invalid_min_score), [`invalid_reference`](https://www.scarleta.ai/docs/errors#invalid_reference), [`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
curl -X POST "https://api.scarleta.ai/v1/audio/library/similar" \
  -H "Authorization: Bearer $SCARLETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "audio_3f9c1a7d2b60",
    "limit": 10,
    "min_score": 0.5
  }'
```

## GET /v1/audio/library/similar/{audio_id}

Operation id: `find_similar_files`

**Find files that sound like one of yours**

Returns the files in your library whose sound is closest to the file named in the path (`audio_id` or the file id). The reference file needs a sound fingerprint (the embedding analysis). A file you own without one is 409 `embedding_missing`; a file that does not exist or is not yours is 404 `audio_not_found`. `limit` is a whole number from 1 to 100 (default 20); `min_score` is a number from -1 to 1 (default -1, which keeps everything). The search compares only your own files and is exact, so on a large library it can take a moment. A bad `limit` is 400 `invalid_limit`, a bad `min_score` 400 `invalid_min_score`. If the database is briefly unavailable the route answers 503 `db_unavailable`; retry after a short wait.

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

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `audio_id` | path | string | yes | The `audio_id` or file id of the reference file. |
| `limit` | query | integer | no | How many results to return, 1 to 100. Defaults to 20. |
| `min_score` | query | number | no | Leave out files scoring below this, -1 to 1. Defaults to -1. |

### Response fields (inside `data`)

| Field | Type | Description |
| --- | --- | --- |
| `reference_audio_id` | string | The file the search compared against. |
| `embedding_model` | string | Name of the fingerprint kind that was compared. Only files with a fingerprint of the same kind can match. |
| `results` | array<object> | Your most similar files, best first. The reference itself is never listed. |
| `results[].audio_id` | string | Registry identifier of the similar file; it starts with `audio_`. |
| `results[].original_filename` | string | Name the file was uploaded under. |
| `results[].display_name` | string \| null | Name you gave the file, or null. |
| `results[].similarity_score` | number | How alike the sound is, from -1 to 1, to four decimals. Higher is closer. |
| `results[].bpm` | number \| null | Tempo of the file, or null when it has none. |
| `results[].key_label` | string \| null | Musical key of the file, for example `A minor`, or null. |
| `results[].analyzed_categories` | array<string> | Analysis categories this file has results for. |
| `count` | integer | Entries in `results`. Allowed: -9007199254740991 to 9007199254740991. |
| `note` | string | A fixed sentence on what similarity means. |

### Responses

200: The closest files, best first. The list is empty when no other file has a fingerprint of the same kind.

```json
{
  "data": {
    "reference_audio_id": "audio_3f9c1a7d2b60",
    "embedding_model": "fingerprint-6144",
    "results": [
      {
        "audio_id": "audio_a81e5c40d7f2",
        "original_filename": "demo-mix-2.wav",
        "display_name": null,
        "similarity_score": 0.9312,
        "bpm": 119.8,
        "key_label": "A minor",
        "analyzed_categories": [
          "rhythm",
          "embedding"
        ]
      }
    ],
    "count": 1,
    "note": "Similarity is acoustic character (timbre/texture), not structural or temporal match."
  },
  "meta": {
    "request_id": "req_0b7a3c2e-6f1d-4d9a-8e55-3a4b5c6d7e8f"
  }
}
```

400: `limit` or `min_score` is not allowed (`invalid_limit`, `invalid_min_score`).

```json
{
  "error": {
    "code": "invalid_limit",
    "message": "limit must be an integer from 1 to 100",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#invalid_limit"
  }
}
```

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

```json
{
  "error": {
    "code": "audio_not_found",
    "message": "Audio file not found",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#audio_not_found"
  }
}
```

409: The reference file has no sound fingerprint yet.

```json
{
  "error": {
    "code": "embedding_missing",
    "message": "Run embedding analysis on this file first.",
    "request_id": "req_5b1c0f3e-2d41-4a8e-9a57-0c1b2d3e4f50",
    "docs_url": "https://www.scarleta.ai/docs/errors#embedding_missing"
  }
}
```

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

[`audio_not_found`](https://www.scarleta.ai/docs/errors#audio_not_found), [`auth_unavailable`](https://www.scarleta.ai/docs/errors#auth_unavailable), [`db_unavailable`](https://www.scarleta.ai/docs/errors#db_unavailable), [`embedding_missing`](https://www.scarleta.ai/docs/errors#embedding_missing), [`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), [`invalid_limit`](https://www.scarleta.ai/docs/errors#invalid_limit), [`invalid_min_score`](https://www.scarleta.ai/docs/errors#invalid_min_score), [`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
AUDIO_ID="YOUR_AUDIO_ID"
curl "https://api.scarleta.ai/v1/audio/library/similar/$AUDIO_ID" \
  -H "Authorization: Bearer $SCARLETA_API_KEY"
```