:List agent versions

Request headers

Header	Required	Description
Authorization	Yes	Bearer <PAT>

Path parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Unique agent identifier.

Query parameters

Parameter	Type	Required	Default	Description
limit	integer	No	20	Number of results per page.
order	string	No	desc	Sort direction. Either "asc" or "desc".
after_id	string	No	-	Cursor. Return records after this version.
before_id	string	No	-	Cursor. Return records before this version.

See Pagination for cursor semantics.

Example request

curl -X GET "https://api.qoder.com.cn/api/v1/cloud/agents/agent_019eXXXX.../versions" \
  -H "Authorization: Bearer $QODER_PAT"

Example response

HTTP 200 OK

{
  "data": [
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent-updated",
      "description": "Used for API documentation testing.",
      "model": "ultimate",
      "system": "You are the updated documentation test assistant.",
      "instructions": "You are the updated documentation test assistant.",
      "tools": [],
      "mcp_servers": [],
      "default_environment": "",
      "version": 2,
      "created_at": "2026-05-18T15:26:39.61669Z",
      "updated_at": "2026-05-18T15:27:07.967138Z"
    },
    {
      "type": "agent",
      "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "doc-test-agent",
      "description": "",
      "model": "ultimate",
      "system": "You are a documentation test assistant.",
      "instructions": "You are a documentation test assistant.",
      "tools": [],
      "mcp_servers": [],
      "default_environment": "",
      "version": 1,
      "created_at": "2026-05-18T15:26:39.61669Z",
      "updated_at": "2026-05-18T15:26:39.61669Z"
    }
  ],
  "first_id": "2",
  "last_id": "1",
  "has_more": false
}

Response fields

Field	Type	Description
data	array	Array of agent version snapshots. Each element is a full agent object at the time of that version.
first_id	string	Version identifier of the first record on the current page.
last_id	string	Version identifier of the last record on the current page.
has_more	boolean	Whether additional version records are available.

Version history behavior

• Every PUT update to an agent creates a new version.

• Version numbers start at 1 and increment by one.

• Each version stores a full agent snapshot at the time of the change.

• Use this endpoint to audit change history or as a reference for rollback.

Errors

HTTP	Type	Trigger
401	authentication_error	PAT is invalid or has expired.
403	permission_error	Caller is not authorized to access this agent.
404	not_found_error	No agent exists with the given ID.

See Errors for the full error envelope.

Notes

• first_id and last_id at this endpoint are the string forms of version numbers, for example "1" or "2".

• Results are ordered by version number in descending order by default (newest first).

• Combine with the optimistic concurrency (OCC) checks on PUT to track configuration changes over time.