Skip to main content
The Cadenya API provides access to Tool Sets, Agents, Objectives, Memory Layers, and the rest of the Cadenya platform. Endpoint pages come from the OpenAPI specification and define each request, response, and permission requirement.

​
Base URL

Prefix API paths with:

​
Authentication

Send a bearer token in the Authorization header using the value returned when you create or rotate an API key: Authorization: Bearer <token>.

​
Keys and workspaces

API keys belong to the account. Each key reaches the workspaces you assign it to, or every workspace, including ones you create later, when allWorkspaces is set. A key’s scopes are the same in every workspace it reaches. Create keys on the API keys page, with Create a new API key (POST /v1/account/api_keys), or with cadenya api-keys create. Creating or changing a key that reaches every workspace also takes the api_keys:admin scope. API keys covers scopes and the CLI commands. Each key has a set of permission scopes. A scope uses the resource:verb form, such as objectives:manage. The manage verb includes read, and * grants full access. A key with no scopes can call endpoints that do not require a scope. Cadenya returns the bearer token when you create or rotate a key, and later reads omit it. To get a token again, call Reveal an API key’s token or run cadenya api-keys reveal <id>, which issues a new token and leaves earlier ones working. Disable a key to stop authentication without deleting the key record.

​
Resource scope

An account contains one or more workspaces. Most resources belong to a workspace, and their paths start with /v1/workspaces/{workspaceId}. The workspace boundary isolates agents, Tool Sets, memory, secrets, and objectives. Account-scoped endpoints omit the workspace segment.

​
Resource identity

​
Cadenya IDs and external IDs

Each resource has a Cadenya ID in metadata.id. Resources that expose metadata.externalId also accept an ID from your application at creation. Pass external_id:<value> anywhere an endpoint accepts an external ID in place of a Cadenya ID. External IDs let you use an identifier from your application without storing a second mapping. Resolution stays within the account, workspace, and parent resource established by the endpoint path.

​
Labels

metadata.labels stores string-to-string tags for filtering and grouping. List endpoints that support label filters accept comma-separated key=value pairs in the labels query parameter. A resource must match every pair exactly. Label keys and values contain up to 63 alphanumeric characters, with -, _, or . between characters. Keys can include a DNS subdomain prefix such as cadenya.com/.

​
Updates and field masks

Most resource update endpoints use PATCH requests with an updateMask field. The mask names the fields Cadenya changes. Fields outside the mask keep their current values, even when the request body omits them. Operation-specific updates can expose a fixed set of mutable fields without a mask. Field paths follow the request shape, such as metadata.name or spec.description. Some repeated fields use replacement semantics. For example, including spec.overlays in a Tool Set update replaces the stored list. Read the endpoint schema before updating a repeated field.

​
List requests

List endpoints expose a subset of these query parameters: List responses contain items and pagination.nextCursor. Pass nextCursor as cursor to request the next page. An empty cursor marks the end of the result set. Responses do not include a total count.

​
Clients

Browse the endpoint groups in the sidebar for operation-specific parameters and schemas.