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 are scoped to a single workspace with either read or write permission. Admin-only endpoints (webhooks, members) require write access.

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 read-only resources, resource templates, and tools that map to the REST API.

Connect your AI tools

Configure your MCP-compatible client (Claude Desktop, Cursor, etc.) with your Cuevue API key:

{
  "mcpServers": {
    "cuevue": {
      "url": "https://cuevue.io/api/mcp",
      "headers": {
        "Authorization": "Bearer cue_sk_your_key_here"
      }
    }
  }
}

Read-only API keys can browse resources like cuevue://projects/recent, cuevue://workflow/stages, and templates such as cuevue://projects/{episode_id}. The server also provides tools for listing projects, reading comments, fetching transcripts, and, with write-permitted API keys, creating projects, comments, and workflow updates.