HoldFast API reference

Base URL, auth header, every v1 endpoint, and a working first call.

The REST API lives at https://holdfast.video/api/v1 and mirrors the app: projects, uploads, review links, reels, comments, and analytics. Every request carries a token from Settings → API & MCP (how to create one) in the header:

Authorization: Bearer hf_your_token

Send JSON bodies with Content-Type: application/json. Errors come back as { "error": "message" } with the usual statuses: 400 for missing fields, 401 for a bad, revoked, or expired token, 403 when the token's scope or role does not cover the endpoint, 404 when the resource is not in your workspace.

A first call

curl -H "Authorization: Bearer hf_your_token" https://holdfast.video/api/v1/projects

Not sure the host or token is right? The health check needs no auth and returns {"status":"ok"} plus a timestamp:

curl https://holdfast.video/api/health

Projects and assets

• GET /projects: every project with an asset count. POST /projects creates one; body { "name": "Name", "description": "Optional" }.
• GET /projects/:id: one project plus its assets. GET /projects/:id/folders lists its folder tree.
• GET /assets/:id: metadata with playback and thumbnail URLs. GET /assets/:id/download streams the original file.
• POST /assets/upload: send the file as form-data (multipart/form-data) with file and project_id, plus optional name and folder_id. Videos start Optimizing on arrival and are ready to play shortly after.

Review links and comments

• GET /review-links and GET /review-links/:id: your links with view and asset counts.
• POST /review-links: create a shareable page. Body: { "title": "Title", "asset_ids": ["uuid"], "is_active": true }.
• GET /assets/:id/comments and POST /assets/:id/comments: read and write timecoded feedback. GET /assets/:id/comments/markers returns the same notes shaped for editing-software markers.

Reels and analytics

• GET /reels: your reels. Together with analytics, this is all a sales-role token can reach.
• GET /analytics/overview and GET /analytics/storage: workspace counts, and storage per project and asset type.

Creating projects and review links, listing reels, and the analytics endpoints require the Full API token scope; Plugin tokens cover the upload-and-comments surface above. Prefer push over poll? Webhooks send events to you instead.