> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiosk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute the API selected from Ask

> Requires sources:execute. Uses the same selected preparation, authorization and balance executor as the App. Reusing the idempotency key with the same selection/input recovers the saved run. The existing signed App/MCP continuation body remains supported separately.



## OpenAPI

````yaml /openapi/apiosk-api.json post /v2/execute
openapi: 3.1.0
info:
  title: Apiosk API
  version: 2.0.0
  description: >-
    Buy verifiable data per call with an organisation API key. Ask returns the
    same API choices as the App; execute runs the selected API with your inputs
    and approved cap. Direct source calls and optional multi-source plans remain
    available.
servers:
  - url: https://gateway.apiosk.com
security:
  - apiKey: []
paths:
  /v2/execute:
    post:
      summary: Execute the API selected from Ask
      description: >-
        Requires sources:execute. Uses the same selected preparation,
        authorization and balance executor as the App. Reusing the idempotency
        key with the same selection/input recovers the saved run. The existing
        signed App/MCP continuation body remains supported separately.
      operationId: executeSelectedApi
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_id:
                  type: string
                capability:
                  type: string
                input:
                  type: object
                  additionalProperties: true
                max_spend:
                  oneOf:
                    - type: number
                      minimum: 0
                    - type: string
                  description: Explicit approved total in USD; checked before purchase.
                wait_seconds:
                  type: integer
                  minimum: 0
                  maximum: 55
                  description: >-
                    Registered APIs only; external purchases return
                    asynchronously.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 50
              required:
                - api_id
                - max_spend
              additionalProperties: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BuyerRun'
                  - $ref: '#/components/schemas/ExternalPurchase'
        '202':
          description: Still running
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BuyerRun'
                  - $ref: '#/components/schemas/ExternalPurchase'
        '400':
          description: invalid_request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '401':
          description: invalid_api_key, api_key_expired or api_key_revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '402':
          description: insufficient_balance or spend_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '403':
          description: insufficient_scope or organisation_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '404':
          description: source_not_found or operation_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '409':
          description: idempotency_conflict or request_in_progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '422':
          description: invalid_source_input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '429':
          description: rate_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '502':
          description: source_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
        '503':
          description: service_unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerError'
components:
  schemas:
    BuyerRun:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - requires_approval
            - running
            - completed
            - partial
            - needs_input
            - needs_selection
            - unsupported
            - cancelled
            - failed
        question:
          type: string
        capability:
          type: string
          description: European capability slug for a structured capability plan or run.
        normalized_records:
          type: array
          description: >-
            Contract-extracted provider facts grouped by subject. Equal facts
            for one subject are combined with all their source references;
            absent fields are never invented.
          items:
            type: object
            properties:
              entity_ref:
                type: string
                format: uuid
              entity_refs:
                type: array
                description: >-
                  Original subject references joined by a matching stable
                  identifier.
                items:
                  type: string
                  format: uuid
              facts:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                    value: {}
                    observed_at:
                      type: string
                      format: date-time
                    expires_at:
                      type: string
                      format: date-time
                    sources:
                      type: array
                      items:
                        type: object
                        properties:
                          source_id:
                            type: string
                          result_ref:
                            type: string
                            format: uuid
                          source_url:
                            type:
                              - string
                              - 'null'
                          retrieved_at:
                            type: string
                            format: date-time
                          source_pointer:
                            type:
                              - string
                              - 'null'
        plan:
          type: object
          properties:
            quote_ref:
              type: string
              format: uuid
            expires_at:
              type: string
              format: date-time
            steps:
              type: array
              items:
                type: object
                properties:
                  source_id:
                    type: string
                    example: kvk-dutch-business-register
                  operation:
                    type: string
                    example: company_registry.search
                  name:
                    type: string
                  conditional:
                    type: boolean
                  estimated_cost:
                    type: object
                    properties:
                      amount:
                        type: number
                        example: 0.023
                      amount_micro_usd:
                        type: string
                        example: '23000'
                      currency:
                        type: string
                        example: USD
            estimated_total:
              type: object
              properties:
                amount:
                  type: number
                  example: 0.023
                amount_micro_usd:
                  type: string
                  example: '23000'
                currency:
                  type: string
                  example: USD
        answer:
          type:
            - object
            - 'null'
          description: >-
            Apiosk's reading of the results, with evidence pointers. Null for a
            direct call.
        data:
          type: object
          description: The source document, when the run produced exactly one.
        results:
          type: array
          items:
            type: object
            properties:
              result_ref:
                type: string
                format: uuid
              source:
                type: object
                properties:
                  provider:
                    type: string
                  name:
                    type: string
              data:
                type: object
        usage:
          type: object
          properties:
            sources:
              type: array
              items:
                type: object
                properties:
                  source_id:
                    type: string
                  operation:
                    type: string
                  calls:
                    type: integer
                  cost:
                    type: object
                    properties:
                      amount:
                        type: number
                        example: 0.023
                      amount_micro_usd:
                        type: string
                        example: '23000'
                      currency:
                        type: string
                        example: USD
            cost:
              type: object
              properties:
                amount:
                  type: number
                  example: 0.023
                amount_micro_usd:
                  type: string
                  example: '23000'
                currency:
                  type: string
                  example: USD
            held:
              type: object
              properties:
                amount:
                  type: number
                  example: 0.023
                amount_micro_usd:
                  type: string
                  example: '23000'
                currency:
                  type: string
                  example: USD
        balance:
          type: object
          properties:
            remaining:
              type: object
              properties:
                amount:
                  type: number
                  example: 0.023
                amount_micro_usd:
                  type: string
                  example: '23000'
                currency:
                  type: string
                  example: USD
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
        retry_after_ms:
          type: integer
        message:
          type:
            - string
            - 'null'
          description: Natural-language clarification for needs_input.
        needs_input:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              schema:
                type: object
        candidates:
          type:
            - array
            - 'null'
          items:
            type: object
        approval_required_reason:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        metadata:
          type: object
          description: Attribution for a single result, when present.
        continuation:
          $ref: '#/components/schemas/Continuation'
    ExternalPurchase:
      type: object
      properties:
        id:
          type: string
          format: uuid
        purchase_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - requires_approval
            - running
            - succeeded
            - failed
        source:
          type: object
        quote:
          type: object
        result: {}
        result_present:
          type: boolean
        result_truncated:
          type: boolean
        billing:
          type:
            - object
            - 'null'
        error:
          type:
            - object
            - 'null'
      required:
        - id
        - status
        - result
        - result_present
        - billing
    BuyerError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: true
    Continuation:
      type: object
      required:
        - state
        - actions
      properties:
        state:
          $ref: '#/components/schemas/ContinuationState'
        actions:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - action_id
              - kind
              - label
              - requires_authorization
              - input_schema
            properties:
              action_id:
                type: string
                format: uuid
              kind:
                type: string
                enum:
                  - select_entity
                  - supply_input
              label:
                type: string
              requires_authorization:
                type: boolean
                const: false
              input_schema:
                type: object
                additionalProperties: true
    ContinuationState:
      type: object
      additionalProperties: false
      description: Signed snapshot returned by this run. Copy unchanged.
      required:
        - schema_version
        - state_ref
        - revision
        - expires_at
        - focus
        - state_token
      properties:
        schema_version:
          type: string
          enum:
            - '2'
        state_ref:
          type: string
          format: uuid
        revision:
          type: integer
          minimum: 0
        expires_at:
          type: string
          format: date-time
        focus:
          type: object
          additionalProperties: false
          required:
            - entity_refs
            - goal_refs
          properties:
            entity_refs:
              type: array
              items:
                type: string
                format: uuid
            goal_refs:
              type: array
              items:
                type: string
                format: uuid
        state_token:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An organisation API key: Authorization: Bearer apk_org_live_…'

````