AIXBT Recipes API

openapi: 3.2.0
info:
  title: AIXBT Public Recipes API
  version: 2.0.0
  description: 'Documentation for the AIXBT public API (v2).


    Most endpoints require an API key via the `x-api-key` header. Current topics, the deprecated `/grounding` topics alias, and cluster, category, and chain metadata are public. Historical topic data and all project, intel, signal, and recipe endpoints require authentication.


    Self-serve accounts can retrieve a rolling 90 days of proprietary AIXBT history, reported in `meta.history`. The boundary applies to explicit date ranges, historical `at` snapshots, pagination, and by-ID retrieval; older requests return `403 HISTORY_WINDOW_EXCEEDED` with the same `meta.history`. Accounts with the `archive-history` entitlement are uncapped. Current Topics and published Reports are excluded, while price candles and project market metrics retain their endpoint-specific windows.


    For full usage instructions, authentication and example projects, visit the documentation: docs.aixbt.tech.'
security:
- ApiKeyAuth: []
tags:
- name: Recipes
paths:
  /v2/recipes/execute:
    post:
      summary: Execute a recipe
      description: 'Executes a recipe either from raw YAML or by registry name. AIXBT steps execute server-side

        via direct service calls. Provider steps return auto-fallback results with metadata for

        client-side enrichment.


        Exactly one of `yaml` or `recipeName` must be provided.

        The credential owner must have API access. MCP is not required.


        When execution yields at an agent step, the response includes carry-forward data and

        instructions for the agent. Resume by calling this endpoint again with `resumeFromStep`,

        `resumeInput`, and `carryForward` from the previous response.'
      tags:
      - Recipes
      x-required-entitlements:
      - api
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                yaml:
                  type: string
                  description: Raw YAML recipe definition
                recipeName:
                  type: string
                  description: Registry recipe name
                params:
                  type: object
                  additionalProperties:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                  description: Recipe parameters
                resumeFromStep:
                  type: string
                  description: Step ID to resume from
                resumeInput:
                  type: object
                  description: Agent output from the yielded step
                carryForward:
                  type: object
                  description: Pre-yield step data from previous response
      responses:
        '200':
          description: Recipe execution result (awaiting_agent or complete)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipeExecutionResult'
        '400':
          description: Validation error or invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Current account plan lacks access, or a recipe step requests history outside the account's entitlement window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Registry recipe not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Recipe step execution failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Required service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: postV2RecipesExecute
  /v2/recipes:
    get:
      summary: List available recipes
      description: Returns a list of all curated AIXBT recipes available in the registry.
      tags:
      - Recipes
      responses:
        '200':
          description: List of recipe summaries
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    type: integer
                    example: 200
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecipeSummary'
        '500':
          description: Failed to list recipes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: getV2Recipes
  /v2/recipes/{name}:
    get:
      summary: Get recipe by name
      description: Returns the full YAML definition for a specific recipe.
      tags:
      - Recipes
      parameters:
      - in: path
        name: name
        required: true
        schema:
          type: string
        description: Recipe name
      responses:
        '200':
          description: Recipe details with YAML definition
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    type: integer
                    example: 200
                  data:
                    $ref: '#/components/schemas/RecipeDetail'
        '404':
          description: Recipe not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Failed to fetch recipe
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: getV2RecipesByName
  /v2/recipes/validate:
    post:
      summary: Validate a recipe
      description: 'Validates a raw YAML recipe definition without executing it. Returns structural

        validation issues and basic recipe metadata when valid.'
      tags:
      - Recipes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                yaml:
                  type: string
                  description: Raw YAML recipe definition to validate (mutually exclusive with name)
                recipeName:
                  type: string
                  description: Registry recipe name to validate (mutually exclusive with yaml)
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                  recipe:
                    type: object
                    description: Present when valid
                    properties:
                      name:
                        type: string
                      version:
                        type: string
                      description:
                        type: string
                      stepCount:
                        type: integer
                      paramCount:
                        type: integer
        '400':
          description: Missing or invalid input (yaml/recipeName)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Recipe not found (when using recipeName)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: postV2RecipesValidate
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      description: Error response. Middleware may include additional rate-limit or access metadata.
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
        status:
          type: integer
        data: {}
        meta:
          type: object
          additionalProperties: true
        details:
          type: object
          additionalProperties: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        limitType:
          type: string
          enum:
          - minute
          - day
          description: Rate-limit window that was exhausted.
        retryAfterMs:
          type: integer
          minimum: 0
          description: Milliseconds until the exhausted window resets.
        limits:
          type: object
          required:
          - minute
          - day
          properties:
            minute:
              $ref: '#/components/schemas/RateLimitWindow'
            day:
              $ref: '#/components/schemas/RateLimitWindow'
        issues:
          type: array
          items:
            type: object
            required:
            - path
            - message
            properties:
              path:
                type: string
              message:
                type: string
      additionalProperties: true
    RateLimitWindow:
      type: object
      required:
      - limit
      - remaining
      - resetAt
      properties:
        limit:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        resetAt:
          type: string
          format: date-time
    RecipeExecutionResult:
      oneOf:
      - type: object
        required:
        - status
        - recipe
        - version
        - step
        - instructions
        - returns
        - data
        - tokenCount
        - progress
        - remaining
        properties:
          status:
            type: string
            enum:
            - awaiting_agent
          recipe:
            type: string
          version:
            type: string
          step:
            type: string
          instructions:
            type: string
          returns:
            type: object
            additionalProperties: true
          data:
            type: object
            additionalProperties: true
          tokenCount:
            type: integer
            minimum: 0
          progress:
            type: object
            required:
            - stepsCompleted
            - stepsTotal
            - segmentIndex
            - segmentsTotal
            properties:
              stepsCompleted:
                type: integer
                minimum: 0
              stepsTotal:
                type: integer
                minimum: 0
              segmentIndex:
                type: integer
                minimum: 0
              segmentsTotal:
                type: integer
                minimum: 0
          remaining:
            type: string
          parallel:
            type: object
            required:
            - items
            - itemKey
            - concurrency
            - perItemContext
            - sharedContext
            properties:
              items:
                type: array
                items: {}
              itemKey:
                type: string
              concurrency:
                type: integer
                minimum: 1
              perItemContext:
                type: array
                items:
                  type: string
              sharedContext:
                type: array
                items:
                  type: string
          parallelExecution:
            type: string
          contextHints:
            type: array
            items:
              type: string
          carryForward:
            type: object
            additionalProperties: true
          meta:
            $ref: '#/components/schemas/HistoryResponseMeta'
        additionalProperties: true
      - type: object
        required:
        - status
        - recipe
        - version
        - timestamp
        - data
        - tokenCount
        properties:
          status:
            type: string
            enum:
            - complete
          recipe:
            type: string
          version:
            type: string
          timestamp:
            type: string
            format: date-time
          data:
            type: object
            additionalProperties: true
          tokenCount:
            type: integer
            minimum: 0
          hints:
            type: object
            properties:
              combine:
                type: array
                items:
                  type: string
              key:
                type: string
              include:
                type: array
                items:
                  type: string
          analysis:
            type: object
            required:
            - instructions
            properties:
              instructions:
                type: string
              output:
                type: string
              context:
                type: array
                items:
                  type: string
          contextHints:
            type: array
            items:
              type: string
          meta:
            $ref: '#/components/schemas/HistoryResponseMeta'
        additionalProperties: true
    RecipeDetail:
      type: object
      required:
      - name
      - updatedAt
      - yaml
      properties:
        name:
          type: string
        updatedAt:
          type: string
          format: date-time
        yaml:
          type: string
    HistoryResponseMeta:
      type: object
      required:
      - history
      properties:
        history:
          $ref: '#/components/schemas/HistoryAccessMeta'
    RecipeSummary:
      type: object
      required:
      - name
      - version
      - description
      - paramCount
      - estimatedTokens
      properties:
        name:
          type: string
        version:
          type: string
        description:
          type: string
        paramCount:
          type: integer
          minimum: 0
        estimatedTokens:
          type:
          - integer
          - 'null'
          minimum: 0
    HistoryAccessMeta:
      type: object
      required:
      - lookbackDays
      - earliestAvailableAt
      properties:
        lookbackDays:
          type:
          - integer
          - 'null'
          example: 90
        earliestAvailableAt:
          type:
          - string
          - 'null'
          format: date-time
    Pagination:
      type: object
      required:
      - page
      - limit
      - totalCount
      - hasMore
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
        totalCount:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key to authorize requests