Cuevue API

Build integrations with the Cuevue REST API. Manage projects, workflow stages, custom fields, comments, subtasks, team members, and webhooks programmatically.

Authentication

All API requests require a bearer token. Generate an API key from Settings → API & Integrations in your workspace. Keys use the cue_sk_ prefix.

curl https://cuevue.io/api/v1/projects \
  -H "Authorization: Bearer cue_sk_your_key_here"

Keys carry one of three permission tiers: read (browse everything), write (create and update content), and admin. Admin-grade operations — managing members, workflow stages, custom field definitions, and webhooks, plus deletes — require an admin key. A plain write key no longer performs admin operations.

Endpoints

All endpoints are relative to /api/v1. Request and response bodies use JSON.

Pagination

List endpoints return cursor-based pagination. Pass limit (max 100, default 25) and use the returned cursor value to fetch the next page.

{
  "data": [ ... ],
  "pagination": {
    "cursor": "eyJ2IjoiMjAyNi0wMy0xMCIsImlkIjoiYWJjMTIzIn0",
    "has_more": true,
    "total": 142
  }
}

When has_more is false, you have reached the end. Pass sort and order to control sort direction.

Error handling

Errors return a consistent JSON envelope with an error object:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "title": "Required"
    }
  }
}

Rate limits

The API enforces per-key rate limits. Current limits are returned in response headers:

Default limit: 120 requests/minute for read operations, 60 requests/minute for writes. When rate limited, the response includes retry_after_ms in the error body.

Webhooks

Receive real-time notifications when events happen in your workspace. Register a webhook endpoint and subscribe to the events you need.

Available events

Payload format

{
  "event": "project.updated",
  "timestamp": "2026-03-26T14:30:00.000Z",
  "space_id": "uuid",
  "data": {
    "project": { ... }
  }
}

Signature verification

Each webhook delivery includes a X-Cue-Signature header containing an HMAC-SHA256 signature. Verify it using the signing secret returned when you create the webhook:

import crypto from "crypto";

function verifyWebhook(body: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Webhooks that fail are retried with exponential backoff (up to 3 attempts). After repeated failures, the endpoint is automatically disabled.

MCP integration

Cuevue supports the Model Context Protocol (MCP), allowing AI assistants and LLM-powered tools to interact with your workspace. The MCP server exposes resources, resource templates, prompts, and a broad set of tools that map to the REST API. Per-tool permission gating mirrors your key's tier: read tools browse, write tools mutate, and admin-grade tools (member, stage, custom-field definition, and webhook management, plus deletes) require an admin key or scope.

Connect your client

Pick your assistant for the exact config. Hosted clients (Claude.ai, ChatGPT) connect over OAuth with no key; desktop and SDK clients use a config snippet or API key.

https://cuevue.io/api/mcp

Read-only keys can browse resources like cuevue://projects/recent, cuevue://workflow/stages, and templates such as cuevue://projects/{episode_id}.

Tool coverage

Tools span projects, subtasks, versions, transcripts, comments, markers, version media (delivered as short-lived signed URLs), review links, documents, directory entries, custom fields, members, workflow, webhooks, and space config — plus list_spaces for discovery. High-cardinality lists are cursor-paginated. Directory listings may include people and bookmark information visible to space members.

MCP via OAuth

Hosted clients such as Claude.ai and ChatGPT can connect over OAuth 2.1 instead of a static key. Add Cuevue as a custom connector and point it at the MCP server URL:

https://cuevue.io/api/mcp

The client discovers authentication automatically — Cuevue serves RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource/api/mcp and supports dynamic client registration. On connect, you approve access on a consent screen; no key copy-paste is needed.

An OAuth connection spans all of your spaces. Every tool accepts an optional space_id; call list_spaces to discover the spaces you can target. Approved scopes follow the same read/write/admin tiers as API keys.