> ## 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. # Advertise > Create, update, submit, pause, or get a campaign. get requires advertising:read; all mutations require advertising:write and Idempotency-Key. Existing action bodies remain supported. Submission requests review and does not activate delivery or authorize spending. Choose `action`: `create`, `update`, `submit`, `pause`, or `get`. Existing campaign request shapes are preserved. For `get`, supply `campaignId`; it requires `advertising:read`. Mutations require `advertising:write` and `Idempotency-Key`. Updates, submission, and pause require `expectedRevision`. Submission requests review; it does not activate delivery or authorize spending. This endpoint accepts explicit commands. Conversational management threads are not available yet. The existing campaign read route remains compatible. ## OpenAPI ````yaml openapi-publish.json POST /v3/advertise 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/advertise: post: tags: - Advertise summary: Advertise description: >- Create, update, submit, pause, or get a campaign. get requires advertising:read; all mutations require advertising:write and Idempotency-Key. Existing action bodies remain supported. Submission requests review and does not activate delivery or authorize spending. operationId: advertise 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: anyOf: - oneOf: - type: object properties: action: type: string const: create agentId: type: string minLength: 1 maxLength: 200 operationId: type: string minLength: 1 maxLength: 200 operationRevision: type: integer minimum: 1 maximum: 2147483647 name: type: string minLength: 1 maxLength: 160 billingEvent: type: string enum: - IMPRESSIONS - CONVERSATIONS - CONVERSIONS currency: default: USD type: string const: USD budgetCents: type: integer minimum: 1 maximum: 1000000000 startsAt: 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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ endsAt: 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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ targeting: default: keywords: [] countries: [] type: object properties: keywords: default: [] maxItems: 20 type: array items: type: string minLength: 1 maxLength: 120 countries: default: [] maxItems: 50 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: false required: - action - agentId - operationId - operationRevision - name - billingEvent - budgetCents additionalProperties: false - type: object properties: action: type: string const: update campaignId: type: string minLength: 1 maxLength: 200 expectedRevision: type: integer minimum: 1 maximum: 2147483647 patch: type: object properties: name: type: string minLength: 1 maxLength: 160 billingEvent: type: string enum: - IMPRESSIONS - CONVERSATIONS - CONVERSIONS currency: type: string const: USD budgetCents: type: integer minimum: 1 maximum: 1000000000 startsAt: 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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ endsAt: 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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ targeting: type: object properties: keywords: default: [] maxItems: 20 type: array items: type: string minLength: 1 maxLength: 120 countries: default: [] maxItems: 50 type: array items: type: string pattern: ^[A-Z]{2}$ additionalProperties: false additionalProperties: false required: - action - campaignId - expectedRevision - patch additionalProperties: false - type: object properties: action: type: string enum: - submit - pause campaignId: type: string minLength: 1 maxLength: 200 expectedRevision: type: integer minimum: 1 maximum: 2147483647 required: - action - campaignId - expectedRevision additionalProperties: false - type: object properties: action: type: string const: get campaignId: type: string minLength: 1 maxLength: 200 required: - action - campaignId additionalProperties: false example: action: create agentId: agent-from-publish-agent operationId: operation-from-get-operation operationRevision: 1 name: Weather conversations billingEvent: CONVERSATIONS currency: USD budgetCents: 5000 targeting: keywords: - local forecast countries: - US responses: '200': description: >- Current owner-scoped result. A mutation retry returns its saved response. content: application/json: schema: type: object properties: campaign: type: object properties: campaignId: type: string agentId: type: string operationId: type: string operationRevision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 status: type: string enum: - DRAFT - PENDING_REVIEW - PAUSED name: type: string billingEvent: type: string enum: - IMPRESSIONS - CONVERSATIONS - CONVERSIONS currency: type: string const: USD budgetCents: type: integer minimum: -9007199254740991 maximum: 9007199254740991 targeting: {} startsAt: 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' endsAt: 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' submittedAt: 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' 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))$ delivery: type: object properties: status: type: string const: NOT_ACTIVE impressions: type: 'null' conversations: type: 'null' conversions: type: 'null' spendCents: type: 'null' required: - status - impressions - conversations - conversions - spendCents additionalProperties: false required: - campaignId - agentId - operationId - operationRevision - revision - status - name - billingEvent - currency - budgetCents - targeting - startsAt - endsAt - submittedAt - createdAt - updatedAt - delivery additionalProperties: false required: - campaign 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.