Iris

REST API

Everything in Iris is a thin layer on top of a JSON REST API at /api/v1/*. The dashboard, CLI, SDK, and MCP server all speak it.

Authentication

Send Authorization: Bearer <token> with every request. The token is either a session JWT (for browser flows) or an API key from /keys:

curl https://your-iris-server.example.com/api/v1/recordings \
  -H "Authorization: Bearer ir_live_yourkey"

API keys carry scopes — typically read (default), write, or admin. The minimum scope per endpoint is documented below.

Rate limits

Free plan: 60 requests/minute per workspace. Pro/Team: 600 requests/minute. Burst-friendly. Upload size is capped per plan (500 MB free, 4 GB pro, 8 GB team).

Endpoints

Recordings

  • GET /api/v1/recordings — list. Query: limit, offset, status, workspace_id. Returns { items, pagination }.
  • POST /api/v1/recordings — upload (multipart file, title, workspace_id) or create a stub then PUT later. Scope: write.
  • GET /api/v1/recordings/:id — recording metadata.
  • GET /api/v1/recordings/:id/context — structured context: summary, timeline, transcript, actions, urls, apps, tags. Pass ?field=summary to fetch a sub-field.
  • GET /api/v1/recordings/:id/frames — frame-level OCR/description/url/app for every extracted frame.
  • GET /api/v1/recordings/:id/status — per-stage processing progress.
  • GET /api/v1/recordings/:id/video — streams the video (with Range support) or 302s to a presigned S3 URL.
  • POST /api/v1/recordings/:id/retry — re-queue a failed recording. Scope: write.
  • DELETE /api/v1/recordings/:id — delete files + DB row. Scope: admin.

Recordings (latest)

  • GET /api/v1/recordings/latest — newest recording.
  • GET /api/v1/recordings/latest/context — its context.

Search

  • POST /api/v1/search — body { query, limit?, workspace_id? }. Returns ranked recordings with summary snippets.

Sharing

  • POST /api/v1/recordings/:id/share — toggle public sharing on. Scope: write.
  • DELETE /api/v1/recordings/:id/share — revoke.
  • Public read endpoints under /api/v1/share/:shareId/* (no auth) for video, frames, OG image, JSON-LD.

Workspaces & members

  • GET /api/v1/workspaces — list workspaces you belong to.
  • POST /api/v1/workspaces — create.
  • PATCH /api/v1/workspaces/:id — rename. Owner/admin only.
  • GET /api/v1/workspaces/:id/members — members + pending invites.
  • PATCH /api/v1/workspaces/:id/members/:userId — change role.
  • DELETE /api/v1/workspaces/:id/members/:userId — remove (or leave, if it’s yourself).
  • POST /api/v1/workspaces/invite — email an invite.
  • GET /api/v1/workspaces/:id/usage — current month usage vs plan.

API keys

  • GET /api/v1/keys — list (prefixes only; full keys are shown only at creation).
  • POST /api/v1/keys — create. Body { name, scopes, workspace_id }. Returns the key once.

Auth

  • POST /api/v1/auth/signup, /login, /logout.
  • POST /api/v1/auth/forgot-password, /reset-password, /verify-email, /resend-verification.
  • GET /api/v1/auth/me, PATCH (name, password), DELETE (account).

Found a gap or a typo? Open an issue or PR on GitHub.