API

REST endpoints, bearer-token auth.

The Framevo API is small on purpose. Right now it covers authentication and key validation; project + analyze endpoints land next.

Authentication

All /api/v1/* requests authenticate with a bearer token. Generate keys from Settings → API Keys.

Test keys are prefixed ak_test_ — safe to ship in CI / staging.
Live keys are prefixed ak_live_ — production only.
Only the SHA-256 hash plus a 12-character prefix is stored server-side. The plaintext key is shown to you exactly once at creation time. Store it somewhere safe.
A revoked key returns 401 on every call. Generating a new key does not invalidate older ones.

Header

Authorization: Bearer ak_live_a1b2c3d4e5f6g7h8...

GET/api/v1/meAvailable

Validates the bearer token and returns the account it belongs to. Use for smoke-testing keys and health-checking integrations.

cURL

curl -H "Authorization: Bearer ak_test_<your-key>" \
     https://your-app.example.com/api/v1/me

200 · response

{
  "uid": "8EqHj4PqM...",
  "keyId": "f7a2c1b0...",
  "type": "test"
}

401 · error

{ "error": "Invalid or revoked API key.", "hint": "Send \`Authorization: Bearer ak_test_…\` (or \`ak_live_…\`)." }

POST/api/v1/projectsPlanned

Create a project, upload a video, and trigger analysis. Returns the project id once the upload completes.

GET/api/v1/projects/{id}Planned

Read a project's current analysis state, timeline moments, and export URLs.

POST/api/v1/projects/{id}/exportPlanned

Render the project's current timeline at the requested resolution and aspect ratio.

Every error response is JSON-encoded with at minimum an error string. Many also carry a hint field with a one-line fix.

401Unauthorised

Missing, malformed, unknown, or revoked API key.

402Plan required

The endpoint or feature you called requires a higher plan.

404Not found

The project (or other resource) doesn't exist on your account.

429Rate limited

Too many calls in a short window. Back off and retry.

5xxServer error

Something went wrong on our side. Retry with backoff.

Settings → API Keys → Create. Pick test for sandbox use, live for production. Plaintext shows once.