REST Quickstart

Make your first authenticated call to the Specala AI Developer API and get back real transcriptions.

Every Specala AI endpoint is a plain HTTPS request with a bearer token. In a few minutes you'll list your transcriptions, fetch one in full, and export it to Markdown.

Prefer no code? The MCP server wraps this same API for AI assistants.

Create an API key

Open Settings → API & MCP in the Specala AI web app, click Create key, and copy the sk_live_… value. It's shown only once.

Create API key

List your transcriptions

Send the key in the Authorization header. Pick your language — the choice syncs across every example on the site.

curl https://app.specala.ai/api/v1/developer/transcriptions \
  -H "Authorization: Bearer sk_live_your_key_here"

import httpx

BASE = "https://app.specala.ai/api/v1/developer"
HEADERS = {"Authorization": "Bearer sk_live_your_key_here"}

resp = httpx.get(f"{BASE}/transcriptions", headers=HEADERS)
resp.raise_for_status()

data = resp.json()
print(f"{data['total']} transcriptions")
for t in data["items"]:
    print(t["id"], "—", t["title"])

const BASE = "https://app.specala.ai/api/v1/developer";
const headers = { Authorization: "Bearer sk_live_your_key_here" };

const res = await fetch(`${BASE}/transcriptions`, { headers });
if (!res.ok) throw new Error(`HTTP ${res.status}`);

const data = await res.json();
console.log(`${data.total} transcriptions`);
for (const t of data.items) console.log(t.id, "—", t.title);

With the MCP server connected, just ask your assistant:

List my most recent Specala AI transcriptions.

It calls specala_list_transcriptions for you — no key handling, no HTTP.

You'll get back a page of transcriptions:

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": "Acme — discovery call",
      "summary": "Walked through current workflow and pain points...",
      "language": "en",
      "duration_seconds": 1840.5,
      "speakers": [{ "name": "Alex" }, { "name": "Jordan" }],
      "topics": [{ "title": "Pricing" }, { "title": "Onboarding" }],
      "media_type": "audio",
      "project": { "id": "8b1f...", "name": "Sales" },
      "created_at": "2026-05-20T09:14:00Z",
      "updated_at": "2026-05-20T09:31:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Fetch one transcription in full

Take an id from the list and request its detail — this adds the full text and any AI reports.

curl https://app.specala.ai/api/v1/developer/transcriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer sk_live_your_key_here"

tid = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
resp = httpx.get(f"{BASE}/transcriptions/{tid}", headers=HEADERS)
resp.raise_for_status()

t = resp.json()
print(t["title"])
print(t["text"][:500])
for report in t["prompt_results"]:
    print("Report:", report["name"])

const tid = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
const res = await fetch(`${BASE}/transcriptions/${tid}`, { headers });
const t = await res.json();

console.log(t.title);
console.log(t.text.slice(0, 500));
t.prompt_results.forEach((r) => console.log("Report:", r.name));

Open the Acme discovery call and show me the action items.

The assistant calls specala_get_transcription with the UUID and reads the full text + AI reports.

Export it to Markdown

The export endpoint returns a ready-to-save file. Markdown includes YAML frontmatter, so it drops straight into Obsidian or any notes app.

curl "https://app.specala.ai/api/v1/developer/transcriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6/export?format=md" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -o "acme-discovery-call.md"

resp = httpx.get(
    f"{BASE}/transcriptions/{tid}/export",
    params={"format": "md"},
    headers=HEADERS,
)
resp.raise_for_status()

with open("acme-discovery-call.md", "wb") as f:
    f.write(resp.content)

import { writeFile } from "node:fs/promises";

const res = await fetch(`${BASE}/transcriptions/${tid}/export?format=md`, { headers });
await writeFile("acme-discovery-call.md", Buffer.from(await res.arrayBuffer()));

Export the Acme discovery call to ~/notes/meetings as markdown.

The assistant calls specala_export_transcription with an output_path and writes the file directly — without loading the whole transcript into the conversation.

Next steps

Authentication — key scope, rate limits, security best practices.
API Reference — every endpoint and parameter.
Guides — task-focused walkthroughs.

Create an API key

List your transcriptions

Fetch one transcription in full

Export it to Markdown

Next steps

On this page