Versions

An agent version is a numbered snapshot of which version of every primitive an agent runs. These routes create, list, inspect, diff, promote, and delete them; promoting is also the rollback path. The CLI twin is lua version. Verified against lua-cli 3.33.0.

Base URL and authentication

Every route checks an agents scope on the agent in the path: agents:read reads and diffs, agents:write creates, promotes, and patches the commit hash, and agents:manage deletes. The host, the bearer header, and the error envelope are on the REST API overview.

Agent version object

string

Record ID.

string

The agent.

string

The agent’s base ID.

string

Owning organization.

number

Version number, increasing per agent.

string

staged (created, not live), active (live), superseded (was live), or deleted (soft-deleted).

object

The pinned primitive versions.

Show properties

object[]

Each { skillId, versionId, version, name? }.

object[]

Each { webhookId, versionId, version, name? }.

object[]

Each { jobId, versionId, version, name? }.

object[]

Each { id, versionId, version, name? }.

object[]

Each { id, versionId, version, name? }.

object[]

Each { triggerId, versionId, version, name? }. Absent on agent versions that predate triggers.

object[]

Each { workflowId, versionId, version, name? }, the latest pushed version of each workflow. Present only when the agent has a pushed workflow.

object[]

Each { id, configHash, name?, config? }. MCP servers are unversioned, so the agent version pins a hash of their configuration.

object

{ versionId, version?, contentHash? }.

string

Model code.

object

{ voiceId, versionId, version, name? }, the agent’s default voice. Absent when the agent has no default voice.

number

Source backup version the agent version was taken from, when given.

string

Description given at creation.

string

Git commit associated with the version.

string

User ID of the creator.

string

Creator email; added on list and read when the user is known.

string

ISO timestamp.

string

ISO timestamp of the last promote.

string

Who made the last promote, recorded by the platform from the credential that made it: user:<userId> for a user session, apiKey:<keyId> for a scoped API key, or service:agent:<agentId> for a supervising agent. Absent on versions promoted before this field existed, and on a version whose promote was rolled back. A value sent in the request body is ignored. lua version show <n> --json prints it.

boolean

Set when a promote had to roll back and the rollback did not complete.

string

The rollback error, when any.

Endpoints

GET /developer/agents/:agentId/versioning/mode

Reports whether agent versioning is enabled. Scope agents:read. Versioning is enabled for every agent; the route is kept so older CLIs that probe it keep working. Response 200 with { "enabled": true }.

POST /developer/agents/:agentId/versions

Snapshots the latest pushed version of every primitive into a new staged version. Scope agents:write. Equivalent: lua version create -m "<message>"; with --commit-hash or after its own git commit, the CLI also patches the hash through the commit-hash route.

string

Description. Maximum 500 characters.

number

Source backup version to record.

string

Git commit to record.

Response 201 with the created agent version object. 409 NO_STAGED_CHANGES when nothing changed since the last version; 400 AGENT_VERSION_LIMIT_REACHED when the agent already has 100 versions.

GET /developer/agents/:agentId/versions

Lists versions, newest first. Scope agents:read. Equivalent: lua version list.

boolean

default:false

Return every version instead of the first limit.

number

default:50

Maximum entries.

string

default:"all"

active, staged, superseded, deleted, or all.

Response 200 with an array of agent version objects without snapshot.

GET /developer/agents/:agentId/versions/diff

Compares two versions. Scope agents:read. Equivalent: lua version diff <from> <to>.

number

required

Older version number.

number

required

Newer version number.

Response

number

The compared versions.

object

Each { added, removed, changed }; entries carry the primitive’s ID field, versionId, version, and name?, and changed entries carry from and to as { versionId, version }.

object

{ added, removed, changed } keyed by id and configHash; changed entries carry from, to, and changedFields?.

object | null

{ from, to, fromVersion?, toVersion? } when the persona changed.

object | null

{ from, to } when the model changed.

object | null

{ voiceId, from, to } when the default voice changed.

GET /developer/agents/:agentId/versions/:version

Returns one agent version object with its full snapshot. Scope agents:read. Equivalent: lua version show <n>.

POST /developer/agents/:agentId/versions/:version/promote

Makes a version live for every primitive at once; the previously active version becomes superseded. Scope agents:write. Send an empty JSON object as the body, or expectActive to promote only while the live version is still the one you expect. Equivalent: lua version promote <n>. Promoting an older version is the rollback. Body

number | null

The version you expect to be active right now, or null for “no version is active”. When the live version is different, the promote writes nothing and answers 409 PROMOTE_CONFLICT. Omit it to promote unconditionally, as before. See Promote safely.

Response 200 with { promoted, previousActive }: the now-active version number and the one it replaced (null when none was active). The promoted version records promotedBy.

DELETE /developer/agents/:agentId/versions/:version

Soft-deletes a version. Scope agents:manage. The active version and the last remaining version cannot be deleted. Equivalent: lua version delete <n>. Response 200 with { deleted: true, version }.

PATCH /developer/agents/:agentId/versions/:version/commit-hash

Records the git commit for a version. Scope agents:write. Idempotent. lua version create calls it after committing and tagging.

string

required

The commit SHA.

Response 200 with { "ok": true }.

Promote safely

Two promotes that race, for example a person and an automation, used to leave the last writer live. Send expectActive with the version you read from the version list, and a promote that lost the race is refused instead of overwriting the other:

curl -X POST "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/versions/5/promote" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "expectActive": 4 }'

Output

{ "error": { "code": "PROMOTE_CONFLICT", "message": "…", "expected": 4, "active": 6 } }

expected is what you sent and active is the version that is live now. Read the state again and decide rather than retrying blindly. The check runs inside the promote, so when two promotes send the same expectActive at once, only one succeeds. lua version promote does not send expectActive; call the route directly when you need the check. The same check exists for persona activation. If a promote fails part-way and rolls back after another promote has already made its own version live, the rollback leaves that other promote in place and marks the failed version superseded, so an agent never ends up with two active versions.

Scoped promotes from single-primitive deploys

Publishing a version of a webhook, job, preprocessor, postprocessor, trigger, or workflow through that primitive’s own publish route, which is what lua deploy <type> calls, also creates and promotes an agent version scoped to that change: the platform clones the active agent version with the one primitive repointed and makes the clone active, so the live agent runs the code it published without a separate promote. The publish response carries the new agent version number. When the code was published but the promote failed, the route answers 503 SCOPED_PROMOTE_FAILED with the message Code published, but the live agent version could not be updated … Retry the deploy to complete it.; at the version cap it answers 409 SCOPED_PROMOTE_CAP_EXHAUSTED (Agent version limit reached. Prune older versions with lua version delete.). Skill and persona publishes create no agent version. A skill publish sets the skill’s active version, which the agent serves from its next turn; promoting an agent version rewrites every skill’s active version from the promoted agent version, so a skill published without a new agent version is reverted by the next promote. A persona publish switches the served persona at once, and a promote records which persona version was current but does not change it. See Releasing.

Errors

Errors carry { "error": { "code", "message" } }.

Status	Code or message	Meaning	Fix
`400`	`AGENT_VERSION_LIMIT_REACHED`	The agent has 100 versions: `Agent version limit of 100 reached. Delete older versions to create new ones.`	Delete old versions with `lua version delete <n>`.
`403`	`Insufficient permissions`	The key lacks the `agents` scope on this agent.	Grant the scope.
`404`	`AGENT_VERSION_NOT_FOUND`	Unknown version number.	List versions.
`404`	`AGENT_VERSIONING_NOT_ENABLED`	Versioning is off for the agent. Not expected; versioning is on for every agent.	Contact support.
`409`	`NO_STAGED_CHANGES`	Nothing changed since the last version.	Push a change first, or promote an existing version.
`409`	`VERSION_ALREADY_ACTIVE`	Promote of the active version.	Nothing to do.
`409`	`PROMOTE_CONFLICT`	`expectActive` is not the live version. The error carries `expected` and `active`.	Read the version list and decide again.
`409`	`CANNOT_PROMOTE_DELETED_VERSION`	Promote of a soft-deleted version.	Promote a live version.
`409`	`CANNOT_DELETE_ACTIVE_VERSION`	Delete of the active version.	Promote another version first.
`409`	`CANNOT_DELETE_LAST_VERSION`	Delete of the only version.	Create another version first.
`409`	`SKILL_SLUG_CONFLICT`	Two skills in the target snapshot resolve to the same name.	Rename one skill, push, and create a new version.
`500`	`PROMOTE_INCOMPLETE`	The promote failed part-way and could not be rolled back fully.	Read the version: `compensationFailed` and `lastCompensationError` say what remains. Promote again or contact support.
`500`	`SUB_AGENT_NOT_FOUND_DURING_PROMOTE`	The agent record vanished while the promote ran.	Contact support.

Example

Promote version 4, the rollback after a bad version 5.

lua version promote 4

interface PromoteResult {
  promoted: number;
  previousActive: number | null;
}

interface ApiError {
  error: { code: string; message: string };
}

async function promoteVersion(apiKey: string, agentId: string, version: number): Promise<PromoteResult> {
  const response = await fetch(`https://api.heylua.ai/developer/agents/${agentId}/versions/${version}/promote`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
    body: '{}',
  });
  if (!response.ok) {
    const failure = (await response.json()) as ApiError;
    throw new Error(`${failure.error.code}: ${failure.error.message}`);
  }
  return (await response.json()) as PromoteResult;
}

curl -X POST "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/versions/4/promote" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

CLI

REST API

Base URL and authentication

Agent version object

Endpoints

GET /developer/agents/:agentId/versioning/mode

POST /developer/agents/:agentId/versions

GET /developer/agents/:agentId/versions

GET /developer/agents/:agentId/versions/diff

GET /developer/agents/:agentId/versions/:version

POST /developer/agents/:agentId/versions/:version/promote

DELETE /developer/agents/:agentId/versions/:version

PATCH /developer/agents/:agentId/versions/:version/commit-hash

Promote safely

Scoped promotes from single-primitive deploys

Errors

Example

See also

​Base URL and authentication

​Agent version object

​Endpoints

​GET /developer/agents/:agentId/versioning/mode

​POST /developer/agents/:agentId/versions

​GET /developer/agents/:agentId/versions

​GET /developer/agents/:agentId/versions/diff

​GET /developer/agents/:agentId/versions/:version

​POST /developer/agents/:agentId/versions/:version/promote

​DELETE /developer/agents/:agentId/versions/:version

​PATCH /developer/agents/:agentId/versions/:version/commit-hash

​Promote safely

​Scoped promotes from single-primitive deploys

​Errors

​Example

​See also

Base URL and authentication

Agent version object

Endpoints

GET /developer/agents/:agentId/versioning/mode

POST /developer/agents/:agentId/versions

GET /developer/agents/:agentId/versions

GET /developer/agents/:agentId/versions/diff

GET /developer/agents/:agentId/versions/:version

POST /developer/agents/:agentId/versions/:version/promote

DELETE /developer/agents/:agentId/versions/:version

PATCH /developer/agents/:agentId/versions/:version/commit-hash

Promote safely

Scoped promotes from single-primitive deploys

Errors

Example

See also