JavaScript
Workspaces
List workspaces
Every workspace your token can reach. One of the few routes with no workspace in its path.
GET
JavaScript
A workspace isolates resources: agents, tool sets, memory, secrets, objectives. This endpoint tells you which ones the token in your hand can touch.
An API key is account-scoped and reaches only the workspaces it has been granted, which is exactly what this returns.
Reference pages write paths in full. Prose across the guides drops the
Set
Pair this endpoint with
A profile is a person or a machine inside an account, and it moves between workspaces without a fresh invite.
Most of the API is workspace-scoped
Sixty-five of the API’s eighty-one routes sit under/v1/workspaces/{workspaceId}/. Agents, tool sets, objectives, memory, secrets, and schedules all live inside a workspace, which is the isolation boundary between staging and production, or between one tenant and the next.
The rest are account-scoped or identity-scoped:
/v1/workspaces/{workspaceId}/ prefix for readability, so POST /objectives means POST /v1/workspaces/{workspaceId}/objectives.
The workspace segment takes an external ID
Anywhere a Cadenya ID appears, including the workspace path segment, your own ID works:metadata.externalId on a workspace once and a full URL never mentions a Cadenya ID:
Name the workspace, do not infer it
Pick a workspace deliberately. A setup script that discovers one and creates an agent in it is a script that eventually creates an agent in production./v1/whoami when a tool needs to show a human which workspaces they can act on, and let them choose.
Which identity is asking
whoami names the one behind the current token.
Related
Use your own IDs
external_id: resolves in the workspace segment too.API design
Why the account holds keys and the workspace holds everything else.
Get the current profile
Which identity the token carries.
Create an agent
The first thing you build inside a workspace.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Maximum number of results to return
Pagination cursor from previous response
Sort order for results (asc or desc by creation time)
When set to true you may use more of your alloted API rate-limit
Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).