# Superscribe API Reference

v1.0.0

OAS 3.0.3

# Superscribe API

Superscribe

REST API for accessing your Superscribe voice transcription recordings. Authenticate with an `ss_` API key created at [https://superscribe.io/dashboard/api](/content/dashboard/api/index.html).

Server

Server: https://superscribe.io/api/v1

Production

## AuthenticationRequired

Selected Auth Type: ApiKeyAuth

|     |
| --- |
| API key starting with `ss_`. Create one at [https://superscribe.io/dashboard/api](/content/dashboard/api/index.html) |
| Name : <br>x-api-key<br>Clear Value |
| Value : <br>Show Password |

## List recordings

Auth Required

Returns a paginated list of your transcription recordings, newest first.

### Query Parameters

- **page**  
  Type: integer  
  min: 1  
  Default: 1  
  Page number (1-indexed)

- **limit**  
  Type: integer  
  min: 1  
  max: 100  
  Default: 20  
  Results per page

- **dateFrom**  
  Type: string  
  Format: date-time  
  Filter recordings from this date (ISO 8601)

- **dateTo**  
  Type: string  
  Format: date-time  
  Filter recordings until this date (ISO 8601)

- **source**  
  Type: string  
  Enum  
  Filter by recording source  
  values: microphone, file, phone_call, system_audio

- **callerNumber**  
  Type: string  
  Filter by caller or callee phone number (E.164 format, e.g. +15551234567)

- **sortBy**  
  Type: string  
  Enum  
  Default: createdAt  
  Field to sort by  
  values: createdAt, audioDuration

- **sortOrder**  
  Type: string  
  Enum  
  Default: desc  
  Sort direction  
  values: asc, desc

### Responses

- **200**  
  Paginated list of recordings  
  application/json

- **401**  
  Unauthorized  
  application/json

### Request Example for get/recordings

```curl
curl 'https://superscribe.io/api/v1/recordings?page=1&limit=20&dateFrom=&dateTo=&source=microphone&callerNumber=&sortBy=createdAt&sortOrder=desc' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

### Search recordings

Auth Required

Search recording transcripts. Uses semantic (vector embedding) search first; falls back to full-text regex if no semantic matches are found. The `search_mode` field in the response indicates which was used.

### Query Parameters

- **q**  
  Type: string  
  required  
  Search query

- **page**  
  Type: integer  
  min: 1  
  Default: 1  
  Integer numbers.

- **limit**  
  Type: integer  
  min: 1  
  max: 50  
  Default: 10  
  Integer numbers.

### Responses

- **200**  
  Search results  
  application/json

- **400**  
  Missing q parameter  
  application/json

- **401**  
  Unauthorized  
  application/json

### Request Example for get/recordings/search

```curl
curl 'https://superscribe.io/api/v1/recordings/search?q=&page=1&limit=10' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```

### Get recording

Auth Required

Fetch a single recording by ID.

### Path Parameters

- **id**  
  Type: string  
  required  
  Recording ID (MongoDB ObjectId)

### Responses

- **200**  
  Recording  
  application/json

- **400**  
  Invalid ID format  
  application/json

- **401**  
  Unauthorized  
  application/json

- **404**  
  Recording not found  
  application/json

### Request Example for get/recordings/{id}

```curl
curl 'https://superscribe.io/api/v1/recordings/{id}' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'
```