curl --request POST \
  --url https://asteragents.com/api/agents/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": 1,
  "action": "rollback",
  "versionId": 17
}
'

{
  "success": true,
  "publishedVersionId": 17
}

{
  "error": "User is not part of any organization"
}

{
  "error": "Bad Request",
  "details": [
    {}
  ]
}

{
  "error": "Internal Server Error"
}

Agents API

Roll back to a version, or save a labeled checkpoint

Two actions on an agent’s version history:

rollback: restore the agent’s live config from an earlier snapshot. This rewrites the live agent row (the source of truth the runtime reads) and repoints publishedVersionId — so the change takes effect immediately. Requires versionId.
checkpoint: append a version snapshotting the current live config, with an optional label. Useful for marking a known-good state before a round of edits. De-duplicated if nothing changed.

Requires agent management permission or org:admin.

POST

agents

versions

curl --request POST \
  --url https://asteragents.com/api/agents/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": 1,
  "action": "rollback",
  "versionId": 17
}
'

{
  "success": true,
  "publishedVersionId": 17
}

{
  "error": "User is not part of any organization"
}

{
  "error": "Bad Request",
  "details": [
    {}
  ]
}

{
  "error": "Internal Server Error"
}

Authorizations

Authorization

string

header

required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Body

application/json

agentId

integer

required

Example:

1

action

enum<string>

required

Available options:

rollback,

checkpoint

versionId

integer

Version to restore (required when action is rollback)

Example:

17

label

string

Optional note for the version (used when action is checkpoint)

Example:

"before reworking the system prompt"

Response

Action completed

success

boolean

publishedVersionId

integer

The version now reflected by the agent's live config

API Documentation

Admin API

Files API

Agents API

Tools API

Agent Tags API

Knowledge Bases API

Skills API

Conversations API

Scheduled Tasks API

Other Endpoints

Legacy Endpoints (Deprecated)

Roll back to a version, or save a labeled checkpoint

Authorizations

Body

Response