Agent

Mint an agent token, list the tools available to a caller, and run them over REST. The agent operates the course lifecycle — create, edit, publish, share, analyse, translate, narrate, and organise courses. For MCP-speaking clients, see Embed MCP.

Mint an agent token Scale and above

Create a bearer token the agent acts with. Authenticate with your workspace API key. The token encodes the end-user identity, an optional tenant key, an optional tool allowlist, an optional course pin, and a read-only flag. Default lifetime is 30 days.

POST/agent/auth

Body parameters

Field	Type	Required	Desc	Options
`identifier`	`string`	Yes	Your stable end-user identifier the agent acts as.	—
`clientIdentifier`	`string`	No	Tenant key (omit for workspace-default scope).	—
`tools`	`string[]`	No	Per-token tool allowlist; omit for the full surface.	—
`courseId`	`integer`	No	Pin the token to a single course.	—
`expiresIn`	`string`	No	Lifetime as <n>h\|m\|s; default 720h (30 days).	—
`readonly`	`boolean`	No	When true, the token may only run read tools.	—

Examples

cURL request

curl --request POST \
  --url "https://api.coassemble.com/agent/auth" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "identifier": "user_123",
    "clientIdentifier": "client_123",
    "tools": [
        "example"
    ],
    "courseId": 1234
}'

Response

JSON response

{
  "token": "example",
  "expiresAt": "2026-08-18T21:50:27.650Z"
}

List tools Scale and above

List the tools the caller may run. Authenticate with the agent token (Bearer) or your workspace API key.

GET/agent/tools

Query parameters

Field	Type	Required	Default	Description	Options
`identifier`	`string`	No	—	API-key callers only; token callers use the token identity.	—
`clientIdentifier`	`string`	No	—	API-key callers only; tenant key.	—
`courseId`	`string`	No	—	Scope tool availability to a course.	—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/agent/tools?identifier=user_123&clientIdentifier=client_123&courseId=1234" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

{
  "tools": [
    {
      "name": "example",
      "description": "example"
    }
  ]
}

Run a tool Scale and above

Execute a tool by name with its arguments. Authenticate with the agent token (Bearer) or your workspace API key.

POST/agent/tools/{name}

Path parameters

Field	Description	Options
`name`	Tool name (see List tools).	—

Body parameters

Field	Type	Required	Desc	Options
`args`	`object`	No	Tool arguments.	—
`courseId`	`integer`	No	Course to act on (ignored if the token is course-pinned).	—
`identifier`	`string`	No	API-key callers only; identity the agent acts as.	—
`clientIdentifier`	`string`	No	API-key callers only; tenant key.	—

Examples

cURL request

curl --request POST \
  --url "https://api.coassemble.com/agent/tools/example" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "args": {
        "key": "value"
    },
    "courseId": 1234,
    "identifier": "user_123",
    "clientIdentifier": "client_123"
}'

Response

JSON response

{
  "name": "example"
}