Apiosk Capabilities API

openapi: 3.2.0
info:
  title: Apiosk Capabilities 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: []
tags:
- name: Capabilities
paths:
  /v2/capabilities/resolve:
    post:
      summary: Find fitting European source operations
      description: Free endpoint routing for a structured European capability. Requires sources:read; no provider call or charge.
      operationId: resolveEuropeanCapability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EuropeanCapabilityRequest'
      responses:
        '200':
          description: Accepted endpoint operations, input fit, price and freshness.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EuropeanCapabilityResolution'
        '400':
          description: Invalid country or request
        '401':
          description: Invalid API key
        '403':
          description: Insufficient scope
        '422':
          description: No fitting operation or invalid input
      tags:
      - Capabilities
  /v2/capabilities/plan:
    post:
      summary: Price a structured European capability
      description: Save one total-price plan from fitting operations. Requires ask:create. Execution requires a separate POST /v2/asks/{id}/run with ask:execute.
      operationId: planEuropeanCapability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EuropeanCapabilityRequest'
      responses:
        '200':
          description: Saved plan for review and explicit approval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerRun'
        '400':
          description: Invalid country or request
        '401':
          description: Invalid API key
        '403':
          description: Insufficient scope
        '422':
          description: No fitting operation or invalid input
      tags:
      - Capabilities
components:
  schemas:
    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
    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'
    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
    EuropeanCapabilityRequest:
      type: object
      additionalProperties: false
      required:
      - capability
      properties:
        capability:
          type: string
          enum:
          - eu.company.profile
          - eu.tenders.search
          - eu.statistics.query
        country:
          type: string
          pattern: ^[A-Za-z]{2}$
          description: Optional two-letter ISO country code used for source routing.
        input:
          type: object
          description: Structured fact-type input; inspect resolve for exact field schemas.
        operation:
          type: string
          description: Optional exact operation selector, required for CBS observation metrics.
    EuropeanCapabilityResolution:
      type: object
      required:
      - capability
      - sources
      - ready_source_count
      properties:
        capability:
          type: string
        country:
          type:
          - string
          - 'null'
        ready_source_count:
          type: integer
          minimum: 0
        sources:
          type: array
          items:
            type: object
            properties:
              source_id:
                type: string
              name:
                type: string
              role:
                type: string
                enum:
                - primary
                - supplementary
              ready:
                type: boolean
              operations:
                type: array
                items:
                  type: object
                  properties:
                    operation:
                      type: string
                    endpoint_id:
                      type: string
                      format: uuid
                    method:
                      type: string
                    path:
                      type: string
                    inputs:
                      type: array
                      items:
                        type: object
                    input:
                      type: object
                    missing_input:
                      type: array
                      items:
                        type: string
                    invalid_input:
                      type: array
                      items:
                        type: string
                    ready:
                      type: boolean
                    output:
                      type: array
                      items:
                        type: string
                    freshness_seconds:
                      type:
                      - integer
                      - 'null'
                    price:
                      type: object
                    run_url:
                      type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An organisation API key: Authorization: Bearer apk_org_live_…'