# Firassa for developers

REST API at https://api.firassa.ai/v1 and a remote MCP server at https://api.firassa.ai/mcp, over the same library.

## Quickstart

1. In the portal, make an API key for your workspace with the scopes it needs. Keys are `ak_live_<id>.<secret>`, sent as `Authorization: Bearer`. Every key expires; its secret is shown once.
2. Upload a file:

```bash
# 1. Start an upload. Firassa answers with a signed URL for the bytes.
curl https://api.firassa.ai/v1/uploads \
  -H "Authorization: Bearer $FIRASSA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "single",
    "kind": "video",
    "file_name": "ep1-rough-cut.mp4",
    "size_bytes": 2576980378,
    "content_type": "video/mp4"
  }'

# 2. PUT the file to put.url, with put.headers (one PUT up to 5 GB, or parts).

# 3. Complete it. Firassa checks the file and starts understanding it.
curl -X POST https://api.firassa.ai/v1/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $FIRASSA_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

3. Wait for the run: give the upload a `callback_url`, or read `GET /v1/media/{id}` until `status` is `completed`.
4. Ask. `[1]` after a statement is the first of `citations`; with `not_found`, the citations are the closest moments:

```bash
curl https://api.firassa.ai/v1/ask \
  -H "Authorization: Bearer $FIRASSA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "When does Joost talk about the night tours?" }'
```

```json
{
  "answer": "Joost talks about the night tours at the Damrak quay while the next group lines up [1], and about his twenty years of them in the wheelhouse [2]. In his full interview he says why the evening route starts at the Damrak [3].",
  "not_found": false,
  "citations": [
    { "media_id": "0c5e8f2a-…", "start_ms": 700000, "end_ms": 751000 },
    { "media_id": "0c5e8f2a-…", "start_ms": 330000, "end_ms": 372000 },
    { "media_id": "7d21b6c0-…", "start_ms": 1862000, "end_ms": 1935000 }
  ]
}
```

To list the moments instead, call `POST /v1/search` with the same `query`. It answers `{moments}`, best first, each a `media_id` with its `start_ms`, `end_ms` and a `score` from 0 to 1: 10, or up to 50 with `limit`.

5. Run an agent on a finished item:

```bash
# Run the latest version of your agent on a finished item.
# The answer goes to your webhook; mode "sync" answers in the response instead.
curl https://api.firassa.ai/v1/agents/$AGENT_ID/runs \
  -H "Authorization: Bearer $FIRASSA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "media_id": "0c5e8f2a-…",
    "version": "latest",
    "mode": "async",
    "callback_url": "https://example.com/hooks/firassa"
  }'
```

## MCP

Server: https://api.firassa.ai/mcp. An AI tool signs in through the portal (OAuth); the user allows it in one workspace with the scopes it asks for. In Claude Code or Codex, paste: "Read https://api.firassa.ai/setup.md and set up Firassa". Or by hand, Claude Code: `claude mcp add --transport http --scope user firassa https://api.firassa.ai/mcp`; Codex: `codex mcp add firassa --url https://api.firassa.ai/mcp`.

Tools:

- `ask_library`: Ask the library; an answer that cites its moments, $0.01
- `search_library`: Find moments, each with a score, $0.0025; the first 1,000 a month free
- `list_scenes · get_scene`: Read what happens around a moment
- `list_media · list_people`: Titles, lengths, folders and who is in each item
- `run_agent`: Run one of your agents on a finished item
- `create_agent_version`: Write and version agents, then publish them
- `list_runs · get_run`: Follow the work, and cancel what hasn’t started
- `get_usage · get_prices`: Your balance, prices and what each run cost

## Conventions

- Every create takes an `Idempotency-Key`; a repeat within 24 hours gets the first answer back.
- Every error is `application/problem+json` with a stable code; every answer carries `x-request-id`.
- Every list is a cursor page.
- Uploads: one signed PUT up to 5 GB, or signed parts that resume.
- Webhooks: a `callback_url` on an upload or an agent run, retried for 24 hours.

## Routes a key can call

### Library

Uploads, items, folders, scenes and people.

- `POST /v1/uploads`: Start an upload: one signed PUT for the whole file, or signed parts, and the item's draft. Scope: media:write.
- `POST /v1/uploads/quote`: What an upload will cost, in US dollars, before it starts. Scope: media:write.
- `POST /v1/imports`: Import a file from a URL (an S3 presigned URL included): an upload the platform fetches and completes. Scope: media:write.
- `POST /v1/imports/bulk`: Import up to 100 files from their URLs: each an upload the platform fetches and completes. Scope: media:write.
- `GET /v1/uploads/{id}/parts`: List the parts of a multipart upload stored so far, to resume it. Scope: media:write.
- `POST /v1/uploads/{id}/parts`: Sign URLs for parts of a multipart upload. Scope: media:write.
- `POST /v1/uploads/{id}/complete`: Complete an upload: check the stored file, then start the item's first run. Scope: media:write.
- `DELETE /v1/uploads/{id}`: Abort an upload, with its draft item. Scope: media:write.
- `GET /v1/media`: List the organization's media items, newest first, by kind, status, folder (with its subfolders or not), IDs and title. Scope: media:read.
- `GET /v1/media/{id}`: Read a media item, with its current run and signed URLs for its files. Scope: media:read.
- `PATCH /v1/media/{id}`: Rename a media item, describe it, or move it into a folder. Scope: media:write.
- `DELETE /v1/media/{id}`: Delete a media item: hidden now, its files, documents and rows deleted by the platform. Scope: media:write.
- `POST /v1/media/{id}/retry`: Start a new run of a media item whose run failed or was cancelled. Scope: media:write.
- `GET /v1/media/{id}/questions`: An item's suggested questions, the first answered: what Search opens with. Scope: media:read.
- `GET /v1/folders`: List the organization's folders, newest first, each with how many items and folders it holds: every one, to draw the tree from, or those in one folder. Scope: media:read.
- `POST /v1/folders`: Make a folder, at the top of the tree or in another. Scope: media:write.
- `PATCH /v1/folders/{id}`: Rename a folder, or move it into another or to the top. Scope: media:write.
- `DELETE /v1/folders/{id}`: Delete a folder that is empty. Scope: media:write.
- `GET /v1/stats`: Count the organization's media items by kind, with its hours of video and audio. Scope: media:read.
- `GET /v1/media/{id}/scenes`: List a media item's scenes in order, or those that overlap a time range. Scope: media:read.
- `GET /v1/scenes/{id}`: Read a scene, with its people. Scope: media:read.
- `GET /v1/media/{id}/people`: List the people in a media item, each with the scenes they act in. Scope: media:read.
- `GET /v1/media/{id}/transcript`: Export a media item's transcript as subtitle cues: JSON, WebVTT (format=vtt) or SRT (format=srt). Scope: media:read.

### Search

Find the moments that match, each with a score, or ask for an answer that cites them.

- `POST /v1/search`: Search the library: the moments that show what was asked, best first, each with a score from 0 to 1. Scope: search.
- `POST /v1/ask`: Ask the library: an answer in text, whether the library holds one, and the spans it cites. Scope: search.
- `POST /v1/search/warm`: Ask the search store to warm the workspace's documents before a first search; free. Scope: search.

### Agents

Your instructions, with versions, run on a finished item.

- `GET /v1/agents`: List the organization's agents that you can see, newest first, each with its latest version: yours, and those shared with the organization; or the agents you pinned. Scope: agents.
- `POST /v1/agents`: Make an agent: a name, a description, and its first version, its label and its text or another agent's version to copy. Scope: agents.
- `GET /v1/agents/{id}`: Read an agent, with its latest version. Scope: agents.
- `PATCH /v1/agents/{id}`: Rename, describe or share an agent, hand it to another owner, or make another version its latest. Scope: agents.
- `DELETE /v1/agents/{id}`: Delete an agent for good, with its versions; runs that started from it are not changed. Scope: agents.
- `GET /v1/agents/{id}/versions`: List an agent's versions, newest first, with their texts, reviews, whether each is published and which is latest. Scope: agents.
- `POST /v1/agents/{id}/versions`: Make a new draft version of an agent, with its label, a note and its text or a version to copy; it is reviewed, and becomes latest only when asked. Scope: agents.
- `GET /v1/agents/{id}/versions/{version}`: Read a version of an agent, by its label, or `latest`. Scope: agents.
- `POST /v1/agents/{id}/versions/{version}/review`: Run again the safety review of a version whose review is pending. Scope: agents.
- `POST /v1/agents/{id}/versions/{version}/publish`: Publish a version to those the agent is shared with, and make it latest unless asked not to. Scope: agents.
- `GET /v1/agents/{id}/diff`: Compare two versions of an agent, line by line, each named by its label or `latest`. Scope: agents.
- `POST /v1/agents/{id}/runs/quote`: The most a run of an agent on a media item can cost, in US dollars, before it starts: what it holds. It is charged the output tokens its answer writes past the 8,000 included, so it may cost less. Scope: agents.
- `POST /v1/agents/{id}/runs`: Run a version of an agent, its latest unless named, on a completed media item: async, on the platform's workers, or sync, answering with the answer; every answer is kept on the run for whoever started it, and goes to the webhook when there is one. Scope: agents.

### Runs

Every piece of work Firassa does, with its status and stage.

- `GET /v1/runs`: List the workspace's runs, newest first, by kind, media item, agent and status; a key with only agents lists agent runs alone. Scope: media:read or agents.
- `GET /v1/runs/open`: Count the runs queued or processing, in the workspace and in the whole organization, and the limit on runs at once they share. Scope: media:read or media:write or agents.
- `GET /v1/runs/{id}`: Read a run: its status, stage and failure, and an agent run's answer, for whoever started it, while the API keeps it; a key with only agents reads agent runs alone. Scope: media:read or agents.
- `POST /v1/runs/{id}/cancel`: Cancel a run while it is queued; once the platform starts it, it goes to its end. A key with only agents cancels agent runs alone. Scope: media:write or agents.

### Billing

Your balance, usage and prices, read by a key.

- `GET /v1/billing/balance`: The balance in US dollars, spendable and held, and the grants in the order they are spent. Scope: billing:read.
- `GET /v1/billing/usage`: US dollars charged per service and per UTC day; ?format=csv for a CSV file. Scope: billing:read.
- `GET /v1/billing/prices`: The organization's prices now, and the next change to each that is set. Scope: billing:read.

### Account

Who is calling, and the audit log.

- `GET /v1/me`: Who calls: the signed-in user and their role, or the API key; its organization, its workspace and the quotas. Scope: any key.
- `GET /v1/plans`: List the plans on sale: each one's monthly fee, spent as usage, its quotas and its features. Scope: any key.
- `GET /v1/audit-events`: Read the workspace's audit log, or the organization's, newest first, by action, actor, target and time. Scope: audit:read.
