> ## Documentation Index > Fetch the complete documentation index at: https://darwin.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Publish > Dispatch one explicit publishing command. Each action requires its own agents:read/write or operations:read/write scope. Mutations retain idempotency, ownership, and revision checks. Read actions do not mutate records. This is a typed command endpoint; it does not yet start a conversational management thread. Choose `action`: `publish_agent`, `publish_operation`, `update_agent`, `update_operation`, `get_agent`, or `get_operation`. Supply the existing operation fields inside `input`; updates and reads also select the top-level `agentId` or `operationId`. Mutations require `Idempotency-Key`. Updates require `input.expectedRevision`. Each action requires its own read or write scope, and ownership checks still apply. This endpoint accepts explicit commands. Conversational management threads are not available yet. The older resource routes remain compatible. ## OpenAPI ````yaml openapi-publish.json POST /v3/publish openapi: 3.1.0 info: title: Publish version: 3.0.0 description: >- Owner-authorized agent and operation publishing, operating decisions and analytics, and durable campaign management. Publishing records does not bypass independent execution verification. Campaign submission requests review; it does not activate delivery or authorize spending. servers: - url: https://api.darwin.so/api security: [] paths: /v3/publish: post: tags: - Publish summary: Publish description: >- Dispatch one explicit publishing command. Each action requires its own agents:read/write or operations:read/write scope. Mutations retain idempotency, ownership, and revision checks. Read actions do not mutate records. This is a typed command endpoint; it does not yet start a conversational management thread. operationId: publish parameters: - name: Idempotency-Key in: header required: true description: >- Stable key for this exact mutation. Reusing it with different input returns 409. schema: type: string minLength: 1 maxLength: 200 requestBody: required: true content: application/json: schema: oneOf: - type: object properties: action: type: string const: publish_agent input: type: object properties: handle: type: string pattern: ^[a-z0-9](?:[a-z0-9-]{0,39}[a-z0-9])?$ name: type: string minLength: 1 maxLength: 160 description: default: '' type: string maxLength: 5000 avatarUrl: anyOf: - type: string maxLength: 2000 format: uri - type: 'null' visibility: default: PRIVATE type: string enum: - PRIVATE - RESTRICTED - PUBLIC required: - handle - name additionalProperties: false required: - action - input additionalProperties: false - type: object properties: action: type: string const: publish_operation input: type: object properties: agentId: type: string minLength: 1 maxLength: 200 handle: type: string pattern: ^[a-z0-9](?:[a-z0-9-]{0,39}[a-z0-9])?$ name: type: string minLength: 1 maxLength: 160 description: default: '' type: string maxLength: 20000 visibility: default: PRIVATE type: string enum: - PRIVATE - PUBLIC status: default: DRAFT type: string enum: - DRAFT - ACTIVE - PAUSED - ARCHIVED inputSchema: default: {} type: object propertyNames: type: string additionalProperties: {} outputSchema: default: {} type: object propertyNames: type: string additionalProperties: {} fulfillment: default: mechanism: MANUAL type: object properties: mechanism: type: string enum: - MANUAL - API - MCP - A2A - WEBMCP endpoint: type: string maxLength: 2000 format: uri required: - mechanism additionalProperties: false pricing: default: currency: USD amountCents: 0 type: object properties: currency: default: USD type: string const: USD amountCents: type: integer minimum: 0 maximum: 1000000000 required: - amountCents additionalProperties: false ownerApproval: default: MANUAL type: string enum: - MANUAL - AUTO required: - agentId - handle - name additionalProperties: false required: - action - input additionalProperties: false - type: object properties: action: type: string const: update_agent agentId: type: string minLength: 1 maxLength: 200 input: type: object properties: handle: type: string pattern: ^[a-z0-9](?:[a-z0-9-]{0,39}[a-z0-9])?$ name: type: string minLength: 1 maxLength: 160 description: type: string maxLength: 5000 avatarUrl: anyOf: - type: string maxLength: 2000 format: uri - type: 'null' visibility: type: string enum: - PRIVATE - RESTRICTED - PUBLIC expectedRevision: type: integer minimum: 1 maximum: 2147483647 required: - expectedRevision additionalProperties: false required: - action - agentId - input additionalProperties: false - type: object properties: action: type: string const: update_operation operationId: type: string minLength: 1 maxLength: 200 input: type: object properties: handle: type: string pattern: ^[a-z0-9](?:[a-z0-9-]{0,39}[a-z0-9])?$ name: type: string minLength: 1 maxLength: 160 description: type: string maxLength: 20000 visibility: type: string enum: - PRIVATE - PUBLIC status: type: string enum: - DRAFT - ACTIVE - PAUSED - ARCHIVED inputSchema: type: object propertyNames: type: string additionalProperties: {} outputSchema: type: object propertyNames: type: string additionalProperties: {} fulfillment: type: object properties: mechanism: type: string enum: - MANUAL - API - MCP - A2A - WEBMCP endpoint: type: string maxLength: 2000 format: uri required: - mechanism additionalProperties: false pricing: type: object properties: currency: default: USD type: string const: USD amountCents: type: integer minimum: 0 maximum: 1000000000 required: - amountCents additionalProperties: false ownerApproval: type: string enum: - MANUAL - AUTO expectedRevision: type: integer minimum: 1 maximum: 2147483647 required: - expectedRevision additionalProperties: false required: - action - operationId - input additionalProperties: false - type: object properties: action: type: string const: get_agent agentId: type: string minLength: 1 maxLength: 200 required: - action - agentId additionalProperties: false - type: object properties: action: type: string const: get_operation operationId: type: string minLength: 1 maxLength: 200 required: - action - operationId additionalProperties: false example: action: publish_agent input: name: Acme Weather handle: acme-weather responses: '200': description: >- Current owner-scoped result. A mutation retry returns its saved response. content: application/json: schema: anyOf: - type: object properties: agent: type: object properties: agentId: type: string handle: anyOf: - type: string - type: 'null' name: type: string description: anyOf: - type: string - type: 'null' avatarUrl: anyOf: - type: string - type: 'null' visibility: type: string revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - agentId - handle - name - description - avatarUrl - visibility - revision - createdAt - updatedAt additionalProperties: false required: - agent additionalProperties: false - type: object properties: operation: type: object properties: operationId: type: string agentId: type: string handle: anyOf: - type: string - type: 'null' name: type: string description: type: string revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 visibility: type: string status: type: string readiness: type: string inputSchema: {} outputSchema: {} fulfillment: {} pricing: {} ownerApproval: type: string enum: - MANUAL - AUTO createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - operationId - agentId - handle - name - description - revision - visibility - status - readiness - inputSchema - outputSchema - fulfillment - pricing - ownerApproval - createdAt - updatedAt additionalProperties: false pendingApprovals: type: array items: type: object properties: approvalId: type: string requestId: type: string operationRevision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 expectedUpdatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ reviewToken: type: string expiresAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: 'null' required: - approvalId - requestId - operationRevision - expectedUpdatedAt - reviewToken - expiresAt additionalProperties: false required: - operation additionalProperties: false '400': description: Invalid request. content: application/json: schema: type: object properties: message: type: - string - array code: type: string '401': description: Missing or invalid credentials. content: application/json: schema: type: object properties: message: type: - string - array code: type: string '403': description: Insufficient scope or user authority. content: application/json: schema: type: object properties: message: type: - string - array code: type: string '404': description: Resource is absent or not owned by this caller. content: application/json: schema: type: object properties: message: type: - string - array code: type: string '409': description: Revision, handle, idempotency, or decision conflict. content: application/json: schema: type: object properties: message: type: - string - array code: type: string '503': description: Canonical product storage or migration is unavailable. content: application/json: schema: type: object properties: message: type: - string - array code: type: string security: - apiKey: [] - apiKeyBearer: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key apiKeyBearer: type: http scheme: bearer description: A Darwin API key supplied as an Authorization Bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.