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

# Assist

> Plan, execute, and update agent work through one typed request endpoint.

Use this endpoint for every Assist turn. Create once, then pass the returned `assistId` for follow-ups. Read state with [Get assist request](/docs/reference/get-assist). The [Plan](/docs/navigator/assist-plan), [Execute](/docs/navigator/assist-execution), and [Update](/docs/navigator/assist-update) guides explain the full lifecycle.

Authenticate each request with a Darwin API key in `x-api-key` or `Authorization: Bearer`.

| `type` | Required fields beyond `type` | Effect |
| - | - | - |
| `create` | text `message`; optional `context` | Create an owner-scoped draft and return `assistId`. |
| `revise` | `assistId`, `expectedRevisionId`, text `message` | Refine an unstarted draft; invalidates its quote. |
| `update` | `assistId`, `expectedRevisionId`, text `message` | Refine a draft or replan a terminal, settled run under the same ID. Archives previous run/quote and requires new funding and approval. |
| `claim` | `assistId`; owner credential and `X-Assist-Token` | Save an unclaimed guest draft to its authenticated owner. |
| `quote` | `assistId`, `revisionId`, `totalBudgetMinor`, `currency: "USD"` | Price the exact plan; does not reserve funds. |
| `authorize_budget` | `assistId`, `revisionId`, `quoteId`, typed budget `approval` | Reserve the quoted ceiling; starts no work. Requires `Idempotency-Key`. |
| `execute` | `assistId`, `revisionId`, `quoteId`, `fundingAuthorizationId`, typed execution `approval` | Start one approved run. Requires `Idempotency-Key`. |
| `message` | `assistId`, `runId`, `stepId`, typed Act `message` | Continue that run's child thread through Act. Use an idempotency key for retries. |
| `refresh` | `assistId` | Reconcile accepted evidence and open eligible dependent steps. This is a mutation. |
| `accept_step` | `assistId`, `runId`, `stepId`, `messageId`, typed acceptance `approval` | Accept a delivered free conversational result when no action/payment review is needed. |
| `release_budget` | `assistId`, `fundingAuthorizationId` | Release an unused authorization before starting. |
| `stop` | `assistId` | Prevent new dispatch and settle at verified child checkpoints. |

Text messages have `{ "type": "text", "text": "..." }`. Copy IDs from your responses. Never manufacture user consent: the exact typed approvals in [Execute](/docs/navigator/assist-execution) record separate decisions by the authorized person. Guest tokens cannot authorize execution or payment. Application-only keys cannot act as a person.

All commands return the same Assist state shape. An accepted command is not proof of completed provider work. Budget and execution commands keep their original live-scope, ownership, idempotency, quote-expiry, wallet, and settlement checks.


## OpenAPI

````yaml openapi-v3.json POST /v3/assist
openapi: 3.1.0
info:
  title: Navigator
  version: 3.0.0
servers:
  - url: https://api.darwin.so/api
security: []
paths:
  /v3/assist:
    post:
      summary: Assist
      description: >-
        Plan, execute, and update agent work through one typed request endpoint
        using an authenticated API key. Create or refine a plan, quote,
        authorize the exact budget, execute, message a child, refresh, accept a
        result, stop, or update a settled plan using the same assistId. Planning
        never starts work or spends. Budget authorization and execution require
        their own exact typed approvals and Idempotency-Key. Structural updates
        require a settled terminal run; previous runs remain in history.
        Claiming an existing guest draft additionally requires its
        X-Assist-Token.
      operationId: create_or_revise_assist
      parameters:
        - name: X-Assist-Token
          in: header
          required: false
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistV3Request'
      responses:
        '200':
          description: >-
            Current Assist conversation, revisions, quote, funding, run and
            previous runs. Only an explicitly authorized execute request starts
            work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistV3Response'
        '401':
          description: Missing or invalid API key
        '403':
          description: Credential access denied
        '409':
          description: Stale revision or idempotency conflict
        '429':
          description: Account request limit exceeded; follow Retry-After
        '503':
          description: Service unavailable
      security:
        - apiKey: []
        - apiKeyBearer: []
components:
  schemas:
    AssistV3Request:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              const: create
            message:
              type: object
              properties:
                type:
                  type: string
                  const: text
                text:
                  type: string
                  minLength: 1
                  maxLength: 20000
              required:
                - type
                - text
              additionalProperties: false
            context:
              default: []
              maxItems: 10
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 4000
          required:
            - type
            - message
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: revise
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
            expectedRevisionId:
              type: string
              pattern: ^arev_[a-f0-9-]{36}$
            message:
              type: object
              properties:
                type:
                  type: string
                  const: text
                text:
                  type: string
                  minLength: 1
                  maxLength: 20000
              required:
                - type
                - text
              additionalProperties: false
          required:
            - type
            - assistId
            - expectedRevisionId
            - message
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: update
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
            expectedRevisionId:
              type: string
              pattern: ^arev_[a-f0-9-]{36}$
            message:
              type: object
              properties:
                type:
                  type: string
                  const: text
                text:
                  type: string
                  minLength: 1
                  maxLength: 20000
              required:
                - type
                - text
              additionalProperties: false
          required:
            - type
            - assistId
            - expectedRevisionId
            - message
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: claim
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
          required:
            - type
            - assistId
          additionalProperties: false
        - type: object
          properties:
            revisionId:
              type: string
              pattern: ^arev_[a-f0-9-]{36}$
            totalBudgetMinor:
              type: integer
              exclusiveMinimum: 0
              maximum: 1000000000
            currency:
              type: string
              const: USD
            type:
              type: string
              const: quote
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
          required:
            - revisionId
            - totalBudgetMinor
            - currency
            - type
            - assistId
          additionalProperties: false
        - type: object
          properties:
            revisionId:
              type: string
              pattern: ^arev_[a-f0-9-]{36}$
            quoteId:
              type: string
              pattern: ^aqt_[a-f0-9-]{36}$
            approval:
              type: object
              properties:
                type:
                  type: string
                  const: typed
                text:
                  type: string
                  const: I authorize this Assist budget
              required:
                - type
                - text
              additionalProperties: false
            type:
              type: string
              const: authorize_budget
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
          required:
            - revisionId
            - quoteId
            - approval
            - type
            - assistId
          additionalProperties: false
        - type: object
          properties:
            revisionId:
              type: string
              pattern: ^arev_[a-f0-9-]{36}$
            quoteId:
              type: string
              pattern: ^aqt_[a-f0-9-]{36}$
            fundingAuthorizationId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
            approval:
              type: object
              properties:
                type:
                  type: string
                  const: typed
                text:
                  type: string
                  const: I approve this Assist plan and quote
              required:
                - type
                - text
              additionalProperties: false
            type:
              type: string
              const: execute
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
          required:
            - revisionId
            - quoteId
            - fundingAuthorizationId
            - approval
            - type
            - assistId
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: refresh
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
          required:
            - type
            - assistId
          additionalProperties: false
        - type: object
          properties:
            runId:
              type: string
              pattern: ^arun_[a-f0-9-]{36}$
            messageId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
            approval:
              type: object
              properties:
                type:
                  type: string
                  const: typed
                text:
                  type: string
                  const: I accept this Assist step result
              required:
                - type
                - text
              additionalProperties: false
            type:
              type: string
              const: accept_step
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
            stepId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
          required:
            - runId
            - messageId
            - approval
            - type
            - assistId
            - stepId
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: release_budget
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
            fundingAuthorizationId:
              type: string
              pattern: ^afund_[a-f0-9-]{36}$
          required:
            - type
            - assistId
            - fundingAuthorizationId
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: stop
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
          required:
            - type
            - assistId
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: message
            assistId:
              type: string
              pattern: ^asst_[a-f0-9-]{36}$
            runId:
              type: string
              pattern: ^arun_[a-f0-9-]{36}$
            stepId:
              type: string
              minLength: 1
              maxLength: 200
              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
            message:
              oneOf:
                - type: object
                  properties:
                    type:
                      type: string
                      const: text
                    text:
                      type: string
                      minLength: 1
                      maxLength: 32000
                  required:
                    - type
                    - text
                  additionalProperties: false
                - type: object
                  properties:
                    type:
                      type: string
                      const: action_request
                    operationId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                    arguments:
                      type: object
                      propertyNames:
                        type: string
                      additionalProperties: {}
                  required:
                    - type
                    - operationId
                    - arguments
                  additionalProperties: false
                - type: object
                  properties:
                    type:
                      type: string
                      const: action_confirmation
                    requestId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                  required:
                    - type
                    - requestId
                  additionalProperties: false
                - type: object
                  properties:
                    type:
                      type: string
                      const: approval_confirmation
                    requestId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                    decision:
                      type: string
                      enum:
                        - allow
                        - deny
                  required:
                    - type
                    - requestId
                    - decision
                  additionalProperties: false
                - type: object
                  properties:
                    type:
                      type: string
                      const: completion_confirmation
                    requestId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                  required:
                    - type
                    - requestId
                  additionalProperties: false
                - type: object
                  properties:
                    type:
                      type: string
                      const: cancellation_request
                    actionId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                  required:
                    - type
                    - actionId
                  additionalProperties: false
                - type: object
                  properties:
                    type:
                      type: string
                      const: authentication_response
                    requestId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                  required:
                    - type
                    - requestId
                  additionalProperties: false
                - type: object
                  properties:
                    type:
                      type: string
                      const: payment_response
                    requestId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                  required:
                    - type
                    - requestId
                  additionalProperties: false
          required:
            - type
            - assistId
            - runId
            - stepId
            - message
          additionalProperties: false
    AssistV3Response:
      type: object
      properties:
        assistId:
          type: string
          pattern: ^asst_[a-f0-9-]{36}$
        status:
          type: string
          enum:
            - planning
            - ready
            - running
            - paused
            - completed
            - cancelled
        goal:
          type: string
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - user
                  - assist
              text:
                type: string
              at:
                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:
              - role
              - text
              - at
            additionalProperties: false
        revisions:
          maxItems: 32
          type: array
          items:
            type: object
            properties:
              revisionId:
                type: string
                pattern: ^arev_[a-f0-9-]{36}$
              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))$
              searchId:
                anyOf:
                  - type: string
                  - type: 'null'
              summary:
                type: string
              plan:
                anyOf:
                  - type: object
                    properties:
                      goal:
                        type: string
                        minLength: 1
                        maxLength: 20000
                      successCriteria:
                        minItems: 1
                        maxItems: 8
                        type: array
                        items:
                          type: string
                          minLength: 1
                          maxLength: 500
                      steps:
                        minItems: 1
                        maxItems: 8
                        type: array
                        items:
                          type: object
                          properties:
                            stepId:
                              type: string
                              minLength: 1
                              maxLength: 200
                              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            objective:
                              type: string
                              minLength: 1
                              maxLength: 500
                            agentId:
                              type: string
                              minLength: 1
                              maxLength: 200
                              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            operationId:
                              type: string
                              minLength: 1
                              maxLength: 200
                              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            alternativeAgentIds:
                              default: []
                              maxItems: 3
                              type: array
                              items:
                                type: string
                                minLength: 1
                                maxLength: 200
                                pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            dependsOn:
                              default: []
                              maxItems: 8
                              type: array
                              items:
                                type: string
                                minLength: 1
                                maxLength: 200
                                pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            evidenceRequired:
                              type: string
                              minLength: 1
                              maxLength: 500
                            accessRequired:
                              default: []
                              maxItems: 8
                              type: array
                              items:
                                type: string
                                minLength: 1
                                maxLength: 200
                            approvalRequired:
                              default: true
                              type: boolean
                              const: true
                          required:
                            - stepId
                            - objective
                            - agentId
                            - operationId
                            - alternativeAgentIds
                            - dependsOn
                            - evidenceRequired
                            - accessRequired
                            - approvalRequired
                          additionalProperties: false
                      stoppingPoints:
                        default: []
                        maxItems: 8
                        type: array
                        items:
                          type: string
                          minLength: 1
                          maxLength: 500
                    required:
                      - goal
                      - successCriteria
                      - steps
                      - stoppingPoints
                    additionalProperties: false
                  - type: 'null'
              agents:
                maxItems: 10
                type: array
                items:
                  type: object
                  properties:
                    agentId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                    operationId:
                      type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                    name:
                      type: string
                    description:
                      anyOf:
                        - type: string
                        - type: 'null'
                    canStartThread:
                      type: boolean
                    canAttemptThread:
                      type: boolean
                    readiness:
                      type: string
                      enum:
                        - ready
                        - authentication_required
                        - recheck_required
                        - unavailable
                  required:
                    - agentId
                    - operationId
                    - name
                    - description
                    - canStartThread
                    - readiness
                  additionalProperties: false
            required:
              - revisionId
              - createdAt
              - searchId
              - summary
              - plan
              - agents
            additionalProperties: false
        latestRevisionId:
          anyOf:
            - type: string
              pattern: ^arev_[a-f0-9-]{36}$
            - type: 'null'
        quote:
          default: null
          anyOf:
            - type: object
              properties:
                quoteId:
                  type: string
                  pattern: ^aqt_[a-f0-9-]{36}$
                revisionId:
                  type: string
                  pattern: ^arev_[a-f0-9-]{36}$
                currency:
                  type: string
                  const: USD
                totalBudgetMinor:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                rateBps:
                  type: integer
                  minimum: 0
                  maximum: 1800
                rateBasis:
                  type: string
                  minLength: 1
                maximumExecutionMinor:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                maximumFeeMinor:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                unallocatedMinor:
                  type: integer
                  minimum: 0
                  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))$
                expiresAt:
                  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))$
                fundingStatus:
                  type: string
                  enum:
                    - not_authorized
                    - authorized
                cancellationTerms:
                  type: string
                  minLength: 1
              required:
                - quoteId
                - revisionId
                - currency
                - totalBudgetMinor
                - rateBps
                - rateBasis
                - maximumExecutionMinor
                - maximumFeeMinor
                - unallocatedMinor
                - createdAt
                - expiresAt
                - fundingStatus
                - cancellationTerms
              additionalProperties: false
            - type: 'null'
        funding:
          default: null
          anyOf:
            - type: object
              properties:
                fundingAuthorizationId:
                  type: string
                  pattern: ^afund_[a-f0-9-]{36}$
                quoteId:
                  type: string
                  pattern: ^aqt_[a-f0-9-]{36}$
                revisionId:
                  type: string
                  pattern: ^arev_[a-f0-9-]{36}$
                totalBudgetMinor:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                currency:
                  type: string
                  const: USD
                status:
                  type: string
                  enum:
                    - reserving
                    - reserved
                    - releasing
                    - released
                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))$
              required:
                - fundingAuthorizationId
                - quoteId
                - revisionId
                - totalBudgetMinor
                - currency
                - status
                - createdAt
              additionalProperties: false
            - type: 'null'
        run:
          default: null
          anyOf:
            - type: object
              properties:
                runId:
                  type: string
                  pattern: ^arun_[a-f0-9-]{36}$
                revisionId:
                  type: string
                  pattern: ^arev_[a-f0-9-]{36}$
                quoteId:
                  type: string
                  pattern: ^aqt_[a-f0-9-]{36}$
                actingAiId:
                  default: null
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 200
                      pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                    - type: 'null'
                status:
                  type: string
                  enum:
                    - starting
                    - running
                    - paused
                    - completed
                    - cancelled
                startedAt:
                  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))$
                settlement:
                  default: null
                  anyOf:
                    - type: object
                      properties:
                        currency:
                          type: string
                          const: USD
                        executionSpendMinor:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        outcomeFeeMinor:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        returnedMinor:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                      required:
                        - currency
                        - executionSpendMinor
                        - outcomeFeeMinor
                        - returnedMinor
                      additionalProperties: false
                    - type: 'null'
                steps:
                  minItems: 1
                  maxItems: 8
                  type: array
                  items:
                    type: object
                    properties:
                      stepId:
                        type: string
                        minLength: 1
                        maxLength: 200
                        pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                      agentId:
                        type: string
                        minLength: 1
                        maxLength: 200
                        pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                      operationId:
                        type: string
                        minLength: 1
                        maxLength: 200
                        pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                      status:
                        type: string
                        enum:
                          - pending
                          - starting
                          - thread_open
                          - waiting
                          - completed
                          - failed
                      threadId:
                        anyOf:
                          - type: string
                            minLength: 1
                            maxLength: 200
                            pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                          - type: 'null'
                      actRequestId:
                        type: string
                        minLength: 1
                        maxLength: 200
                        pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                      errorCode:
                        anyOf:
                          - type: string
                            minLength: 1
                            maxLength: 200
                            pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                          - type: 'null'
                      acceptedMessageId:
                        type: string
                        minLength: 1
                        maxLength: 200
                        pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                      observation:
                        type: object
                        properties:
                          readStatus:
                            type: string
                            enum:
                              - available
                              - unavailable
                          needsAttention:
                            type: boolean
                          pendingRequestIds:
                            type: array
                            items:
                              type: string
                              minLength: 1
                              maxLength: 200
                              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                          confirmedResultIds:
                            type: array
                            items:
                              type: string
                              minLength: 1
                              maxLength: 200
                              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                        required:
                          - readStatus
                          - needsAttention
                          - pendingRequestIds
                          - confirmedResultIds
                        additionalProperties: false
                    required:
                      - stepId
                      - agentId
                      - operationId
                      - status
                      - threadId
                      - errorCode
                    additionalProperties: false
              required:
                - runId
                - revisionId
                - quoteId
                - actingAiId
                - status
                - startedAt
                - settlement
                - steps
              additionalProperties: false
            - type: 'null'
        previousRuns:
          default: []
          maxItems: 32
          type: array
          items:
            type: object
            properties:
              run:
                type: object
                properties:
                  runId:
                    type: string
                    pattern: ^arun_[a-f0-9-]{36}$
                  revisionId:
                    type: string
                    pattern: ^arev_[a-f0-9-]{36}$
                  quoteId:
                    type: string
                    pattern: ^aqt_[a-f0-9-]{36}$
                  actingAiId:
                    default: null
                    anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 200
                        pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                      - type: 'null'
                  status:
                    type: string
                    enum:
                      - starting
                      - running
                      - paused
                      - completed
                      - cancelled
                  startedAt:
                    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))$
                  settlement:
                    default: null
                    anyOf:
                      - type: object
                        properties:
                          currency:
                            type: string
                            const: USD
                          executionSpendMinor:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          outcomeFeeMinor:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          returnedMinor:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                        required:
                          - currency
                          - executionSpendMinor
                          - outcomeFeeMinor
                          - returnedMinor
                        additionalProperties: false
                      - type: 'null'
                  steps:
                    minItems: 1
                    maxItems: 8
                    type: array
                    items:
                      type: object
                      properties:
                        stepId:
                          type: string
                          minLength: 1
                          maxLength: 200
                          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                        agentId:
                          type: string
                          minLength: 1
                          maxLength: 200
                          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                        operationId:
                          type: string
                          minLength: 1
                          maxLength: 200
                          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                        status:
                          type: string
                          enum:
                            - pending
                            - starting
                            - thread_open
                            - waiting
                            - completed
                            - failed
                        threadId:
                          anyOf:
                            - type: string
                              minLength: 1
                              maxLength: 200
                              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            - type: 'null'
                        actRequestId:
                          type: string
                          minLength: 1
                          maxLength: 200
                          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                        errorCode:
                          anyOf:
                            - type: string
                              minLength: 1
                              maxLength: 200
                              pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            - type: 'null'
                        acceptedMessageId:
                          type: string
                          minLength: 1
                          maxLength: 200
                          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                        observation:
                          type: object
                          properties:
                            readStatus:
                              type: string
                              enum:
                                - available
                                - unavailable
                            needsAttention:
                              type: boolean
                            pendingRequestIds:
                              type: array
                              items:
                                type: string
                                minLength: 1
                                maxLength: 200
                                pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                            confirmedResultIds:
                              type: array
                              items:
                                type: string
                                minLength: 1
                                maxLength: 200
                                pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
                          required:
                            - readStatus
                            - needsAttention
                            - pendingRequestIds
                            - confirmedResultIds
                          additionalProperties: false
                      required:
                        - stepId
                        - agentId
                        - operationId
                        - status
                        - threadId
                        - errorCode
                      additionalProperties: false
                required:
                  - runId
                  - revisionId
                  - quoteId
                  - actingAiId
                  - status
                  - startedAt
                  - settlement
                  - steps
                additionalProperties: false
              quote:
                type: object
                properties:
                  quoteId:
                    type: string
                    pattern: ^aqt_[a-f0-9-]{36}$
                  revisionId:
                    type: string
                    pattern: ^arev_[a-f0-9-]{36}$
                  currency:
                    type: string
                    const: USD
                  totalBudgetMinor:
                    type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  rateBps:
                    type: integer
                    minimum: 0
                    maximum: 1800
                  rateBasis:
                    type: string
                    minLength: 1
                  maximumExecutionMinor:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  maximumFeeMinor:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  unallocatedMinor:
                    type: integer
                    minimum: 0
                    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))$
                  expiresAt:
                    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))$
                  fundingStatus:
                    type: string
                    enum:
                      - not_authorized
                      - authorized
                  cancellationTerms:
                    type: string
                    minLength: 1
                required:
                  - quoteId
                  - revisionId
                  - currency
                  - totalBudgetMinor
                  - rateBps
                  - rateBasis
                  - maximumExecutionMinor
                  - maximumFeeMinor
                  - unallocatedMinor
                  - createdAt
                  - expiresAt
                  - fundingStatus
                  - cancellationTerms
                additionalProperties: false
            required:
              - run
              - quote
            additionalProperties: false
        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))$
        assistToken:
          type: string
      required:
        - assistId
        - status
        - goal
        - messages
        - revisions
        - latestRevisionId
        - quote
        - funding
        - run
        - previousRuns
        - createdAt
        - updatedAt
      additionalProperties: false
  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.