List agents available to the caller

GET

/v1/agents

curl --request GET \
  --url https://www.cemented.ai/v1/agents \
  --header 'Authorization: Bearer <token>'

Returns every agent the caller can invoke — personal agents plus agents in projects they belong to, newest first. Pass an agent’s id as agent_id on /v1/responses to run a turn as that agent. A prompt agent’s directions are appended to the system prompt; a code agent runs its committed implementation. Agents are created and managed in the Cemented app, not via this API.

Authorizations

• BearerAuth
• ApiKeyHeader

Responses

200

List of agents the caller can invoke

Media type application/json

object

object

required

string

Allowed values: list

data

required

Array<object>

object

id

required

Pass this as agent_id on /v1/responses.

string format: uuid

object

required

string

Allowed values: agent

handle

required

The @handle used to invoke the agent in chat.

string

description

required

string

kind

required

A prompt agent’s directions are appended to the system prompt; a code agent runs its committed implementation.

string

Allowed values: prompt code

project_id

required

Project the agent is shared through, or null for a personal agent.

string | null format: uuid

created_at

required

Unix timestamp in seconds.

integer

Example

{
  "object": "list",
  "data": [
    {
      "id": "9c1d2e3f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
      "object": "agent",
      "handle": "grant-researcher",
      "description": "Research a grant opportunity and return an evidence-backed eligibility summary.",
      "kind": "code",
      "project_id": null,
      "created_at": 1765238400
    },
    {
      "id": "2f7a1b9c-3d4e-4f5a-9b8c-7d6e5f4a3b2c",
      "object": "agent",
      "handle": "research-bot",
      "description": "SEC-filings research persona.",
      "kind": "prompt",
      "project_id": "c0ffee00-1234-4abc-8def-426614174000",
      "created_at": 1765152000
    }
  ]
}

401

Unauthorized

Media type application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}

500

Server error while listing agents

Media type application/json

object

error

required

object

message

required

string

type

required

string

code

required

string

Example ^generated

{
  "error": {
    "message": "example",
    "type": "example",
    "code": "example"
  }
}