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

# Operate

> Approve one exact owner-admission request or read owner analytics. approve requires operations:approve; analytics requires analytics:read. Approvals retain review tokens, revisions, expiry and idempotency checks. Owner approval does not authorize requester payment or account access.

Choose `action: "approve"` with the exact approval fields inside `input`, or `action: "analytics"` with the analytics filters inside `input`.

Approval requires `operations:approve`, `Idempotency-Key`, the current revision, and the review token. Analytics requires `analytics:read`. Owner approval does not grant requester credentials, consent, or payment authority.

This endpoint accepts explicit commands. Conversational management threads are not available yet. Existing approval and analytics routes remain compatible.


## OpenAPI

````yaml openapi-publish.json POST /v3/operate
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/operate:
    post:
      tags:
        - Operate
      summary: Operate
      description: >-
        Approve one exact owner-admission request or read owner analytics.
        approve requires operations:approve; analytics requires analytics:read.
        Approvals retain review tokens, revisions, expiry and idempotency
        checks. Owner approval does not authorize requester payment or account
        access.
      operationId: operate
      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: approve
                    input:
                      type: object
                      properties:
                        operationId:
                          type: string
                          minLength: 1
                          maxLength: 200
                        operationRevision:
                          type: integer
                          minimum: 1
                          maximum: 2147483647
                        approvalId:
                          type: string
                          minLength: 1
                          maxLength: 200
                        requestId:
                          type: string
                          minLength: 1
                          maxLength: 200
                        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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                        reviewToken:
                          type: string
                          pattern: ^[a-f0-9]{64}$
                        decision:
                          type: string
                          enum:
                            - allow
                            - deny
                      required:
                        - operationId
                        - operationRevision
                        - approvalId
                        - requestId
                        - expectedUpdatedAt
                        - reviewToken
                        - decision
                      additionalProperties: false
                  required:
                    - action
                    - input
                  additionalProperties: false
                - type: object
                  properties:
                    action:
                      type: string
                      const: analytics
                    input:
                      type: object
                      properties:
                        agentId:
                          type: string
                          minLength: 1
                          maxLength: 200
                        operationId:
                          type: string
                          minLength: 1
                          maxLength: 200
                        from:
                          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)))$
                        to:
                          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)))$
                      required:
                        - agentId
                      additionalProperties: false
                  required:
                    - action
                    - input
                  additionalProperties: false
            example:
              action: analytics
              input:
                agentId: your-agent-id
      responses:
        '200':
          description: >-
            Current owner-scoped result. A mutation retry returns its saved
            response.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      approval:
                        type: object
                        properties:
                          approvalId:
                            type: string
                          operationId:
                            type: string
                          requestId:
                            type: string
                          operationRevision:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          status:
                            type: string
                            enum:
                              - APPROVED
                              - REJECTED
                          executionStarted:
                            type: boolean
                            const: false
                        required:
                          - approvalId
                          - operationId
                          - requestId
                          - operationRevision
                          - status
                          - executionStarted
                        additionalProperties: false
                    required:
                      - approval
                    additionalProperties: false
                  - type: object
                    properties:
                      analytics:
                        type: object
                        properties:
                          agentId:
                            type: string
                          operationId:
                            anyOf:
                              - type: string
                              - type: 'null'
                          from:
                            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))$
                          to:
                            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))$
                          generatedAt:
                            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))$
                          activities:
                            type: array
                            items:
                              type: object
                              properties:
                                eventType:
                                  type: string
                                count:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                              required:
                                - eventType
                                - count
                              additionalProperties: false
                          campaigns:
                            type: array
                            items:
                              type: object
                              properties:
                                status:
                                  type: string
                                count:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                              required:
                                - status
                                - count
                              additionalProperties: false
                          executionAttempts:
                            type: array
                            items:
                              type: object
                              properties:
                                status:
                                  type: string
                                count:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                              required:
                                - status
                                - count
                              additionalProperties: false
                          settledTransactions:
                            type: array
                            items:
                              type: object
                              properties:
                                currency:
                                  type: string
                                count:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                                providerSubtotal:
                                  type: string
                                applicationFees:
                                  type: string
                                networkFees:
                                  type: string
                              required:
                                - currency
                                - count
                                - providerSubtotal
                                - applicationFees
                                - networkFees
                              additionalProperties: false
                          coverage:
                            type: object
                            properties:
                              execution:
                                type: string
                              revenue:
                                type: string
                              discoveryImpressions:
                                type: 'null'
                              latency:
                                type: 'null'
                              advertisingDelivery:
                                type: 'null'
                            required:
                              - execution
                              - revenue
                              - discoveryImpressions
                              - latency
                              - advertisingDelivery
                            additionalProperties: false
                        required:
                          - agentId
                          - operationId
                          - from
                          - to
                          - generatedAt
                          - activities
                          - campaigns
                          - executionAttempts
                          - settledTransactions
                          - coverage
                        additionalProperties: false
                    required:
                      - analytics
                    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.