---
title: "Restore a revision"
method: POST
path: "/agent/{id}/branches/{branchId}/revisions/{revisionId}/restore"
tags: ["Agent Versioning - Revisions"]
---

# Restore a revision

`POST /agent/{id}/branches/{branchId}/revisions/{revisionId}/restore`

## Request

- Base URL: `https://api.smallest.ai/atoms/v1`
- URL: `https://api.smallest.ai/atoms/v1/agent/{id}/branches/{branchId}/revisions/{revisionId}/restore`
- Auth: HTTP bearer

Republish an older revision as a new revision at the head of this branch. Restore does not overwrite history; the older revision keeps its ID, and a new revision is committed on top.

The response mirrors `POST /agent/{id}/branches/{branchId}/draft/publish`: `200 committed` if the scan is synchronous, `202 scanning` if deferred. Only one publish or restore can be in flight per branch at a time.

## Path parameters

- `id` string, required
- `branchId` string, required
- `revisionId` string, required

## Response `200`

Restored synchronously.

- object
  - `status` boolean
  - `data` PublishResult: Result of publish or restore. - `state: "committed"` (HTTP `200`) is returned when the commit is synchronous. This happens for restore (the source revision has already been scanned) and for publishes whose content does not need a fresh scan. The response includes the new revision object under `revision`. - `state: "scanning"` (HTTP `202`) is returned when a security scan is deferred. In this case the response body carries only `state`. `revision` is absent, and clients must list the branch's revisions newest-first (`GET /agent/{id}/branches/{branchId}/revisions?limit=1`) to obtain the new revision ID. Then poll `GET /agent/{id}/branches/{branchId}/revisions/{revisionId}` until `revision.status` flips from any transient value to `"published"`. On the revision doc the lifecycle field is `status` (not `state`), and the security-scan sub-lifecycle is on the nested `securityCheck.status`.
    - `state` 'scanning' | 'committed'
    - `revision` Revision: An `AgentVersion` document. Represents either a committed revision (`status: published`, with `branch` + `revisionNumber`) or an in-progress draft revision (`status: draft`, with `draftId` + `draftRevision`). Fields that do not apply to a given row are `null`.
      - `_id` string
      - `agent` string
      - `status` 'published' | 'draft' | 'archived'
      - `branch` string, nullable: Owning branch (v2). `null` on legacy rows until backfilled.
      - `revisionNumber` integer, nullable: Monotonic per-branch commit number. Only set on committed rows.
      - `versionNumber` integer, nullable: Legacy v1 published-version number. `null` for branch revisions and drafts.
      - `label` string, nullable
      - `description` string, nullable
      - `isPinned` boolean
      - `publishedBy` string, nullable
      - `publishedAt` string, date-time, nullable
      - `publishedByName` string, nullable: Display name of the publisher. `null` when unresolvable.
      - `restoredFromLabel` string, nullable: On a commit produced by restore, the label of the revision it copied.
      - `draftId` string, nullable
      - `draftName` string, nullable
      - `draftRevision` integer, nullable
      - `sourceVersionId` string, nullable
      - `blocks` VersionBlocks: ObjectId references to the `AgentConfigBlock` docs that make up a revision, one per config section.
        - `workflow_prompt` string
        - `workflow_tools` string
        - `workflow_graph` string
        - `llm` string
        - `voice` string
        - `language` string
        - `call_handling` string
        - `detection` string
        - `analytics` string
        - `timeouts` string
        - `audio` string
        - `privacy` string
        - `widget` string
        - `playbooks` string: Only present on revisions created after multi-agent playbooks shipped.
      - `workflowType` string: The `WorkflowType` enum for this revision.
      - `parentVersion` string, nullable
      - `isActive` boolean
      - `activatedBy` string, nullable
      - `activatedAt` string, date-time, nullable
      - `securityCheck` object, nullable: Populated after publish. `null` on pre-feature versions.
        - `status` string: The `SecurityCheckStatus` enum.
        - `reason` string, nullable
        - `triggeredAt` string, date-time, nullable
        - `completedAt` string, date-time, nullable
      - `pendingPublish` object, nullable: Set while a publish is armed against this draft revision.
        - `state` 'active' | 'cancelled'
        - `startedBy` string
        - `startedAt` string, date-time
      - `restoredFromRevisionId` string, nullable: On a commit produced by restore, the revision it copied.
      - `sourceDraftId` string, nullable
      - `promptScore` PromptScore, nullable: Result of the prompt-scoring pass, if any.
        - `overall_score` number
        - `overall_grade` string
        - `band` string
        - `estimated_ttft_overhead_ms` number
        - `scoredAt` string, date-time
        - `dimensions` object[]
          - `tier` integer
          - `level` string
          - `evidence_span` string
          - `title` string
          - `description` string
      - `promptScoreStale` boolean
      - `createdBy` string
      - `createdAt` string, date-time
      - `updatedAt` string, date-time

## Other responses

- `202`: Security scan queued.
- `400`: Invalid input
- `401`: Unauthorized access
- `403`: Forbidden. Source revision has not passed its security scan, or the caller lacks write access.
- `404`: Resource not found. The referenced ID does not exist or does not belong to the caller's organization.
- `409`: Conflict. The request cannot be completed because of the current state of the resource (name already exists, another publish or restore is in progress, the source draft failed its security scan, or a similar in-flight collision).
- `423`: Locked. A configuration freeze is active on this agent, or the resource is temporarily locked for another write. Retry after the freeze window ends.
- `500`: Internal server error

## Changes

- **2026-07-23** `a9c928635312`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smallest-inc/apis/agent-management-api/changes/agent/:id/branches/:branchId/revisions/:revisionId/restore/post.md)

---

[API](https://skmtc.dev/smallest-inc/apis/agent-management-api.md) - [All operations](https://skmtc.dev/smallest-inc/apis/agent-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smallest-inc/apis/agent-management-api/revisions/fed4f750ea02?raw)