---
title: "Publish draft"
method: POST
path: "/agent/{id}/branches/{branchId}/draft/publish"
tags: ["Agent Versioning - Branches"]
---

# Publish draft

`POST /agent/{id}/branches/{branchId}/draft/publish`

Publish the open draft on this branch as a new revision.

The response is `200` with `state: "committed"` when the security scan finishes synchronously, and `202` with `state: "scanning"` when the scan is deferred. A `scanning` revision is visible in history but cannot be restored or made live until it becomes `committed`. If the scan fails, the revision is left in `scanning` state and this endpoint returns `409` on subsequent publishes until the scan is retried.

Publishing on the live branch pushes to production immediately.

## Path parameters

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

## Request body

- PublishBranchDraftRequest
  - `label` string, nullable — Optional label saved on the committed revision.

## Response `200`

Draft committed 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. Poll `GET /agent/{id}/branches/{branchId}/revisions` until the returned revision transitions to `committed`.
- `400` — Invalid input
- `401` — Unauthorized access
- `403` — Forbidden. Branch is archived or the caller lacks write access.
- `404` — No open draft on this branch, or the branch does not exist.
- `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

---

[API](https://skmtc.net/smallest-inc/apis/agent-management-api.md) · [All operations](https://skmtc.net/smallest-inc/apis/agent-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/smallest-inc/agent-management-api/revisions/c2d0eb64b01a/schema)