> ## 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

<Info>
  **⚠️ Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

<Info>
  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/assistants-api/assistant-to-agent-migration).
</Info>

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.

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

## Request 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
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
                  maxLength: 100
                  description: Optional change description shown in version history
      responses:
        '200':
          description: Agent published successfully
          content:
            application/json:
              schema:
                type: object
                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"

````