> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/en/developer/agents-api/assistant-to-agent-migration).

## Base URL

```
https://api.langdock.com/agent/v1/publish
```

<Warning>
  **Dedicated deployments**

  Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.
</Warning>

## Draft vs. Published Version

Edits made via [`/agent/v1/update`](/en/developer/agents-api/agent-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 theme={null}
const axios = require("axios");

async function publishAgent(agentId, description) {
  const response = await axios.post(
    "https://api.langdock.com/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 theme={null}
{
  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](/en/developer/agents-api/agent-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 |

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml POST /agent/v1/publish
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
    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"

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.