Kolbo.AIKolbo.AI Docs
Developer API

Kolbo Review

Frame.io-style client review over the API — upload media, create review assets with versions, comment with timecodes, set status, and mint guest share links.

Kolbo Review is the in-app Frame.io-style review layer: versioned assets, status workflow, timestamped comments, collections (folders), and guest share links. The Developer API exposes the same surface under /api/v1/review/* so API clients and @kolbo/mcp agents can drive review without opening the app.

Upload first with the Media Library (POST /v1/media/upload, upload ticket, or MCP upload_media / create_upload_ticket / media_upload_widget), then pass the returned media_id into Review. There is no separate Review uploader.

Endpoint map

GET    /api/v1/review/storage-usage
POST   /api/v1/review/assets
GET    /api/v1/review/assets
GET    /api/v1/review/assets/:id
PATCH  /api/v1/review/assets/:id
POST   /api/v1/review/assets/:id/versions
POST   /api/v1/review/assets/:id/status
DELETE /api/v1/review/assets/:id
GET    /api/v1/review/assets/:id/comments
POST   /api/v1/review/assets/:id/comments

POST   /api/v1/review/collections
GET    /api/v1/review/collections
PATCH  /api/v1/review/collections/:id
DELETE /api/v1/review/collections/:id

POST   /api/v1/review/assets/:id/share-links
POST   /api/v1/review/collections/:id/share-links
GET    /api/v1/review/share-links
POST   /api/v1/review/share-links/:linkId/revoke

POST   /api/v1/review/comments/:noteId/reply
PATCH  /api/v1/review/comments/:noteId
DELETE /api/v1/review/comments/:noteId
POST   /api/v1/review/comments/:noteId/resolve
POST   /api/v1/review/comments/:noteId/unresolve

All Review routes share the 120/min media-library rate-limit bucket (keyed by authenticated user — see Errors & Limits).

Permissions & limits

ActionRequired access
List / get assets & collections, list/create comments, reply, resolveProject view+
Create / update / delete assets & collections, add versions, set status, share linksProject edit+
Delete someone else's commentProject full+, or author of the comment

Additional product limits (same as the app):

LimitDetail
Free planMax 3 live review assets per owner (403 REVIEW_FREE_LIMIT)
Storage5 GB of Review version media per owner (413 REVIEW_STORAGE_LIMIT)
Per-file uploadMedia upload rules still apply (Review versions reuse Media Library items)

Guest share-link visitors use the public /review-link/:token app page — they are not authenticated via API key. The SDK only manages links as the project editor.

Typical flow

1. POST /v1/media/upload  →  media_id
2. POST /v1/review/assets { name, media_id, project_id }  →  asset (+ v1)
3. POST /v1/review/assets/:id/comments { body, time_start? }
4. POST /v1/review/assets/:id/status { review_status: "needs_review" }
5. POST /v1/review/assets/:id/share-links  →  share_url for the client

Storage usage

GET /api/v1/review/storage-usage
{
  "success": true,
  "used_bytes": 118845242,
  "cap_bytes": 5368709120
}

Scoped to the API-key owner (the same cap that gates create / add-version).

Assets

Create (asset + v1 in one call)

POST /api/v1/review/assets
FieldTypeRequiredDescription
namestringYesDisplay name (trimmed, max 500).
media_idstringYesMediaLibraryItem id from upload / list media. Must be owned by you or live in the same project_id.
project_idstringNoTarget project (edit+). Omitted → auto-created "API Generations" project.
collection_idstringNoOptional Review collection folder in that project.
version_notestringNoNote on v1 (max 1000 chars).
curl -X POST https://api.kolbo.ai/api/v1/review/assets \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero cut v1",
    "media_id": "6a7b42c150af38464a4ff468",
    "project_id": "6a098ebadfe025fd179a074a"
  }'

Response (201):

{
  "success": true,
  "asset": {
    "id": "6a7b463b2e9279d87f9ba2e2",
    "name": "Hero cut v1",
    "project_id": "6a098ebadfe025fd179a074a",
    "collection_id": null,
    "review_status": "in_progress",
    "current_version_index": 0,
    "versions": [
      {
        "id": "…",
        "label": "v1",
        "media_id": "6a7b42c150af38464a4ff468",
        "url": "https://media.kolbo.ai/…",
        "media_type": "video",
        "thumbnail_url": "https://media.kolbo.ai/…",
        "note": null,
        "uploaded_at": "2026-08-11T15:56:00.000Z"
      }
    ],
    "created_at": "2026-08-11T15:56:00.000Z",
    "updated_at": "2026-08-11T15:56:00.000Z"
  }
}

List

GET /api/v1/review/assets
ParameterTypeRequiredDescription
project_idstringNoProject to list. Omitted → your default "API Generations" project (not every accessible project).
collection_idstringNoFilter to one collection.
statusstringNoin_progress | needs_review | approved | changes_requested. Also accepted as review_status.
pagenumberNo1-indexed. Default 1.
limitnumberNoDefault 20, max 100.
{
  "success": true,
  "assets": [ /* asset shapes */ ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "pages": 1 }
}

Get / update / delete

GET    /api/v1/review/assets/:id
PATCH  /api/v1/review/assets/:id
DELETE /api/v1/review/assets/:id

PATCH body (all optional):

FieldTypeDescription
namestringRename.
collection_idstring | nullMove into a collection, or null to uncollect.
current_version_indexnumberSwitch the active version (0-based).

DELETE soft-deletes the asset (and frees its contribution toward the free-tier count / storage aggregation once versions are cleaned up by the existing Review delete path).

Add a version

POST /api/v1/review/assets/:id/versions
FieldTypeRequiredDescription
media_idstringYesNew MediaLibraryItem to append as v{n+1}.
version_notestringNoOptional note (max 1000).

Becomes the current version automatically.

Set status

POST /api/v1/review/assets/:id/status
FieldTypeRequiredDescription
review_statusstringYesin_progress | needs_review | approved | changes_requested. Also accepted as status.

Notifies the asset owner when the changer is someone else (same as the app).

Collections

Folders that group review assets inside a project.

POST   /api/v1/review/collections
GET    /api/v1/review/collections
PATCH  /api/v1/review/collections/:id
DELETE /api/v1/review/collections/:id

Create body: { "name": string, "project_id"?: string } — edit+ required.
List query: project_id optional (defaults to API Generations, same as assets).
Patch body: { "name": string }.
Delete: soft-delete; assets in that folder become uncollected (collection_id: null).

Comments

Text comments (optional video timecodes) on a review asset's media. Drawing annotations and voice notes stay app-only for now.

List / create on an asset

GET  /api/v1/review/assets/:id/comments
POST /api/v1/review/assets/:id/comments

List query: optional version_media_id (defaults to the asset's current version media).

Create body:

FieldTypeRequiredDescription
bodystringYesPlain-text comment.
time_startnumberNoSeconds on the timeline.
time_endnumberNoOptional end of a range.
version_media_idstringNoComment on a non-current version's media.
curl -X POST https://api.kolbo.ai/api/v1/review/assets/6a7b463b2e9279d87f9ba2e2/comments \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Cut the logo sting shorter", "time_start": 3.2 }'

Reply / edit / delete / resolve

POST   /api/v1/review/comments/:noteId/reply
PATCH  /api/v1/review/comments/:noteId
DELETE /api/v1/review/comments/:noteId
POST   /api/v1/review/comments/:noteId/resolve
POST   /api/v1/review/comments/:noteId/unresolve

Reply body: { "body": string } (one level of threading).
Edit body: optional body, time_start, time_end (author only).
Delete: author, or full+ on the project.

Mint a guest URL the client opens without a Kolbo account.

POST /api/v1/review/assets/:id/share-links
POST /api/v1/review/collections/:id/share-links
GET  /api/v1/review/share-links?target_type=asset|collection&target_id=…
POST /api/v1/review/share-links/:linkId/revoke

Create body (all optional except you need edit+ on the project):

FieldTypeDescription
role_labelstringLabel shown to guests (e.g. "Client").
permissionsobjectBooleans: canComment, canDownload, canViewOtherComments, canResolveOwn, canSwitchVersions, canSetStatus.
require_emailbooleanAsk guests for an email before commenting.
passwordstringOptional password gate.
allowed_emailsstring[]Optional allow-list.
expires_atstringISO-8601 expiry.
{
  "success": true,
  "share_link": {
    "id": "6a7b4797a51cce019cae9685",
    "share_url": "https://app.kolbo.ai/review-link/76642589a6c554d156e16f33b8108ba0…",
    "target_type": "asset",
    "target_id": "6a7b463b2e9279d87f9ba2e2",
    "role_label": "Client",
    "permissions": { "canComment": true },
    "created_at": "2026-08-11T15:58:00.000Z"
  }
}

Treat share_url as a credential. Only editors can list or revoke links. Revoking immediately invalidates the guest page.

Errors

StatusCodeCause
400VALIDATIONMissing name / media_id, bad ids, invalid status, no media version on the asset.
403FORBIDDENInsufficient project permission.
403REVIEW_FREE_LIMITFree plan already has 3 live review assets.
404NOT_FOUNDAsset, collection, media, or link not found / not accessible.
413REVIEW_STORAGE_LIMITOwner would exceed the 5 GB Review storage cap.

Envelope: { "success": false, "error": "…", "code": "…" }.

MCP tools

Matching @kolbo/mcp tools (v1.66.0+):

ToolMaps to
get_review_storage_usageGET /v1/review/storage-usage
list_review_assets / get_review_asset / create_review_asset / update_review_asset / add_review_version / set_review_status / delete_review_assetAssets
list_review_collections / create_review_collection / update_review_collection / delete_review_collectionCollections
list_review_comments / create_review_comment / reply_review_comment / edit_review_comment / delete_review_comment / resolve_review_comment / unresolve_review_commentComments
create_review_share_link / list_review_share_links / revoke_review_share_linkShare links

Intended agent flow:

1. upload_media | create_upload_ticket | media_upload_widget  → media_id
2. (user named a project?) list_projects → project_id
3. create_review_asset { name, media_id, project_id }
4. create_review_comment / set_review_status / create_review_share_link as needed

Out of scope (v1)

Drawing annotations / pins, voice-note comments, storyboard share links, live cursors, and guest-token auth for MCP. Use the Kolbo app for those.

Media Library

Upload files and obtain media_id before creating a review asset

Projects

Resolve project_id for review assets and collections

AI Docs

Project-scoped written deliverables (plans, briefs) alongside review

Errors & Limits

Shared rate limits and error envelope

AI Docs (Magic Pad)

Create, edit, and share project-scoped documents — the same docs users see in the Kolbo app's Magic Pad editor.

HTML Artifacts

Publish an HTML page, SVG, or Mermaid source to a public Kolbo URL and update it in place.

On this page

Endpoint mapPermissions & limitsTypical flowStorage usageAssetsCreate (asset + v1 in one call)ListGet / update / deleteAdd a versionSet statusCollectionsCommentsList / create on an assetReply / edit / delete / resolveShare linksErrorsMCP toolsOut of scope (v1)Related