List agent versions

List the version history of an Agent in descending order by version number.

GET /api/v1/cloud/agents/{agent_id}/versions

Returns the version history of the specified Agent, sorted by version number in descending order (newest first).

Headers

Header	Required	Description
Authorization	Yes	Bearer <PAT>

Path parameters

Parameter	Type	Required	Description
agent_id	string	Yes	Agent unique identifier

Query parameters

Parameter	Type	Required	Default	Description
limit	integer	No	20	Items per page. Range 1-100; values above 100 return 400 invalid_request_error
page	string	No	-	Cursor returned by the previous response’s next_page

See Pagination for cursor semantics.

Example request

curl -X GET "https://api.qoder.com/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 an updated documentation testing assistant.",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "multiagent": null,
      "version": 2,
      "archived_at": null,
      "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 testing assistant.",
      "tools": [],
      "mcp_servers": [],
      "skills": [],
      "metadata": {},
      "multiagent": null,
      "version": 1,
      "archived_at": null,
      "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,
  "next_page": null
}

Response fields

Field	Type	Description
data	array of Agent version snapshot	Version snapshots on the current page
first_id	string	Version identifier of the first record on this page
last_id	string	Version identifier of the last record on this page
has_more	boolean	Whether more versions remain
next_page	string|null	Cursor for the next page. Equals last_id when has_more is true, otherwise null

Version history

• Creating an Agent stores version 1.
• Every successful update stores the next version.
• Each version stores the full Agent snapshot at that point in time.
• Useful for auditing changes or reference during rollback.

Errors

HTTP	Type	Trigger
400	invalid_request_error	limit is not a positive integer
400	invalid_request_error	Invalid pagination cursor
400	invalid_request_error	page is not a positive integer version cursor
401	authentication_error	PAT invalid or expired
403	permission_error	Not authorized for this Agent
404	not_found_error	Agent with the given ID does not exist

See Errors for the full error envelope.

Notes

• For this endpoint, first_id and last_id are the version numbers as strings (such as "1", "2").
• Versions are sorted in descending order by default (latest first).
• Archiving an Agent does not create a new version snapshot.
• Combine with the OCC mechanism on POST /api/v1/cloud/agents/{agent_id} to track configuration changes.

Related

Agent setup

Create a reusable, versioned agent configuration.