> ## 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, or pause an advertising campaign. Use `advertising:write` and an `Idempotency-Key`. All campaign changes use this endpoint: * `create`: save a durable draft with an owned `agentId`, `operationId`, pinned `operationRevision`, name, one billing event, USD budget in cents, targeting, and optional schedule. * `update`: supply `campaignId`, `expectedRevision`, and a `patch`. Only draft or paused campaigns can be edited. * `submit`: supply `campaignId` and `expectedRevision`. The operation must be active, public, and still at its pinned revision. This records `PENDING_REVIEW`. * `pause`: supply `campaignId` and `expectedRevision`. This records `PAUSED`. Saving or submitting a campaign does not activate paid placements, authorize a charge, reserve funds, or guarantee eligibility. Paid delivery and settlement require a separately verified delivery and funding integration. Delivery remains `NOT_ACTIVE`; unmeasured results and spend remain `null`. Get the persisted result through [Get campaign](/docs/reference/studio-get-campaign). ## 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 a durable campaign draft, update its terms, submit it for review, or pause it through one command endpoint. Updates, submission, and pause require expectedRevision. Submit requires an active public operation at the pinned revision and returns PENDING_REVIEW. No command activates paid delivery, charges a budget, or reports invented results. Delivery metrics remain null until an actual delivery system records them. 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: 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 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.