Superscribe — Full API Reference

Voice-to-text SaaS with automated time tracking.

Overview

Superscribe transcribes audio from microphones, files, and phone calls in real-time using ElevenLabs Scribe (~150ms latency). Transcripts are automatically organized into time blocks for billing and reporting.

Authentication

All API and MCP requests require an API key.

• Header: x-api-key: ss_YOUR_KEY
• Alternative: Authorization: Bearer ss_YOUR_KEY
• Keys are created at: https://superscribe.io/dashboard/api
• Keys start with ss_ and are scoped to the creating user's data only

REST API

Base URL: https://superscribe.io/api/v1

List recordings

GET /api/v1/recordings

Query parameters

Response

{
  "items": [...],
  "total": 142,
  "hasMore": true,
  "page": 1,
  "limit": 20
}

Search recordings

GET /api/v1/recordings/search?q=meeting notes

Uses semantic (vector embedding) search first. Falls back to full-text regex if no semantic matches above threshold. The search_mode field indicates which was used.

Query parameters

Response

{
  "items": [...],
  "total": 8,
  "hasMore": false,
  "page": 1,
  "limit": 10,
  "query": "meeting notes",
  "search_mode": "semantic"
}

Get recording

GET /api/v1/recordings/:id

Response

{
  "id": "507f1f77bcf86cd799439011",
  "transcript": "The meeting discussed Q4 targets and hiring plans.",
  "duration_seconds": 142,
  "source": "phone_call",
  "language": "en",
  "was_translated": false,
  "mode_id": null,
  "direction": "inbound",
  "caller_number": "+12025551234",
  "callee_number": "+18335522205",
  "caller_name": "Alice",
  "turns": [
    { "speaker": "user", "speaker_label": "Alice", "text": "Hello?", "start_time": 0.0, "end_time": 0.8 },
    { "speaker": "agent", "speaker_label": "You", "text": "Hi, how can I help?", "start_time": 1.2, "end_time": 2.4 }
  ],
  "created_at": "2025-03-01T10:30:00.000Z",
  "updated_at": "2025-03-01T10:30:01.000Z"
}

MCP (Model Context Protocol)

Superscribe implements the MCP Streamable HTTP protocol.

Endpoint: https://superscribe.io/mcp

Initialization

bash
curl -X POST https://superscribe.io/mcp \
 -H "x-api-key: ss_YOUR_KEY" \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0"}}}'

Returns a mcp-session-id response header. Pass this in subsequent requests.

Tools

get_recordings

List recordings with optional filters.

Arguments: limit (number), dateFrom (ISO string), dateTo (ISO string), source (string)

get_recording

Fetch a single recording by ID with full transcript, contact-enriched speaker labels, and turn-by-turn breakdown (for phone calls).

Arguments: id (string, required)

search_recordings

Search recording transcripts.

Arguments: query (string, required), limit (number)

Claude Desktop configuration

{
  "mcpServers": {
    "superscribe": {
      "url": "https://superscribe.io/mcp",
      "headers": { "x-api-key": "ss_YOUR_KEY" }
    }
  }
}

Error responses

All errors return JSON with an error field:

{ "error": "Recording not found" }