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.

  1. 01 · UploadPOST/v1/uploads"status": "queued"
  2. 02 · ReadGET/v1/media/{id}"status": "completed"
  3. 03 · AskPOST/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.

  1. 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.

    Your shell
    export FIRASSA_KEY="ak_live_…"
  2. 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.

    POST /v1/uploads
    # 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. 03 / 05

    Wait for it, or don’t

    Give the upload a callback_url and 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.

    GET /v1/media/{id}
    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
  4. 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 of citations. And not_found says when the library holds none. To list the moments instead, call POST /v1/search. It answers them best first, each with a score from 0 to 1: 10, or up to 50 with limit.

    POST /v1/ask
    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?" }'
  5. 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".

    POST /v1/agents/{id}/runs
    # 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.

Serverhttps://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 Firassa

What your agent can do, among 24 tools

  • ask_libraryAsk the library; an answer that cites its moments, $0.01
  • search_libraryFind moments, each with a score, $0.0025; the first 1,000 a month free
  • list_scenes · get_sceneRead what happens around a moment
  • list_media · list_peopleTitles, lengths, folders and who is in each item
  • run_agentRun one of your agents on a finished item
  • create_agent_versionWrite and version agents, then publish them
  • list_runs · get_runFollow the work, and cancel what hasn’t started
  • get_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

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.