# 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**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| page | integer | 1 | Page number (1-indexed) |
| limit | integer | 20 | Results per page (max 100) |
| dateFrom | string (ISO 8601) | — | Filter from date |
| dateTo | string (ISO 8601) | — | Filter until date |
| source | string | — | One of: microphone, file, phone_call, system_audio |
| sortBy | string | createdAt | createdAt or audioDuration |
| sortOrder | string | desc | asc or desc |

**Response**

```json
{
  "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**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| q | string | required | Search query |
| page | integer | 1 | Page number |
| limit | integer | 10 | Results per page (max 50) |

**Response**

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

---

### Get recording

```
GET /api/v1/recordings/:id
```

**Response**

```json
{
  "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

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

## Error responses

All errors return JSON with an `error` field:

```json
{ "error": "Recording not found" }
```

| Status | Meaning |
|--------|---------|
| 400 | Bad request (invalid params) |
| 401 | Missing or invalid API key |
| 404 | Resource not found |
| 500 | Internal server error |