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 Build 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 4 hours. Tokens are read-only unless you pass readonly: false.

POST/api/v1/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 read surface.	—
`courseId`	`number`	No	Pin the token to a single course.	—
`expiresIn`	`string`	No	Lifetime as <n>h\|m\|s; default 4h.	—
`readonly`	`boolean`	No	Omitted or true = read-only. Pass false for write access.	—

Examples

cURL request

curl --request POST \
  --url "https://api.coassemble.com/api/v1/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": "example"
}

List tools Build and above

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

GET/api/v1/agent/tools

Query parameters

Field	Type	Required	Default	Options
`identifier`	`string`	No	—	—
`clientIdentifier`	`string`	No	—	—
`courseId`	`string`	No	—	—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/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 Build and above

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

POST/api/v1/agent/tools/{name}

Path parameters

Field	Description	Options
`name`		—

Body parameters

Field	Type	Required	Options
`args`	`object`	No	—
`courseId`	`number`	No	—
`identifier`	`string`	No	—
`clientIdentifier`	`string`	No	—

Examples

cURL request

curl --request POST \
  --url "https://api.coassemble.com/api/v1/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"
}