Clyps developer docs

Workspace owners and admins create API keys in Settings, under Developers. Clyps shows each key once and stores only a hash of it. Send the key as a bearer token on every request.

A key belongs to one workspace and acts with the current role of the person who created it. It cannot reach another workspace, team settings or billing. Revoking a key, or removing its creator from the workspace, disables it immediately. Each key may make 120 requests a minute; past that, requests return 429 with the code RATE_LIMITED.

Errors use one shape: an error object with a code, a message and a requestId. Include the requestId when you contact support.

curl https://api.clyps.ai/v1/projects?workspaceId=$CLYPS_WORKSPACE_ID \
  -H "Authorization: Bearer $CLYPS_API_KEY"

Create a project in your workspace; the workspace ID is shown in Settings, under Developers. Then upload its source video. Processing starts once the upload completes.

POST /v1/uploads returns a signed URL for each part of the file. PUT each part to its URL, keep the ETag header from each response, and finish with POST /v1/uploads/{uploadId}/complete. Where URL import is enabled, POST /v1/imports attaches a video from a public link instead. Requests that start work take an Idempotency-Key header, so a retried request never starts the same work twice.

curl https://api.clyps.ai/v1/projects \
  -H "Authorization: Bearer $CLYPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"'$CLYPS_WORKSPACE_ID'","title":"Launch interview"}'

curl https://api.clyps.ai/v1/uploads \
  -H "Authorization: Bearer $CLYPS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"workspaceId":"'$CLYPS_WORKSPACE_ID'","projectId":"'$PROJECT_ID'",
       "filename":"interview.mp4","contentType":"video/mp4","sizeBytes":734003200}'

GET /v1/projects/{projectId} returns the project's status and readiness. Candidate clips are ready when readiness.candidates is true and the status is ready. Instead of polling, you can subscribe to the processing.complete webhook.

GET /v1/projects/{projectId}/candidates lists the moments Clyps selected. Each candidate has a title, start and end times, a score and the reason it was chosen.

curl https://api.clyps.ai/v1/projects/$PROJECT_ID/candidates \
  -H "Authorization: Bearer $CLYPS_API_KEY"

Turn a candidate into an editable clip, then render that clip revision to MP4. The clip response includes the clipId and revision to export. Rendering runs in the background: read the export until its status is complete, or wait for the render.complete webhook. A complete export includes a signed download URL.

curl -X POST https://api.clyps.ai/v1/projects/$PROJECT_ID/candidates/$CANDIDATE_ID/clip \
  -H "Authorization: Bearer $CLYPS_API_KEY"

curl https://api.clyps.ai/v1/projects/$PROJECT_ID/clips/$CLIP_ID/renders \
  -H "Authorization: Bearer $CLYPS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"expectedRevision":1,"filename":"launch-interview.mp4"}'

curl https://api.clyps.ai/v1/projects/$PROJECT_ID/clips/$CLIP_ID/renders/$RENDER_JOB_ID \
  -H "Authorization: Bearer $CLYPS_API_KEY"

Add https endpoints in Settings, under Developers. Clyps posts processing.complete when a project's clips are ready and render.complete when an export finishes. Events carry IDs only; fetch the resource through the API for its details.

Every request is signed with the endpoint's secret using the Standard Webhooks scheme, so any Standard Webhooks library can verify it. Reject requests whose timestamp is more than five minutes old. Clyps retries a delivery that fails or returns a non-2xx status after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 24 hours, then stops. Deliveries can repeat, so deduplicate on the event id.

// Body: {"id":"evt_…","type":"render.complete","timestamp":"…",
//        "workspaceId":"…","data":{"projectId":"…","clipId":"…","renderJobId":"…"}}
async function verifyClypsWebhook(request, secret) {
  const id = request.headers.get("webhook-id")
  const timestamp = request.headers.get("webhook-timestamp")
  const body = await request.text()
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return null
  const key = await crypto.subtle.importKey(
    "raw",
    Uint8Array.from(atob(secret.slice("whsec_".length)), (c) => c.charCodeAt(0)),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  )
  const mac = await crypto.subtle.sign(
    "HMAC",
    key,
    new TextEncoder().encode(`${id}.${timestamp}.${body}`)
  )
  const expected = "v1," + btoa(String.fromCharCode(...new Uint8Array(mac)))
  const signatures = request.headers.get("webhook-signature").split(" ")
  return signatures.includes(expected) ? JSON.parse(body) : null
}

Clyps runs a remote MCP server at https://api.clyps.ai/mcp over streamable HTTP. Authenticate it with a workspace API key in the Authorization header. Its tools run the same operations as the API, inside the key's workspace: list_projects, create_project, import_from_url, create_upload, complete_upload, get_project, list_candidates, create_clip, start_export and get_export.

claude mcp add --transport http clyps https://api.clyps.ai/mcp \
  --header "Authorization: Bearer $CLYPS_API_KEY"

// Or, in an MCP client's JSON configuration:
{
  "mcpServers": {
    "clyps": {
      "type": "http",
      "url": "https://api.clyps.ai/mcp",
      "headers": { "Authorization": "Bearer clyps_sk_…" }
    }
  }
}

The OpenAPI document at https://api.clyps.ai/openapi.json describes every endpoint, request and response. Endpoints that accept API keys list the apiKey security scheme; the rest need a signed-in session.