Skip to content

API reference

Generated from the action registry in core/src/actions/registry.ts; run pnpm docs:generate after changing an action.

Every action is a REST endpoint and an MCP tool with the same input, validation, and errors. Project actions authenticate with a project API key (Authorization: Bearer cl_sk_…), which acts on its own project, or, on REST, with a signed-in user’s session cookie, which names the project in the Customer-Lite-Project header. MCP takes project API keys only. Session-only actions need a signed-in user’s session cookie from the dashboard; a key or an MCP connection gets forbidden. A session’s writes must be same-origin with a JSON body, and an action on one workspace names it in the Customer-Lite-Workspace header. A session’s membership and role in the project’s or selected workspace are read when each request starts, before the action runs, so a call already running when the user is demoted or removed completes. On a session’s call, validation_error (no header), not_found (such as project not found, for a project outside the user’s workspaces), and forbidden (a role too low) can come from the header, before the input is read.

  • REST: the paths below. Input is the merge of path parameters, the query string (GET), and the JSON body. The OpenAPI document with the full JSON Schemas is served at /api/openapi.json.
  • MCP: Streamable HTTP at /mcp. A tool’s arguments are the action’s input; tools/list returns the same JSON Schemas.
  • Sending: An action that can start sending email (its errors include confirmation_invalid) first answers confirmation_required with a preview of who would be sent what and a confirmation token, and changes nothing. Show the preview to the user and wait for their answer; only if they agree, call again with the same input and confirmation set to the token. A retry of a call that succeeded with the token returns its result again; a stale or foreign token answers confirmation_invalid (409) with a fresh preview and token.
  • Errors: both surfaces return the error body below. REST returns it with the status shown, and internal_error with 500. MCP returns it as the text of a tool result with isError: true, except unauthorized, which MCP answers with HTTP 401 before any tool runs, and internal_error, which MCP answers with JSON-RPC error -32603.

Error body: an object with one field, error, which has:

  • code (“validation_error” | “unauthorized” | “forbidden” | “not_found” | “conflict” | “confirmation_invalid” | “unsupported_media_type” | “rate_limited” | “sender_not_verified” | “no_approvers” | “workspace_limit_reached” | “approval_delivery_failed” | “internal_error”, required)
  • message (string, required)
  • issues (array, optional): For validation_error: each invalid field’s path and what is wrong.
  • delivery (object, optional): For approval_delivery_failed: how many of the approval links this call sent reached their approver.
  • preview (object, optional): For confirmation_invalid: a fresh preview of the call, to show before confirming; absent when the project may not be issued a token now.
  • confirmation (object, optional): For confirmation_invalid: the token of the fresh preview, with it.
  • latestVersion (integer, optional): For conflict from workflows.upsert with expectedLatestVersion: the workflow’s latest version now; 0 when it does not exist.

Create a customer or update its email and attributes.

  • REST: PUT /api/customers/{id}
  • MCP tool: customers_upsert
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: write
  • Hints: idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), unsupported_media_type (415)

Input:

  • id (string, required)
  • email (string | null, optional)
  • attributes (object, optional)

Output:

  • id (string, required)
  • email (string | null, required)
  • attributes (object, required)
  • unsubscribed (boolean, required)
  • unsubscribedAt (integer | null, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • updatedAt (integer, required): Milliseconds since the Unix epoch.

Get a customer by its external ID.

  • REST: GET /api/customers/{id}
  • MCP tool: customers_get
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • id (string, required)

Output:

  • id (string, required)
  • email (string | null, required)
  • attributes (object, required)
  • unsubscribed (boolean, required)
  • unsubscribedAt (integer | null, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • updatedAt (integer, required): Milliseconds since the Unix epoch.

List the project’s customers, the newest created first, a page at a time. Pass a page’s nextCursor as cursor to read the next one; customers created meanwhile do not shift the pages.

  • REST: GET /api/customers
  • MCP tool: customers_list
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • limit (integer, optional, default 50)
  • cursor (string, optional): The nextCursor of the previous page, unchanged; omit it for the first page.

Output:

  • customers (array, required)
  • nextCursor (string | null, required): Pass it as cursor to read the next page; null on the last page.

Unsubscribe a customer. Pending sends are rechecked and skipped.

  • REST: POST /api/customers/{id}/unsubscribe
  • MCP tool: customers_unsubscribe
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: write
  • Hints: idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), unsupported_media_type (415)

Input:

  • id (string, required)

Output:

  • id (string, required)
  • email (string | null, required)
  • attributes (object, required)
  • unsubscribed (boolean, required)
  • unsubscribedAt (integer | null, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • updatedAt (integer, required): Milliseconds since the Unix epoch.

Record an event for an existing customer and start the workflows it triggers. Clients that may retry must send an idempotency key; a replay returns the original event ID.

  • REST: POST /api/events
  • MCP tool: events_track
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: write
  • Hints: none
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), unsupported_media_type (415)

Input:

  • customerId (string, required)
  • name (string, required)
  • properties (object, optional)
  • idempotencyKey (string, optional)

Output:

  • eventId (string, required)
  • duplicate (boolean, required)

List the project’s events, or one customer’s, the newest received first, a page at a time. Pass a page’s nextCursor as cursor to read the next one. An event whose properties’ JSON is longer than 2048 characters is listed without them, with propertiesOmitted true; no action reads them back yet.

  • REST: GET /api/events
  • MCP tool: events_list
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • customerId (string, optional): Only this customer’s events, by external ID.
  • limit (integer, optional, default 50)
  • cursor (string, optional): The nextCursor of the previous page, unchanged; omit it for the first page.

Output:

  • events (array, required)
  • nextCursor (string | null, required): Pass it as cursor to read the next page; null on the last page.

Create a workflow, or save a new version of it. Saving does not change the live version: new runs keep starting on it until the workflow is activated again, and started runs keep their version. A send step’s from is saved with its domain normalized (lower case, no trailing dot, IDNs as A-labels), so spellings of the same domain save as the same version; a from whose domain is not a domain name is a validation_error. The name, the trigger’s event, and each send step’s subject must be one line: a control character (including a line break) or a bidi embedding, override, or isolate in them is a validation_error. With expectedLatestVersion, a save that would write is refused with conflict, and the latest version in the error’s latestVersion, unless the workflow’s latest version is that one (0: the workflow does not exist yet), so a save based on an older version never replaces a newer one. Only a changed definition makes a new version: a rename alone does not, so the name is not guarded. A save that writes nothing (the same name and definition as the latest version) is answered with the workflow whatever it expects, so a retry of a save that was written is answered with it while no other save followed.

  • REST: PUT /api/workflows/{id}
  • MCP tool: workflows_upsert
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: write
  • Hints: idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), conflict (409), not_found (404), unsupported_media_type (415)

Input:

  • id (string, required)
  • name (string, required)
  • definition (object, required)
  • expectedLatestVersion (integer, optional): The latest version the caller based this save on (0 for a workflow it creates); omit it to save whatever the latest version is.

Output:

  • id (string, required)
  • name (string, required)
  • status (“draft” | “active” | “stopped”, required)
  • latestVersion (integer, required): The last version saved, whose definition this is.
  • liveVersion (integer | null, required): The version new runs start on; null until the workflow is first activated.
  • activationEpoch (integer, required)
  • reentryPolicy (“no-while-active”, required)
  • definition (object, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • updatedAt (integer, required): Milliseconds since the Unix epoch.

Make the workflow’s latest version live, so its trigger starts runs on it. A draft workflow becomes active; on an active workflow this publishes the latest version, and runs already started keep their version. Does nothing if the latest version is already live. A version that sends email goes live only after a person approves it through a link that is not sent to the caller: the workflow is left unchanged and the pending approval is returned in sendApproval. Calling again for the same version returns the same approval and sends new links. A version whose send steps’ from domains are not all verified sending domains of the workspace is refused with sender_not_verified, and one in a workspace without approvers with no_approvers; no approval is created. If a link could not be mailed to every approver, the call fails with approval_delivery_failed; calling again mails new links to those who did not get one. Sends start only on a confirmed call: called without confirmation, it changes nothing and answers confirmation_required with a preview of what would be sent and a token. Show the preview to the user, and only if they agree call again with the same input and confirmation set to the token before it expires; the result is then in result. A call that would start no sends runs at once and answers done. A retry with a used token returns the first result.

  • REST: POST /api/workflows/{id}/activate
  • MCP tool: workflows_activate
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the admin role or above
  • Scope: admin
  • Hints: none
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), rate_limited (429), sender_not_verified (422), no_approvers (422), approval_delivery_failed (502), unsupported_media_type (415), confirmation_invalid (409)

Input:

  • id (string, required)
  • confirmation (string, optional): The token from a confirmation_required answer to the same call, to commit what it previewed.

Output:

  • status (“confirmation_required” | “done”, required): confirmation_required: nothing changed; preview shows what would be sent and confirmation holds the token. done: the call ran, and result holds its result.
  • preview (object, optional): With confirmation_required: who would be sent what. Show it to the user.
  • confirmation (object, optional): With confirmation_required: the token that confirms this preview.
  • result (object, optional): With done: the action’s result.

List the project’s workflows, the most recently updated first, each with its latest version’s trigger, whether it sends email, and the approval it awaits, if any.

  • REST: GET /api/workflows
  • MCP tool: workflows_list
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • limit (integer, optional, default 100)

Output:

  • workflows (array, required)

Get a workflow with the definition of its latest version and the approval that version awaits, if any. The live version’s definition is read with workflows.getVersion.

  • REST: GET /api/workflows/{id}
  • MCP tool: workflows_get
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • id (string, required)

Output:

  • id (string, required)
  • name (string, required)
  • status (“draft” | “active” | “stopped”, required)
  • latestVersion (integer, required): The last version saved, whose definition this is.
  • liveVersion (integer | null, required): The version new runs start on; null until the workflow is first activated.
  • activationEpoch (integer, required)
  • reentryPolicy (“no-while-active”, required)
  • definition (object, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • updatedAt (integer, required): Milliseconds since the Unix epoch.
  • pendingApproval (object | null, required): The pending approval the latest version awaits before it goes live, as sendApprovals.get reports it; null when none is pending (never requested, decided, expired, or superseded).

List a workflow’s saved versions, the newest first, without their definitions: each version’s number, definition hash, whether it sends email, and when it was saved.

  • REST: GET /api/workflows/{id}/versions
  • MCP tool: workflows_listVersions
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • id (string, required)
  • limit (integer, optional, default 50)

Output:

  • versions (array, required)

Get one saved version of a workflow with its definition.

  • REST: GET /api/workflows/{id}/versions/{version}
  • MCP tool: workflows_getVersion
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • id (string, required)
  • version (integer, required)

Output:

  • workflowId (string, required)
  • version (integer, required)
  • definitionHash (string, required): SHA-256 of the version’s RFC 8785 canonical definition, which an approval binds.
  • sendsEmail (boolean, required): Whether it has a send_email step.
  • definition (object, required)
  • createdAt (integer, required): When the version was saved.

Get a send approval: the workflow version it lets go live, its status, expiry, and who decided it.

  • REST: GET /api/send-approvals/{id}
  • MCP tool: sendApprovals_get
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • id (string, required)

Output:

  • id (string, required)
  • workflowId (string, required)
  • version (integer, required): The workflow version the approval lets go live.
  • definitionHash (string, required): SHA-256 of the version’s RFC 8785 canonical definition, which the approval binds.
  • reentryPolicy (“no-while-active”, required)
  • status (“pending” | “approved” | “declined” | “cancelled” | “expired” | “superseded”, required): expired: not decided within its lifetime; superseded: the workflow has a newer latest version. Only a pending approval can be decided, by an approver through their link.
  • requestedAt (integer, required): Milliseconds since the Unix epoch.
  • expiresAt (integer, required): Milliseconds since the Unix epoch.
  • decidedBy (string | null, required): The ID of the approver who decided; null while undecided.
  • decidedAt (integer | null, required)

List a customer’s messages with their send state and delivery result.

  • REST: GET /api/messages
  • MCP tool: messages_list
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • customerId (string, required)
  • limit (integer, optional, default 50)

Output:

  • messages (array, required)

Get a message with its send state, delivery result, and step log.

  • REST: GET /api/messages/{id}
  • MCP tool: messages_get
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • id (string, required)

Output:

  • id (string, required)
  • runId (string, required)
  • stepId (string, required)
  • customerId (string, required)
  • state (“queued” | “waiting” | “sending” | “accepted” | “unknown” | “failed” | “skipped”, required)
  • reason (string | null, required)
  • attemptId (string | null, required)
  • attemptCount (integer, required)
  • providerMessageId (string | null, required)
  • providerReason (string | null, required)
  • deliveryStatus (“delayed” | “soft_bounced” | “delivered” | “content_rejected” | “bounced” | “complained” | null, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • updatedAt (integer, required): Milliseconds since the Unix epoch.
  • runLog (array, required)

Delivery metrics for the project: billable emails, deliveries, bounces, complaints.

  • REST: GET /api/metrics
  • MCP tool: metrics_get
  • Caller: a project API key, or a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the member role or above
  • Scope: read
  • Hints: read-only, idempotent
  • Errors: unauthorized (401), forbidden (403), validation_error (400), not_found (404)

Input:

  • none

Output:

  • billableEmails (integer, required)
  • delivered (integer, required)
  • bounced (integer, required)
  • complained (integer, required)

Create a workspace, with the caller as its admin. A user may create a limited number of workspaces. Clients that may retry should send an idempotency key; a replay with the same name returns the workspace the first call created. A replay with another name, or by a creator who is no longer a member of that workspace, answers conflict. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: POST /api/workspaces
  • MCP tool: workspaces_create
  • Caller: a signed-in user (session cookie) only
  • Hints: none
  • Errors: validation_error (400), unauthorized (401), forbidden (403), conflict (409), workspace_limit_reached (422), unsupported_media_type (415)

Input:

  • name (string, required)
  • idempotencyKey (string, optional)

Output:

  • id (string, required)
  • name (string, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • role (“member” | “admin”, required): The caller’s role in the workspace.

List the workspaces the caller is a member of, with the caller’s role in each. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: GET /api/workspaces
  • MCP tool: workspaces_list
  • Caller: a signed-in user (session cookie) only
  • Hints: read-only, idempotent
  • Errors: unauthorized (401), forbidden (403)

Input:

  • none

Output:

  • workspaces (array, required)

Get the workspace the Customer-Lite-Workspace header selects; the caller must be a member of it. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: GET /api/workspace
  • MCP tool: workspaces_get
  • Caller: a signed-in user (session cookie) in the workspace the Customer-Lite-Workspace header names, with the member role or above only
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • none

Output:

  • id (string, required)
  • name (string, required)
  • createdAt (integer, required): Milliseconds since the Unix epoch.

List the members of the workspace the Customer-Lite-Workspace header selects, oldest first, with their addresses and roles. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: GET /api/workspace/members
  • MCP tool: members_list
  • Caller: a signed-in user (session cookie) in the workspace the Customer-Lite-Workspace header names, with the member role or above only
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • none

Output:

  • members (array, required)

Add a user to the workspace the Customer-Lite-Workspace header selects, by the address they sign in with, with a role. The user must have signed in before; no invitation is sent. While anyone may sign in to the installation, it answers forbidden until invitations exist. Adding a member again with the same role returns them, so a retry succeeds; with another role it answers conflict. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: POST /api/workspace/members
  • MCP tool: members_add
  • Caller: a signed-in user (session cookie) in the workspace the Customer-Lite-Workspace header names, with the admin role or above only
  • Hints: idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), unsupported_media_type (415)

Input:

  • email (string, required)
  • role (“member” | “admin”, required)

Output:

  • userId (string, required)
  • email (string, required): The address the member signs in with.
  • role (“member” | “admin”, required)
  • createdAt (integer, required): When the user became a member.

Set the role of a member of the workspace the Customer-Lite-Workspace header selects. Demoting the workspace’s last admin answers conflict: a workspace always keeps an admin. On a self-hosted installation, demoting an installation admin (a user whose address ADMIN_EMAILS lists) answers conflict too. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: PUT /api/workspace/members/{userId}/role
  • MCP tool: members_setRole
  • Caller: a signed-in user (session cookie) in the workspace the Customer-Lite-Workspace header names, with the admin role or above only
  • Hints: idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), unsupported_media_type (415)

Input:

  • userId (string, required)
  • role (“member” | “admin”, required)

Output:

  • userId (string, required)
  • email (string, required): The address the member signs in with.
  • role (“member” | “admin”, required)
  • createdAt (integer, required): When the user became a member.

Remove a member from the workspace the Customer-Lite-Workspace header selects; an admin may remove themselves. Removing the workspace’s last admin answers conflict: a workspace always keeps an admin. Removing someone who is not a member answers not_found, so a retry after success does too. On a self-hosted installation, removing an installation admin (a user whose address ADMIN_EMAILS lists) answers conflict too. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: POST /api/workspace/members/{userId}/remove
  • MCP tool: members_remove
  • Caller: a signed-in user (session cookie) in the workspace the Customer-Lite-Workspace header names, with the admin role or above only
  • Hints: destructive
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), unsupported_media_type (415)

Input:

  • userId (string, required)

Output:

  • userId (string, required)
  • removed (boolean, required)

Create the project of the workspace the Customer-Lite-Workspace header selects. A workspace has one project for now, so a second answers conflict. Clients that may retry should send an idempotency key; a replay returns the project the first call created. An internal error may leave the project created; retry (with the same key, or without one, which answers conflict) to finish it. The project’s ID is what a session names in the Customer-Lite-Project header to call the project actions. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: POST /api/workspace/projects
  • MCP tool: projects_create
  • Caller: a signed-in user (session cookie) in the workspace the Customer-Lite-Workspace header names, with the admin role or above only
  • Hints: none
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), unsupported_media_type (415)

Input:

  • idempotencyKey (string, optional)

Output:

  • id (string, required): The project’s ID, which a session names in the Customer-Lite-Project header.
  • createdAt (integer, required): Milliseconds since the Unix epoch.

List the projects of the workspace the Customer-Lite-Workspace header selects, oldest first. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: GET /api/workspace/projects
  • MCP tool: projects_list
  • Caller: a signed-in user (session cookie) in the workspace the Customer-Lite-Workspace header names, with the member role or above only
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • none

Output:

  • projects (array, required)

Create a secret API key (cl_sk_) for the project the Customer-Lite-Project header selects. The key acts on that project with every API scope. Its plaintext is in this response only: it is stored hashed, and every other response shows its prefix and last four characters. Clients that may retry should send an idempotency key; since the plaintext cannot be shown again, a replay answers conflict and names the key the first call created, which the caller can revoke if the plaintext was lost. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: POST /api/api-keys
  • MCP tool: apiKeys_create
  • Caller: a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the admin role or above only
  • Hints: none
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), conflict (409), unsupported_media_type (415)

Input:

  • idempotencyKey (string, optional)

Output:

  • key (object, required)
  • secret (string, required): The key itself (cl_sk_…), as a Bearer token. Shown in this response only.

List the API keys of the project the Customer-Lite-Project header selects, revoked ones included, oldest first. Each shows its ID, prefix, and last four characters; never the key. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: GET /api/api-keys
  • MCP tool: apiKeys_list
  • Caller: a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the admin role or above only
  • Hints: read-only, idempotent
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404)

Input:

  • none

Output:

  • keys (array, required)

Revoke an API key of the project the Customer-Lite-Project header selects: from the next request on, the key answers unauthorized. Revoking a revoked key returns it unchanged. An ID that names no key of this project answers not_found. Needs a signed-in user’s session; an API key or an MCP connection gets forbidden.

  • REST: POST /api/api-keys/{id}/revoke
  • MCP tool: apiKeys_revoke
  • Caller: a signed-in user (session cookie) in the project the Customer-Lite-Project header names, with the admin role or above only
  • Hints: idempotent, destructive
  • Errors: validation_error (400), unauthorized (401), forbidden (403), not_found (404), unsupported_media_type (415)

Input:

  • id (string, required)

Output:

  • id (string, required): The key’s ID, which apiKeys.revoke takes; not the key.
  • prefix (string, required): The key’s type prefix: cl_sk_ for a secret key.
  • last4 (string, required): The last four characters of the key.
  • createdAt (integer, required): Milliseconds since the Unix epoch.
  • createdBy (string | null, required): The ID of the user who created it; null for a key made before users.
  • revokedAt (integer | null, required): When it was revoked; null while it authenticates.