API · v2

Upload, process, and retrieve recordings — over HTTP.

Send local videos and images from any HTTP client. Then retrieve recordings, transcripts, and AI summaries for warehouses, automations, RAG pipelines, and agents.

Title searchAI metadataJWT bearer authCursor paginationDirect multipart uploads
curl https://kommodo.ai/api/public/v2/recordings?limit=5 \
  -H "Authorization: Bearer $KOMMODO_API_TOKEN"
200 OK · returns { recordings, next_cursor }
MCP connector · Claude Code skill

Use Kommodo from your AI assistant.

Connect through the official Kommodo MCP server with secure sign-in and no API token to paste. Claude is verified today. For a local Claude Code workflow, install the open-source Skill and provide a scoped API token instead.

Explore the MCP connectorOpen Claude Code skill

MCP and API access require an active Stripe-backed Premium or Enterprise account. The packaged Skill installer targets Claude Code.

~/your-project
$ git clone https://github.com/kommodoai/kommodo-skill.git
$ ./kommodo-skill/install.sh
$ export KOMMODO_API_TOKEN="..."
$ claude
> List my five most recent Kommodo recordings.
I found your five most recent recordings…

Restart Claude Code after setup.

What it is

A REST API for uploading media and working with the recordings, transcripts, and AI metadata in your Kommodo workspace.

The Kommodo API is built for teams that capture video at scale — sales calls, customer onboarding sessions, internal training, recorded meetings, screen-shared product demos — and want that footage to live somewhere other than the dashboard. List endpoints return paginated recordings filtered by creation date, title, owner, folder, or whether a Page exists. Title search does not search transcripts or AI metadata. Detail endpoints return the full AI envelope: summary, chapters with timestamps, action items, tags, suggested title, and detected language.

Upload local images with a signed PUT, or upload videos in signed multipart chunks directly to storage. The upload contract is plain HTTP and works from cURL, JavaScript, Python, Go, Ruby, PHP, Java, or any other client that can make HTTP requests. Large video bytes never pass through the dashboard service.

A separate transcript endpoint streams raw WebVTT or returns parsed JSON cues. Write endpoints let you organize folders, rename or retag recordings, move them between folders, or publish a recording as a Page — all without opening the dashboard. Authentication is a single JWT bearer token; pagination is opaque cursor-based; request pacing information surfaces in headers.

Common builds: nightly transcript sync into a data warehouse, video knowledge bases backed by AI summaries, RAG pipelines that cite specific recording timestamps, agent workflows that curate recordings on a user's behalf, and automation that converts finished recordings into published Pages on a schedule.

Authentication

Create an API token

Read scope by default. Toggle write to upload media, organize folders, update recordings, or publish pages. Available to active Stripe-backed Premium and Enterprise accounts.

1

Open Account → API

Generate a token from your account settings. Read scope is the default; Read + write also permits uploads, folder changes, PATCH, and page creation. Tokens remain valid until revoked or replaced, while your account has API access.

2

Export it as $KOMMODO_API_TOKEN

Treat it like a password — never commit it. Tokens are scoped to your user; revoke and reissue anytime.

3

Send it as a Bearer header

Set Authorization: Bearer <token> on each request. Never send the token to signed storage URLs.

Open token settings
Upload API

Upload from any HTTP client

Upload is a language-neutral HTTP contract. Images use one signed PUT. Videos use signed multipart PUTs so even multi-gigabyte files travel directly to storage instead of through the Kommodo web service. The examples below use cURL and Node, but no Kommodo SDK is required.

Image request

POST /api/public/v2/uploads
Authorization: Bearer <read+write token>
Content-Type: application/json

{
  "type": "image",
  "title": "diagram.png",
  "size_bytes": 240123,
  "content_type": "image/png",
  "width": 1600,
  "height": 900
}

The 201 response contains upload.method, upload.url, required upload.headers, and upload.expires_in_seconds. Send the image bytes to that URL. Images do not use the Kommodo completion endpoint.

Video request

POST /api/public/v2/uploads
Authorization: Bearer <read+write token>
Content-Type: application/json

{
  "type": "video",
  "title": "meeting.mp4",
  "size_bytes": 104857600
}

The 201 response contains upload_id, recording_id, the chunk size, one or more storage providers, and a short-lived Kommodo completion grant.

Video multipart response

URLs and tokens are shortened below. Treat every returned URL and token as a secret until it expires.

{
  "upload_id": "...",
  "recording_id": "...",
  "type": "video",
  "status": "awaiting_upload",
  "upload": {
    "method": "multipart",
    "path": "...",
    "chunk_size_bytes": 5242880,
    "expires_in_seconds": 43200,
    "providers": [{
      "upload_parts": [
        { "part_number": 1, "url": "https://signed-storage/..." }
      ],
      "complete_url": "https://signed-storage/...",
      "abort_url": "https://signed-storage/..."
    }]
  },
  "completion": {
    "url": "/api/public/v2/uploads/<upload_id>/complete",
    "token": "..."
  }
}

Complete a video upload

  1. Split the file using upload.chunk_size_bytes. PUT each part to its matching upload_parts[].url and retain the response ETag.
  2. POST S3-compatible CompleteMultipartUploadXML, ordered by part number, to that provider's complete_url.
  3. POST { "completion_token": "..." } with your Bearer token to completion.url. A successful call returns status: processing. Retry transient failures with the same completion token.
  4. Poll GET /v2/recordings/<recording_id>. A 404 is expected until processing creates the recording; media is ready when urls.video is non-empty.

Security and failure handling

  • Send the Kommodo Bearer token only to the Kommodo API origin. Never attach it to signed storage URLs.
  • Retry individual part PUTs for transient network and 5xx failures. Keep part numbers and ETags in response order.
  • If a provider fails, DELETE its abort_url, then restart the whole file with the next returned provider.
  • Finish all storage and Kommodo completion calls before expires_in_seconds. If the contract expires, initialize a new upload.

Runnable video upload

Both references implement retries, ETag collection, provider failover, storage completion, and Kommodo finalization.

View cURL sourceView Node source
# Requires curl and jq. Inspect the reference before running it.
curl -fsS https://kommodo.ai/api-examples/upload-video.sh -o upload-video.sh
less upload-video.sh
chmod +x upload-video.sh

export KOMMODO_API_TOKEN="<read+write token>"
export KOMMODO_API_BASE_URL="https://kommodo.ai"
./upload-video.sh /absolute/path/to/meeting.mp4

# Prints { upload_id, recording_id, result: { status: "processing" } }

Runnable image upload

JPEG, PNG, GIF, and WebP are supported. Width and height must be the source image's actual positive dimensions. Importing from a remote Zoom, Dropbox, or other URL is not currently supported.

# Requires curl and jq. Supply the source image's real dimensions.
export KOMMODO_API_TOKEN="<read+write token>"
export KOMMODO_API_BASE_URL="https://kommodo.ai"
FILE=/absolute/path/to/diagram.png
SIZE=$(wc -c < "$FILE" | tr -d ' ')

INIT=$(curl --fail-with-body --silent --show-error \
  -X POST "$KOMMODO_API_BASE_URL/api/public/v2/uploads" \
  -H "Authorization: Bearer $KOMMODO_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data "$(jq -cn --arg title "$(basename "$FILE")" --argjson size "$SIZE" \
    '{type:"image", title:$title, size_bytes:$size,
      content_type:"image/png", width:1600, height:900}')")

# The signed storage request must not include your Kommodo API token.
curl --fail-with-body --silent --show-error \
  -X "$(jq -r '.upload.method' <<<"$INIT")" \
  "$(jq -r '.upload.url' <<<"$INIT")" \
  -H "Content-Type: $(jq -r '.upload.headers["Content-Type"]' <<<"$INIT")" \
  --data-binary "@$FILE"

jq '{upload_id, type, status:"uploaded"}' <<<"$INIT"
What people build

Common patterns

Each snippet uses live v2 endpoints. Replace $KOMMODO_API_TOKEN and run.

Nightly transcript sync

Watermark + cursor pagination. Pull every new recording created since your last run and ingest its VTT or JSON transcript into your data warehouse.

# Pull every recording created since last run, then fetch transcripts.
since = read_watermark()  # ISO timestamp from your last sync
cursor = None
while True:
    r = session.get(BASE + "/recordings", params={
        "since": since, "cursor": cursor, "limit": 100,
    }).json()
    for rec in r["recordings"]:
        t = session.get(BASE + f"/recordings/{rec['id']}/transcript",
                        params={"format": "json"}).json()
        ingest(rec, t["cues"])
    cursor = r["next_cursor"]
    if not cursor: break
write_watermark(now_utc_iso())

Build a video knowledge base

Filter by title, folder, or has_page; hydrate with AI summary, chapters, and action items. Feed an enterprise search index or RAG pipeline.

# 1. List recordings inside a specific folder
curl "$BASE/recordings?folder_id=<folder-id>&has_page=true" \
  -H "Authorization: Bearer $KOMMODO_API_TOKEN"

# 2. Pull the AI summary + chapters for each
curl "$BASE/recordings/<id>" \
  -H "Authorization: Bearer $KOMMODO_API_TOKEN"
# returns: ai.summary, ai.chapters, ai.action_items, ai.tags

Bulk rename & curate

PATCH titles, descriptions, and tags from a script or agent. Owner-or-folder-fullAccess enforced server-side.

# Rename a recording (write scope required)
curl -X PATCH "$BASE/recordings/<id>" \
  -H "Authorization: Bearer $KOMMODO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Q2 onboarding — final"}'

Auto-publish a Page from a recording

Turn a finished recording into a public Page with one POST. Drop publish:false for a draft you can edit in the dashboard.

# Convert a recording into a published Page (write scope required)
curl -X POST "$BASE/recordings/<id>/pages" \
  -H "Authorization: Bearer $KOMMODO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"publish": true}'
The fine print

Protocol details

Bearer-authenticated v2 calls include request-pacing headers. Honor Retry-After when the API returns 429.

Auth
JWT HS256, Bearer
Scopes
read · write
Search
Recording titles
Date filters
created_at
Page size
Up to 100 / call
Pagination
Opaque cursor
Transcript cap
5 MB / file
CORS
Any origin; Bearer auth
429 retry
Retry-After seconds
Headers
X-RateLimit-Remaining
Reference

Endpoints

The complete upload protocol is documented above. Additional recording recipes are in the GitHub quickstart.

GET
/v2/recordings
List with filters: q, since, until, folder_id, member_id, has_page, cursor.
read
GET
/v2/recordings/{id}
Full envelope including ai.summary, ai.chapters, ai.action_items.
read
PATCH
/v2/recordings/{id}
Update title, description, tags, folder_id.
write
GET
/v2/recordings/{id}/transcript
Stream as text/vtt or parsed JSON cues. 5 MB cap.
read
POST
/v2/uploads
Initialize an image PUT or a multipart video upload.
write
POST
/v2/uploads/{upload_id}/complete
Finalize a stored video and queue asynchronous processing.
write
POST
/v2/recordings/{id}/pages
Convert recording to a Page. publish:true to go live.
write
GET
/v2/folders
Walk accessible folders. parent_id, visible member_id, and cursor supported.
read
POST
/v2/folders
Create under an owned parent_id, or under your root when omitted.
write
PATCH
/v2/folders/{id}
Rename a folder you own or can edit.
write
DELETE
/v2/folders/{id}
Delete an empty non-root folder. Trash contents also block deletion.
write
GET
/v2/team/members
List the team roster. Account owners only.
read
Kommodo API FAQs

Common questions from developers

Open Account → API in your dashboard and generate a token. Read scope is enabled by default; choose Read + write for write operations. Treat API tokens like passwords and revoke them immediately if exposed. API access requires an active Stripe-backed Premium or Enterprise account.

Read scope can list recordings and folders, fetch transcripts, and read AI metadata. Write scope can also upload local images and videos; create, rename, and delete empty folders; PATCH titles, descriptions, tags, and folder placement; and POST a recording to create a Page. Tokens default to read scope; you must opt in to write scope at token creation.

Yes. Upload is a language-neutral HTTP contract. The upload guide above includes a complete cURL reference, a dependency-free Node reference, the multipart response schema, and the steps required to implement it in any language. Python is optional.

Not currently. The upload API accepts local file bytes. Download the source file first, then upload it with the cURL reference, Node reference, or your own HTTP client.

Bearer-authenticated v2 calls include X-RateLimit-Remaining and X-RateLimit-Reset pacing headers. If the API returns 429, wait the Retry-After duration before retrying. Treat these response headers—not a hard-coded client-side quota—as the current limit signal.

Recording and folder list responses return an opaque next_cursor. Pass it back as the cursor query parameter on the next call until next_cursor is null. GET /v2/recordings also supports since=<ISO timestamp>, which filters by creation time. It is not an updated-record change feed.

The q parameter on GET /v2/recordings searches recording titles. You can combine it with folder, date, team-member, and Page filters. It does not search transcripts, summaries, tags, or other AI metadata.

The transcript endpoint returns either WebVTT (format=vtt) or parsed JSON cues (format=json) with start_seconds, end_seconds, and text per cue. Files are capped at 5 MB; larger transcripts return a 413. The endpoint proxies the underlying file so you do not need to manage presigned URL TTLs.

List responses include ai.tags, ai.suggested_title, ai.detected_language, and ai.status. Detail responses (GET /v2/recordings/{id}) additionally include ai.summary, ai.chapters (with timestamps), and ai.action_items. AI processing is asynchronous; check ai.status (ready, processing, or pending) before consuming.

Yes. Connect a supported AI assistant through the official Kommodo MCP connector with secure sign-in and no API token to paste. Claude and ChatGPT are supported today. Claude Code users can alternatively install the open-source Kommodo Skill with a scoped API token.

API access requires an active Stripe-backed Premium or Enterprise account. Free and non-Stripe accounts can preview the docs but cannot use an API token. See pricing for current tiers.

Email support@kommodo.ai with the request URL, response status, and timestamp in UTC so we can correlate it with server logs.

Not currently. The endpoint table and complete language-neutral upload protocol on this page are the current reference. The GitHub quickstart adds response envelopes, pagination recipes, error codes, and optional agent tooling.

Related

Where this fits in

The API is one surface for the same recordings you see in the dashboard. Here's the rest.

Kommodo MCP connector

Connect supported AI assistants to the same recordings and API capabilities through secure sign-in.

Learn more

Video to SOP Generator

Turn a screen recording into a step-by-step procedure. Useful for understanding what AI metadata looks like.

Learn more

Video Knowledge Base

See the dashboard surface that the API powers — folders, search, AI tagging.

Learn more

Kommodo Skill (open source)

The agent integration that wraps the v2 API. MIT-licensed reference implementation.

Learn more

API support

Generate and revoke tokens in Account settings. For API issues, email support@kommodo.ai with the request URL, response status, and UTC timestamp.