Skip to main content
GET /v1/agents/{agent_id}/versions Returns the version history of the specified Agent, sorted by version number in descending order (newest first).

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>

​
Path parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent unique identifier

​
Query parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo20Items per page. Must be positive; values above 100 are capped at 100
after_idstringNo-Positive integer version cursor; returns older versions after this cursor in descending version order. Do not combine with before_id
before_idstringNo-Positive integer version cursor; returns newer versions before this cursor in descending version order. Do not combine with after_id
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": {},
      "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": {},
      "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
}

​
Response fields

FieldTypeDescription
dataarray of Agent version snapshotVersion snapshots on the current page
first_idstringVersion identifier of the first record on this page
last_idstringVersion identifier of the last record on this page
has_morebooleanWhether more versions remain

​
Version history

  • Creating an Agent stores version 1.
  • Every successful PUT on an Agent 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

HTTPTypeTrigger
400invalid_request_errorlimit is not a positive integer
400invalid_request_errorBoth before_id and after_id were provided
400invalid_request_errorbefore_id or after_id is not a positive integer version
401authentication_errorPAT invalid or expired
403permission_errorNot authorized for this Agent
404not_found_errorAgent 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 PUT to track configuration changes.

Agent setup

Create a reusable, versioned agent configuration.