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/listreturns the same JSON Schemas. - Sending: An action that can start sending email (its errors include
confirmation_invalid) first answersconfirmation_requiredwith apreviewof who would be sent what and aconfirmationtoken, and changes nothing. Show the preview to the user and wait for their answer; only if they agree, call again with the same input andconfirmationset to the token. A retry of a call that succeeded with the token returns its result again; a stale or foreign token answersconfirmation_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_errorwith 500. MCP returns it as the text of a tool result withisError: true, exceptunauthorized, which MCP answers with HTTP 401 before any tool runs, andinternal_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.
customers.upsert
Section titled “customers.upsert”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-Projectheader names, with thememberrole 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.
customers.get
Section titled “customers.get”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-Projectheader names, with thememberrole 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.
customers.list
Section titled “customers.list”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-Projectheader names, with thememberrole 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): ThenextCursorof the previous page, unchanged; omit it for the first page.
Output:
customers(array, required)nextCursor(string | null, required): Pass it ascursorto read the next page; null on the last page.
customers.unsubscribe
Section titled “customers.unsubscribe”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-Projectheader names, with thememberrole 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.
events.track
Section titled “events.track”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-Projectheader names, with thememberrole 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)
events.list
Section titled “events.list”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-Projectheader names, with thememberrole 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): ThenextCursorof the previous page, unchanged; omit it for the first page.
Output:
events(array, required)nextCursor(string | null, required): Pass it ascursorto read the next page; null on the last page.
workflows.upsert
Section titled “workflows.upsert”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-Projectheader names, with thememberrole 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.
workflows.activate
Section titled “workflows.activate”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-Projectheader names, with theadminrole 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 aconfirmation_requiredanswer to the same call, to commit what it previewed.
Output:
status(“confirmation_required” | “done”, required): confirmation_required: nothing changed;previewshows what would be sent andconfirmationholds the token. done: the call ran, andresultholds 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.
workflows.list
Section titled “workflows.list”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-Projectheader names, with thememberrole 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)
workflows.get
Section titled “workflows.get”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-Projectheader names, with thememberrole 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).
workflows.listVersions
Section titled “workflows.listVersions”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-Projectheader names, with thememberrole 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)
workflows.getVersion
Section titled “workflows.getVersion”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-Projectheader names, with thememberrole 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.
sendApprovals.get
Section titled “sendApprovals.get”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-Projectheader names, with thememberrole 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)
messages.list
Section titled “messages.list”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-Projectheader names, with thememberrole 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)
messages.get
Section titled “messages.get”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-Projectheader names, with thememberrole 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)
metrics.get
Section titled “metrics.get”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-Projectheader names, with thememberrole 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)
workspaces.create
Section titled “workspaces.create”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.
workspaces.list
Section titled “workspaces.list”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)
workspaces.get
Section titled “workspaces.get”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-Workspaceheader names, with thememberrole 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.
members.list
Section titled “members.list”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-Workspaceheader names, with thememberrole or above only - Hints: read-only, idempotent
- Errors:
validation_error(400),unauthorized(401),forbidden(403),not_found(404)
Input:
- none
Output:
members(array, required)
members.add
Section titled “members.add”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-Workspaceheader names, with theadminrole 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.
members.setRole
Section titled “members.setRole”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-Workspaceheader names, with theadminrole 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.
members.remove
Section titled “members.remove”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-Workspaceheader names, with theadminrole 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)
projects.create
Section titled “projects.create”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-Workspaceheader names, with theadminrole 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.
projects.list
Section titled “projects.list”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-Workspaceheader names, with thememberrole or above only - Hints: read-only, idempotent
- Errors:
validation_error(400),unauthorized(401),forbidden(403),not_found(404)
Input:
- none
Output:
projects(array, required)
apiKeys.create
Section titled “apiKeys.create”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-Projectheader names, with theadminrole 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.
apiKeys.list
Section titled “apiKeys.list”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-Projectheader names, with theadminrole or above only - Hints: read-only, idempotent
- Errors:
validation_error(400),unauthorized(401),forbidden(403),not_found(404)
Input:
- none
Output:
keys(array, required)
apiKeys.revoke
Section titled “apiKeys.revoke”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-Projectheader names, with theadminrole 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.