# 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 | — | microphone, file, phone_call or system_audio; combine with `|` (e.g. `phone_call|microphone`) |
| callerNumber | string | — | Filter by caller/callee phone number (E.164) |
| includeEmpty | boolean | false | Include recordings with empty transcripts (e.g. still processing) |
| includeTranscript | boolean | true | Set false to leave out `transcript` and `turns` for a compact list |
| 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) |
| dateFrom | string (ISO 8601) | — | Filter from date |
| dateTo | string (ISO 8601) | — | Filter until date |
| source | string | — | microphone, file, phone_call or system_audio; combine with `|` (e.g. `phone_call|microphone`) |
| callerNumber | string | — | Filter by caller/callee phone number (E.164) |
| includeEmpty | boolean | false | Include recordings with empty transcripts |
| includeTranscript | boolean | true | Set false to leave out `transcript` and `turns` |

**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": "Alice: Hello?\nYou: Hi, how can I help?",
  "summary": "Alice asked for a quote for 200 units. Send it by Friday.",
  "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": "caller", "speaker_label": "Alice", "is_owner": false, "text": "Hello?", "start_time": 0.0, "end_time": 0.8 },
    { "speaker": "agent", "speaker_label": "You", "is_owner": true, "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",
  "reprocessed_at": null
}
```

---

### Usage report

```
GET /api/v1/reports/usage?dateFrom=2026-08-01&dateTo=2026-08-31
```

Counts for one date range in a single response.

**Query parameters**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| dateFrom | string (ISO 8601) | required | Start of the range |
| dateTo | string (ISO 8601) | now | End of the range. A date without a time covers that whole day (UTC). At most 366 days after dateFrom |
| includeGithub | boolean | true | Add commits, issues and merged pull requests from GitHub repositories linked to projects. Set false for a faster report |

**Response**

```json
{
  "date_from": "2026-08-01T00:00:00.000Z",
  "date_to": "2026-08-31T23:59:59.999Z",
  "recordings": {
    "phone_calls": {
      "count": 120, "minutes": 310, "summarized": 84, "over_two_minutes": 40,
      "incoming": 66, "outgoing": 54,
      "per_week": [{ "week_start": "2026-07-27", "count": 12 }, { "week_start": "2026-08-03", "count": 30 }]
    },
    "meetings": { "count": 14, "minutes": 420, "summarized": 14 },
    "dictations": { "count": 210, "minutes": 95, "summarized": 0 },
    "other": { "count": 3, "minutes": 25, "summarized": 1 }
  },
  "follow_ups": {
    "suggested": 52, "recordings_with_follow_ups": 41,
    "by_kind": { "reminder": 30, "call_back": 10, "calendar_event": 9, "checklist": 3 }
  },
  "crm": {
    "entries_synced": 61, "entries_failed": 0,
    "synced_by_action": { "create_follow_up_task": 30, "create_call_activity": 25, "create_meeting_activity": 6 },
    "synced_by_provider": { "pipedrive": 61 },
    "drafts_by_status": { "synced": 61, "dismissed": 12 }
  },
  "billed_minutes": 5400,
  "projects": [
    {
      "project_id": "507f1f77bcf86cd799439012",
      "project_name": "Acme web app",
      "billed_minutes": 3600,
      "time_blocks": 96,
      "recordings": { "phone_calls": 45, "meetings": 6, "dictations": 80 },
      "github": {
        "repositories": ["acme/web-app"],
        "commits": 58, "issues_opened": 40, "issues_closed": 35, "pull_requests_merged": 12,
        "issues_from_recordings_opened": 22, "issues_from_recordings_closed": 18,
        "recordings_turned_into_issues": 17
      }
    }
  ]
}
```

- Hidden recordings are left out. `summarized` counts recordings that have a summary.
- `per_week` groups calls by week starting Monday (UTC), so the first entry can start before `dateFrom`.
- `follow_ups` are the follow-ups Superscribe suggested, by kind. `crm` counts entries written to the connected CRM and CRM drafts by status.
- `billed_minutes` uses the same precision windows as the Reports page: every window with activity counts once, at the project's time precision or the account default.
- `github` appears on projects with linked repositories when GitHub is connected. `issues_from_recordings_opened` and `issues_from_recordings_closed` count issues whose body contains the ID of one of your recordings. When GitHub data could not be loaded, `github_error` says why.

---

## 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. Sessions expire after 30 minutes without requests; an unknown or expired session ID returns HTTP 404, and sending `initialize` again starts a new session.

### Tools

#### get_recordings

List recordings, newest first, with optional filters.

Arguments: `limit` (number, default 20, max 100), `dateFrom` (ISO string), `dateTo` (ISO string), `source` (string, several separated by `|`), `callerNumber` (E.164 phone number), `includeEmpty` (boolean), `includeTranscript` (boolean, default true), `cursor` (string)

Returns `{ recordings, count, next_cursor }`. Pass `next_cursor` back as `cursor` for the next page; it is null on the last page. Set `includeTranscript` to false for a compact list that keeps the summary, duration, direction and phone numbers.

For phone calls, `transcript` is a speaker-labelled dialogue (one utterance per line) built from the turns — never an unlabelled text blob. Turns use `speaker: "agent"` for the device owner (the Superscribe user) and carry an explicit `is_owner` boolean. Recordings with empty transcripts are excluded unless `includeEmpty` is set.

#### 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, default 10, max 50), `dateFrom`, `dateTo`, `source`, `callerNumber`, `includeEmpty`, `includeTranscript`

#### get_report

Usage counts for a date range, the same JSON as `GET /api/v1/reports/usage`.

Arguments: `dateFrom` (ISO string, required), `dateTo` (ISO string, defaults to now), `includeGithub` (boolean, default true)

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