00:00:00Developers
From a file to an answer
in three calls.
A REST API and an MCP server over the same library. Upload once, let Firassa understand it, then search and run your agents from your code or from the AI tools you already use.
- 01 · Upload
POST/v1/uploads"status": "queued" - 02 · Read
GET/v1/media/{id}"status": "completed" - 03 · Ask
POST/v1/askcitations[0] 00:11:40
- REST API
https://api.firassa.ai/v1- MCP server
https://api.firassa.ai/mcp- For your agent
- This page in Markdown · llms.txt
00:01:00Quickstart
Five steps,
about ten minutes.
Every call goes to https://api.firassa.ai/v1 with your key as a bearer token.
- 01 / 05
Make a key
In the portal, open API keys and make one for your workspace with the scopes it needs: Upload and edit media, Search and Agents. Every key has an expiry, and its secret is shown once.
export FIRASSA_KEY="ak_live_…" - 02 / 05
Upload a file
Start an upload, PUT the bytes to the signed URL, then complete it. Firassa checks the file and starts understanding it.
# 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)"import os, uuid, requests API = "https://api.firassa.ai/v1" KEY = {"Authorization": f"Bearer {os.environ['FIRASSA_KEY']}"} path = "ep1-rough-cut.mp4" up = requests.post(f"{API}/uploads", headers={**KEY, "Idempotency-Key": str(uuid.uuid4())}, json={ "method": "single", "kind": "video", "file_name": path, "size_bytes": os.path.getsize(path), "content_type": "video/mp4", }).json() with open(path, "rb") as f: requests.put(up["put"]["url"], headers=up["put"]["headers"], data=f).raise_for_status() item = requests.post(f"{API}/uploads/{up['id']}/complete", headers={**KEY, "Idempotency-Key": str(uuid.uuid4())}).json() print(item["status"]) # queued, then processing: preparing, analyzing, indexingimport { readFile, stat } from "node:fs/promises"; const API = "https://api.firassa.ai/v1"; const key = { Authorization: `Bearer ${process.env.FIRASSA_KEY}` }; const path = "ep1-rough-cut.mp4"; const up = await fetch(`${API}/uploads`, { method: "POST", headers: { ...key, "Idempotency-Key": crypto.randomUUID(), "Content-Type": "application/json" }, body: JSON.stringify({ method: "single", kind: "video", file_name: path, size_bytes: (await stat(path)).size, content_type: "video/mp4", }), }).then((r) => r.json()); await fetch(up.put.url, { method: "PUT", headers: up.put.headers, body: await readFile(path) }); const item = await fetch(`${API}/uploads/${up.id}/complete`, { method: "POST", headers: { ...key, "Idempotency-Key": crypto.randomUUID() }, }).then((r) => r.json()); console.log(item.status); // queued, then processing: preparing, analyzing, indexing - 03 / 05
Wait for it, or don’t
Give the upload a
callback_urland Firassa calls it when the run ends. Or read the item: its run goes from queued to preparing, analyzing and indexing, then the item is completed.curl https://api.firassa.ai/v1/media/$MEDIA_ID \ -H "Authorization: Bearer $FIRASSA_KEY" # "status": "completed" once Firassa has understood it. # Then read its scenes: GET /v1/media/$MEDIA_ID/scenes - 04 / 05
Ask
Ask in your own words, across the library, a folder or chosen items. The answer cites the moments that show it:
[1]is the first ofcitations. Andnot_foundsays when the library holds none. To list the moments instead, callPOST /v1/search. It answers them best first, each with ascorefrom 0 to 1: 10, or up to 50 withlimit.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?" }'import os, requests r = requests.post( "https://api.firassa.ai/v1/ask", headers={"Authorization": f"Bearer {os.environ['FIRASSA_KEY']}"}, json={"query": "When does Joost talk about the night tours?"}, ) r.raise_for_status() result = r.json() if result["not_found"]: print("Not in the library. The closest moments:") print(result["answer"]) # [1] after a statement is citations[0], [2] is citations[1] for n, c in enumerate(result["citations"], 1): print(f"[{n}]", c["media_id"], c["start_ms"] / 1000, c["end_ms"] / 1000)const res = await fetch("https://api.firassa.ai/v1/ask", { method: "POST", headers: { Authorization: `Bearer ${process.env.FIRASSA_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "When does Joost talk about the night tours?" }), }); const { answer, not_found, citations } = await res.json(); if (not_found) console.log("Not in the library. The closest moments:"); console.log(answer); // [1] after a statement is citations[0], [2] is citations[1] citations.forEach((c, i) => console.log(`[${i + 1}]`, c.media_id, c.start_ms / 1000, c.end_ms / 1000));{ "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 } ] } - 05 / 05
Run an agent
Write your instructions once as an agent in the portal, then run them on any finished item. The answer goes to your webhook, or comes back in the response with
"mode": "sync".# 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" }'
00:02:00MCP server
Your agent already
knows how to ask.
Firassa is a remote MCP server. Paste one line into Claude Code or Codex, and your agent sets itself up: it can search your footage, read its scenes and run your agents, with answers that cite the moment.
https://api.firassa.ai/mcp- No key in a config file. A browser page opens: you sign in, pick one workspace and click Allow.
- It reads, searches and runs your agents. It can’t upload, delete or change who has access.
- Yours to disconnect. Connected tools show up next to your API keys. Disconnect one and it can’t renew its access.
Read https://api.firassa.ai/setup.md and set up Firassaclaude mcp add --transport http --scope user firassa https://api.firassa.ai/mcp
claude mcp login firassacodex mcp add firassa --url https://api.firassa.ai/mcp
codex mcp login firassaWhat your agent can do, among 24 tools
ask_libraryAsk the library; an answer that cites its moments, $0.01search_libraryFind moments, each with a score, $0.0025; the first 1,000 a month freelist_scenes · get_sceneRead what happens around a momentlist_media · list_peopleTitles, lengths, folders and who is in each itemrun_agentRun one of your agents on a finished itemcreate_agent_versionWrite and version agents, then publish themlist_runs · get_runFollow the work, and cancel what hasn’t startedget_usage · get_pricesYour balance, prices and what each run cost
00:03:00Conventions
An API that behaves
the same everywhere.
Keys, retries, errors, lists, webhooks and uploads work one way across the API.
Keys
Bearer API keys, ak_live_<id>.<secret>, one workspace each, with scopes and an expiry. Stored hashed; the secret is shown once.
Idempotency
The routes that make something take an Idempotency-Key. A repeat within 24 hours gets the first answer back.
Errors
Every error is application/problem+json with a stable code, and every answer carries x-request-id.
Lists
Every list is a cursor page, newest first, with filters on the fields that matter.
Webhooks
Give an upload or an agent run an HTTPS callback_url. When the run ends, Firassa posts its status, and an agent’s answer, retrying for 24 hours.
Uploads
One signed PUT up to 5 GB, or 16 MB parts that resume after a dropped connection, up to 20 GB for a video.
00:04:00Limits
Know the edges before you hit them.
Plans set the first three. The rest hold on every plan.
- Longest file
- 1 h on Hobby, 4 h on Pro and Scale, by contract on Enterprise
- Runs at once
- 1, 10, 20 and 50+ by plan
- Indexed library
- 20 h on Hobby, 1,000 h on Pro, 10,000 h on Scale, no limit on Enterprise
- File size
- video 20 GB, audio 2 GB, image 20 MB
- Formats
- MP4, MOV, WebM, MKV, AVI, MPEG, M4V, 3GP · MP3, M4A, AAC, WAV, FLAC, OGG, Opus · JPEG, PNG, WebP, HEIC
- An upload
- completes within 24 h of its start
- A question
- up to 1,000 characters; up to 100 chosen items; up to 20 citations; $0.01, found or not
- A search
- up to 1,000 characters; up to 100 chosen items; up to 50 moments, 10 unless you set limit; $0.0025, the first 1,000 a month free
- An agent
- 1,000 agents and 10,000 versions per organization; a version’s text up to 32 KB
- An agent’s answer
- 8,000 output tokens included, up to 32,000 at $0.02 per extra 1,000; sync runs answer within 120 s; kept 7, 30 or 90 days by plan
- A run
- 6 hours at most once it starts
00:05:00Reference
Every route
a key can call.
49 routes, from the API’s own contract. Each one names the scope a key needs.
Library
Uploads, items, folders, scenes and people.
23 routes- POST
/v1/uploadsStart an upload: one signed PUT for the whole file, or signed parts, and the item's draftUpload and edit mediaIdempotency-Key - POST
/v1/uploads/quoteWhat an upload will cost, in US dollars, before it startsUpload and edit media - POST
/v1/importsImport a file from a URL (an S3 presigned URL included): an upload the platform fetches and completesUpload and edit mediaIdempotency-Key - POST
/v1/imports/bulkImport up to 100 files from their URLs: each an upload the platform fetches and completesUpload and edit media - GET
/v1/uploads/{id}/partsList the parts of a multipart upload stored so far, to resume itUpload and edit media - POST
/v1/uploads/{id}/partsSign URLs for parts of a multipart uploadUpload and edit media - POST
/v1/uploads/{id}/completeComplete an upload: check the stored file, then start the item's first runUpload and edit mediaIdempotency-Key - DELETE
/v1/uploads/{id}Abort an upload, with its draft itemUpload and edit media - GET
/v1/mediaList the organization's media items, newest first, by kind, status, folder (with its subfolders or not), IDs and titleRead media - GET
/v1/media/{id}Read a media item, with its current run and signed URLs for its filesRead media - PATCH
/v1/media/{id}Rename a media item, describe it, or move it into a folderUpload and edit media - DELETE
/v1/media/{id}Delete a media item: hidden now, its files, documents and rows deleted by the platformUpload and edit media - POST
/v1/media/{id}/retryStart a new run of a media item whose run failed or was cancelledUpload and edit mediaIdempotency-Key - GET
/v1/media/{id}/questionsAn item's suggested questions, the first answered: what Search opens withRead media - GET
/v1/foldersList 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 folderRead media - POST
/v1/foldersMake a folder, at the top of the tree or in anotherUpload and edit mediaIdempotency-Key - PATCH
/v1/folders/{id}Rename a folder, or move it into another or to the topUpload and edit media - DELETE
/v1/folders/{id}Delete a folder that is emptyUpload and edit media - GET
/v1/statsCount the organization's media items by kind, with its hours of video and audioRead media - GET
/v1/media/{id}/scenesList a media item's scenes in order, or those that overlap a time rangeRead media - GET
/v1/scenes/{id}Read a scene, with its peopleRead media - GET
/v1/media/{id}/peopleList the people in a media item, each with the scenes they act inRead media - GET
/v1/media/{id}/transcriptExport a media item's transcript as subtitle cues: JSON, WebVTT (format=vtt) or SRT (format=srt)Read media
Search
Find the moments that match, each with a score, or ask for an answer that cites them.
3 routes- POST
/v1/searchSearch the library: the moments that show what was asked, best first, each with a score from 0 to 1Search - POST
/v1/askAsk the library: an answer in text, whether the library holds one, and the spans it citesSearch - POST
/v1/search/warmAsk the search store to warm the workspace's documents before a first search; freeSearch
Agents
Your instructions, with versions, run on a finished item.
13 routes- GET
/v1/agentsList 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 pinnedAgents - POST
/v1/agentsMake an agent: a name, a description, and its first version, its label and its text or another agent's version to copyAgentsIdempotency-Key - GET
/v1/agents/{id}Read an agent, with its latest versionAgents - PATCH
/v1/agents/{id}Rename, describe or share an agent, hand it to another owner, or make another version its latestAgents - DELETE
/v1/agents/{id}Delete an agent for good, with its versions; runs that started from it are not changedAgents - GET
/v1/agents/{id}/versionsList an agent's versions, newest first, with their texts, reviews, whether each is published and which is latestAgents - POST
/v1/agents/{id}/versionsMake 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 askedAgents - GET
/v1/agents/{id}/versions/{version}Read a version of an agent, by its label, or `latest`Agents - POST
/v1/agents/{id}/versions/{version}/reviewRun again the safety review of a version whose review is pendingAgents - POST
/v1/agents/{id}/versions/{version}/publishPublish a version to those the agent is shared with, and make it latest unless asked not toAgents - GET
/v1/agents/{id}/diffCompare two versions of an agent, line by line, each named by its label or `latest`Agents - POST
/v1/agents/{id}/runs/quoteThe 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 lessAgents - POST
/v1/agents/{id}/runsRun 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 oneAgentsIdempotency-Key
Runs
Every piece of work Firassa does, with its status and stage.
4 routes- GET
/v1/runsList the workspace's runs, newest first, by kind, media item, agent and status; a key with only agents lists agent runs aloneRead mediaAgents - GET
/v1/runs/openCount the runs queued or processing, in the workspace and in the whole organization, and the limit on runs at once they shareRead mediaUpload and edit mediaAgents - 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 aloneRead mediaAgents - POST
/v1/runs/{id}/cancelCancel a run while it is queued; once the platform starts it, it goes to its end. A key with only agents cancels agent runs aloneUpload and edit mediaAgents
Billing
Your balance, usage and prices, read by a key.
3 routes- GET
/v1/billing/balanceThe balance in US dollars, spendable and held, and the grants in the order they are spentRead billing - GET
/v1/billing/usageUS dollars charged per service and per UTC day; ?format=csv for a CSV fileRead billing - GET
/v1/billing/pricesThe organization's prices now, and the next change to each that is setRead billing
Account
Who is calling, and the audit log.
3 routes- GET
/v1/meWho calls: the signed-in user and their role, or the API key; its organization, its workspace and the quotasAny key - GET
/v1/plansList the plans on sale: each one's monthly fee, spent as usage, its quotas and its featuresAny key - GET
/v1/audit-eventsRead the workspace's audit log, or the organization's, newest first, by action, actor, target and timeRead the audit log
00:59:59Your footage, understood
Give your agents a memory of everything you’ve filmed.
30 free minutes of Deep video, 200 searches and 50 answers for 14 days. Card required; charged only if you pick a plan.