Agent Publish API

Publish a draft agent as a new version

Publishes the current draft of an agent as a new version. This mirrors the Update button in the agent editor: a published version is a frozen snapshot of the draft that becomes the active version users see.

Before You Start

Legacy Assistants API: This is the new Agents API with native Vercel AI SDK compatibility. If you're using the legacy Assistants API, see the migration guide.

Base URL

https://api.ajan.io/agent/v1/publish

Draft vs. Published Version

Edits made via /agent/v1/update only affect the draft. Until you call publish, those changes are not visible to workspace members.

Use Cases

Promote draft edits made via the Update API into a new active version
Roll out changes programmatically as part of a CI/CD pipeline
Release a new revision with an optional change description shown in version history

Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	UUID of the agent to publish
`description`	string	No	Short change description shown in version history (max 100 characters)

Example

javascript

const axios = require("axios");

async function publishAgent(agentId, description) {
  const response = await axios.post(
    "https://api.ajan.io/agent/v1/publish",
    {
      agentId: agentId,
      description: description,
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
      },
    },
  );

  console.log("Published version:", response.data.version);
}

publishAgent(
  "550e8400-e29b-41d4-a716-446655440000",
  "Tightened the system prompt",
);

Response Format

Success Response (200 OK)

typescript

{
  status: "success";
  message: "Agent published successfully";
  version: {
    id: string;          // UUID of the new version
    version: number;     // Monotonically increasing version number
    createdAt: string;   // ISO 8601 timestamp
  };
}

Validation Rules

Agent access — The API key must have owner or editor access to the agent (same as Update).
Workspace match — The agent must belong to the same workspace as the API key.
Agents only — Projects (type=PROJECT) are not supported and will return 403.
Has draft changes — The draft must differ from the latest published version. Publishing with no pending changes returns 409 Conflict, mirroring the disabled "Update" button in the UI.

Error Handling

Status Code	Description
400	Invalid request body (missing or malformed `agentId` / `description` too long)
401	Invalid or missing API key
403	API key does not have edit access, the agent is in a different workspace, or the resource is a project
409	No draft changes to publish
429	Rate limit exceeded

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /agent/v1/publish:
    post:
      tags:
        - Agent Build
      summary: Publishes a draft agent as a new version
      description: >-
        Publishes the current draft of an agent as a new version. Mirrors the
        "Update" button in the agent editor — only agents (not projects) are
        supported, and the draft must differ from the latest published version.
      operationId: publishAgentV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agentId
              properties:
                agentId:
                  type: string
                  format: uuid
                  description: UUID of the agent to publish
                description:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: Optional change description shown in version history
      responses:
        '200':
          description: Agent published successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - version
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  version:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      version:
                        type: integer
                      createdAt:
                        type: string
                        format: date-time
        '403':
          description: >-
            API key lacks edit access, agent is in a different workspace, or the
            resource is a project
        '409':
          description: No draft changes to publish
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"