Skip to main content
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.

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:
Reference pages write paths in full. Prose across the guides drops the /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:
Set 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.
Pair this endpoint with /v1/whoami when a tool needs to show a human which workspaces they can act on, and let them choose.

Which identity is asking

A profile is a person or a machine inside an account, and it moves between workspaces without a fresh invite. whoami names the one behind the current token.

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

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

limit
integer<int32>

Maximum number of results to return

cursor
string

Pagination cursor from previous response

sortOrder
string

Sort order for results (asc or desc by creation time)

includeInfo
boolean

When set to true you may use more of your alloted API rate-limit

labels
string

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).

Response

OK

items
object[]
pagination
object

Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list.