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

# Discover the same API choices as the Ask page

> Requires ask:create. A question uses the shared App interpreter/search and creates no task, approval or paid provider request. Explicit workflow objects retain their plan/auto behavior.



## OpenAPI

````yaml /openapi/apiosk-api.json post /v2/ask
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/ask:
    post:
      summary: Discover the same API choices as the Ask page
      description: >-
        Requires ask:create. A question uses the shared App interpreter/search
        and creates no task, approval or paid provider request. Explicit
        workflow objects retain their plan/auto behavior.
      operationId: ask
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 255
          description: 'Retry-safe key: the same key with the same body pays once.'
          example: nomi-request-983472
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    question:
                      type: string
                      minLength: 1
                      maxLength: 16000
                      description: Limit counted in UTF-16 code units.
                  required:
                    - question
                  additionalProperties: false
                - type: object
                  properties:
                    execution_mode:
                      type: string
                      enum:
                        - plan
                        - auto
                      default: plan
                    max_spend:
                      type: number
                      description: Required with auto.
                      example: 1
                    limit:
                      type: integer
                      minimum: 1
                      maximum: 50
                    wait_seconds:
                      type: integer
                      minimum: 0
                      maximum: 55
                    workflow:
                      $ref: '#/components/schemas/WorkflowInput'
                  additionalProperties: false
                  required:
                    - workflow
      responses:
        '200':
          description: Question source choices, or a workflow plan/run
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AskChoices'
                  - $ref: '#/components/schemas/BuyerRun'
        '202':
          description: Still running
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerRun'
        '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:
    WorkflowInput:
      type: object
      additionalProperties: false
      required:
        - slug
        - input
      properties:
        slug:
          type: string
          description: Workflow slug from GET /v2/ask/workflows.
          example: european-company-dossier
        input:
          type: object
          additionalProperties: true
          example:
            name: Mollie B.V.
            country: NL
            registration: '30204462'
    AskChoices:
      type: object
      properties:
        status:
          type: string
          enum:
            - choices
            - needs_input
            - partial
        question:
          type: string
        parsed_request:
          type: object
        apis:
          type: array
          items:
            $ref: '#/components/schemas/AskChoice'
        searches:
          type: object
        errors:
          type: array
          items:
            type: object
      required:
        - status
        - question
        - parsed_request
        - apis
        - searches
        - errors
    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'
    BuyerError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
          additionalProperties: true
    AskChoice:
      type: object
      properties:
        api_id:
          type: string
          description: Opaque executable selection identity. Copy exactly.
        capability:
          type:
            - string
            - 'null'
        origin:
          type: string
          enum:
            - apiosk
            - coinbase
        name:
          type: string
        source_slug:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        executable:
          type: boolean
        availability:
          type: string
        inputs:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              required:
                type: boolean
              schema:
                type:
                  - object
                  - 'null'
            required:
              - field
              - schema
        input_values:
          type: object
          additionalProperties: true
        missing_inputs:
          type: array
          items:
            type: string
        outputs:
          type:
            - array
            - 'null'
          items:
            type: object
            properties:
              field:
                type: string
              required:
                type: boolean
              schema:
                type:
                  - object
                  - 'null'
            required:
              - field
              - schema
          description: >-
            Declared fields/schemas only; actual output values arrive after
            execution.
        lookup:
          type:
            - object
            - 'null'
        buyer_price:
          type: object
          properties:
            currency:
              type: string
            provider_atomic:
              type: string
            buyer_atomic:
              type: string
              description: >-
                Per-call price in millionths of USDC. Native lookups can add to
                the total.
      required:
        - origin
        - name
        - executable
    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_…'

````