---
title: "Add a revision"
method: POST
path: "/agents/{agent_id}/revisions"
tags: ["Agents"]
---

# Add a revision

`POST /agents/{agent_id}/revisions`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/agents/{agent_id}/revisions`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/agents/:agent_id/revisions/post.ts> (a function with typed inputs; its response is checked against the schema)

Appends a revision to an agent, instructions or code, and makes it the one runs use. Revisions are never changed or removed.

## Path parameters

- `agent_id` string, uuid, required: The agent's id.

## Request body

- AgentRevisionCreateRequest: Request body for adding a revision. The new revision becomes the agent's current one.
  - `code` string: The script, for a code revision.
  - `instructions` string: The task, for an instructions revision.
  - `kind` 'code' | 'instructions', required: code needs code; instructions needs instructions.
  - `message` string: A note on the revision.
  - `on_failure` 'fail' | 'ask' | 'repair': For a code revision, what a run does when a step fails. fail fails the run. ask pauses the run for a person (reason step_check_failed), who retries the step or completes the run with its output. repair hands the run to the agent, which finishes the task and proposes a fixed revision for a person to promote. Defaults to the current revision's, or fail.

## Response `201`

Created

- AgentRevision: One revision of an agent: instructions or code. Revisions are append-only.
  - `agent_id` string, uuid, required: The agent the revision belongs to.
  - `author_user_id` string, uuid, nullable, required: The user who added the revision. Null once they have deleted their account.
  - `base_revision_id` string, uuid: On a proposed fix, the revision the repaired run ran.
  - `code` string: The script, on a code revision.
  - `created_at` string, date-time, required: When the revision was added.
  - `id` string, uuid, required: The revision's id.
  - `instructions` string: The task, on an instructions revision.
  - `kind` 'code' | 'instructions', required: code: the revision is a script. instructions: the revision is a task the agent works through a model.
  - `message` string: The author's note on the revision.
  - `on_failure` 'fail' | 'ask' | 'repair': On a code revision, what a run does when a step fails: fail the run, ask (pause for a person, who retries the step or completes the run), or repair (the agent takes over and proposes a fix).
  - `promoted_at` string, date-time: On a proposed fix, when it was promoted to current.
  - `proposal_state` 'waiting' | 'superseded' | 'promoted': Set when the revision is a fix a repair proposed, which is not current until promoted: waiting to be promoted, superseded (the agent has moved on from the revision it fixes, so it can't be promoted), or promoted.
  - `revision` integer, required: The revision's number within the agent, from 1.
  - `source_run_id` string, uuid: The run the revision came from: on a proposed fix, the run whose repair wrote it; on an agent saved from a run, that run.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-11-02** `62aa324803a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/agents/:agent_id/revisions/post.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)