Agents

List and retrieve agent information.

List Agents

GET /v1/agents

Returns a paginated list of your agents.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Items per page (1-100)
`cursor`	string	-	Pagination cursor
`name`	string	-	Filter by agent name

Request

curl https://api.vm0.ai/v1/agents \
  -H "Authorization: Bearer vm0_live_xxx"

Filter by name:

curl "https://api.vm0.ai/v1/agents?name=my-agent" \
  -H "Authorization: Bearer vm0_live_xxx"

Response

{
  "data": [
    {
      "id": "ag_abc123",
      "name": "my-agent",
      "currentVersionId": "v1_xyz789",
      "createdAt": "2024-01-15T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

Get Agent

GET /v1/agents/:id

Retrieves an agent's details.

Path Parameters

Parameter	Type	Description
`id`	string	Agent ID

Request

curl https://api.vm0.ai/v1/agents/ag_abc123 \
  -H "Authorization: Bearer vm0_live_xxx"

Response

{
  "id": "ag_abc123",
  "name": "my-agent",
  "currentVersionId": "v1_xyz789",
  "createdAt": "2024-01-15T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

List Agent Versions

GET /v1/agents/:id/versions

Returns a paginated list of all versions for an agent.

Path Parameters

Parameter	Type	Description
`id`	string	Agent ID

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Items per page (1-100)
`cursor`	string	-	Pagination cursor

Request

curl https://api.vm0.ai/v1/agents/ag_abc123/versions \
  -H "Authorization: Bearer vm0_live_xxx"

Response

{
  "data": [
    {
      "id": "v1_xyz789",
      "agentId": "ag_abc123",
      "versionNumber": 2,
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "v1_abc123",
      "agentId": "ag_abc123",
      "versionNumber": 1,
      "createdAt": "2024-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

Agent Object

Field	Type	Description
`id`	string	Unique agent identifier (prefix: `ag_`)
`name`	string	Agent name
`currentVersionId`	string	ID of the current version
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp

Version Object

Field	Type	Description
`id`	string	Unique version identifier
`agentId`	string	Parent agent ID
`versionNumber`	integer	Sequential version number
`createdAt`	string	ISO 8601 creation timestamp

On this page