CumulusDocs
Open Studio
On this page

Promote or roll back a version

Make an existing version live or roll back to an earlier one. Send the live version you last read; a named open draft is rebased in the same transaction.

Operation ID: publications.promote.

Request

POST /api/v1/agents/{agent_id}/head

  • TypeScript SDK: client.publications.promote (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "publications.promote" (path arguments use input.path). Legacy alias: publications_promote. Connect to your authenticated /mcp endpoint with an API key for the same environment.
  • Minimum API key role: member.
  • Idempotency: No header required; the resource or revision identifies the change.

Read resource IDs from earlier responses and use a key for the same environment.

Request example

Choose the target from publications.list and copy the current head from agents.get. Supply the open draft ID if it should be rebased to that head. Promotion changes the selected publication but does not turn a test-only publication into an ordinary one.

Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Example values are synthetic.

cURL

curl
curl --fail-with-body -sS -X POST "${CUMULUS_BASE_URL%/}/api/v1/agents/${AGENT_ID}/head" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "version": 1,
  "expected_head_version": 0,
  "draft_id": "11111111-1111-4111-8111-111111111111"
}'

TypeScript

typescript
import { Cumulus } from "@cumulus/sdk";

const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });

const response = await client.publications.promote({
  "path": {
    "agent_id": "<agent_id>"
  },
  "body": {
    "version": 1,
    "expected_head_version": 0,
    "draft_id": "11111111-1111-4111-8111-111111111111"
  }
});

Integration notes

Send the target version and expected_head_version. Read the latter from agents_get at head.version; use null when the agent has no live publication.

Input schema

Path, query and header parameters

agent_id

path parameter · Required.

Type: string. minLength: 1. maxLength: 256. pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$.

JSON request body

FieldType or valuesRequiredDescription and limits
versionintegerRequiredAt least 0. At most 2147483647.
expected_head_versioninteger or nullRequiredLive publication version you last read; null when there is no live version. At least 0. At most 2147483647.
draft_idstring (uuid) or nullOptionalIdentifier of the editable draft. Read it from the agent or draft response. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [
    {
      "name": "agent_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PublicationsPromoteRequest"
        }
      }
    }
  }
}

Responses

HTTP 200

Move head to an existing version (manual promote or rollback), rebasing the named open draft in the same transaction

application/json

FieldType or valuesRequiredDescription and limits
agentobjectRequired—
agent.tenant_idstring (uuid)Requiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
agent.kind"agent"Required—
agent.idstringRequiredminLength: 1. maxLength: 256. pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$.
from_versioninteger or nullRequiredAt least 0. At most 2147483647.
to_versionintegerRequiredAt least 0. At most 2147483647.
digeststringRequiredpattern: ^sha256:[a-f0-9]{64}$.
movedbooleanRequired—

Error responses

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "200": {
    "description": "Move head to an existing version (manual promote or rollback), rebasing the named open draft in the same transaction",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/PublicationsPromoteResponse200"
        }
      }
    }
  },
  "4XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "5XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Referenced schemas

Expand the complete OpenAPI definitions for integrations that generate their own clients.

Complete OpenAPI schema
OpenAPI JSON
{
  "components": {
    "schemas": {
      "PublicationsPromoteRequest": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "expected_head_version": {
            "nullable": true,
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "draft_id": {
            "nullable": true,
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
          }
        },
        "required": [
          "version",
          "expected_head_version"
        ],
        "additionalProperties": false
      },
      "PublicationsPromoteResponse200": {
        "type": "object",
        "properties": {
          "agent": {
            "type": "object",
            "properties": {
              "tenant_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "agent"
                ]
              },
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
              }
            },
            "required": [
              "tenant_id",
              "kind",
              "id"
            ],
            "additionalProperties": false
          },
          "from_version": {
            "nullable": true,
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "to_version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647
          },
          "digest": {
            "type": "string",
            "pattern": "^sha256:[a-f0-9]{64}$"
          },
          "moved": {
            "type": "boolean"
          }
        },
        "required": [
          "agent",
          "from_version",
          "to_version",
          "digest",
          "moved"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthenticated",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "invalid_request",
                  "idempotency_conflict",
                  "policy_denied",
                  "capability_unavailable",
                  "provider_unavailable",
                  "knowledge_unavailable",
                  "publication_invalid",
                  "run_not_active",
                  "rate_limited",
                  "outcome_unknown",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "none",
                  "unknown"
                ]
              },
              "details": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "code",
              "message",
              "retryable",
              "outcome"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}

Errors and recovery

See API error handling and Troubleshooting.

Content version 5e20e9ddCustomer SDKMarkdown source
Promote or roll back a version · Cumulus developer docs