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.

Server

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

Production

AuthenticationRequired

Selected Auth Type: ApiKeyAuth

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 '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 '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 'https://superscribe.io/api/v1/recordings/{id}' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'