openapi: 3.0.3
info:
  title: Agents API
  version: 1.0.0
  description: >
    AI Agents with tool-use capabilities. Create agents bound to AI providers,
    attach tools, run multi-step generations, and inspect execution traces.
  contact:
    name: SOAT API Support

servers:
  - url: '{baseUrl}'
    description: Base URL of your SOAT deployment (e.g. https://your-soat.com or http://localhost:5047)
    variables:
      baseUrl:
        description: The base URL of your SOAT deployment
        default: http://localhost:5047

tags:
  - name: Agents
    description: Manage AI agents
  - name: Agent Traces
    description: View agent traces
security:
  - bearerAuth: []

paths:
  /api/v1/agents:
    post:
      tags:
        - Agents
      summary: Create an agent
      description: Creates a new agent bound to an AI provider.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            examples:
              minimal:
                summary: Minimal agent
                value:
                  ai_provider_id: aip_V1StGXR8Z5jdHi6B
              full:
                summary: Agent with tools and instructions
                value:
                  ai_provider_id: aip_V1StGXR8Z5jdHi6B
                  name: Research Assistant
                  instructions: You are a helpful research assistant.
                  model: gpt-4o
                  tool_ids:
                    - tool_abc123
                  max_steps: 10
                  temperature: 0.7
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Agents
      summary: List agents
      description: Returns all agents in the project.
      operationId: listAgents
      parameters:
        - name: project_id
          in: query
          required: false
          schema:
            type: string
          description: Project public ID to filter by
      responses:
        '200':
          description: List of agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents/{agent_id}:
    get:
      tags:
        - Agents
      summary: Get an agent
      description: Returns a single agent by ID.
      operationId: getAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Agents
      summary: Update an agent
      description: Updates an existing agent. Identical to PATCH — both perform partial updates.
      operationId: updateAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Agent updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
        - Agents
      summary: Partially update an agent
      description: Partially updates an existing agent. Identical to PUT — both perform partial updates.
      operationId: patchAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Agent updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Agents
      summary: Delete an agent
      description: >
        Deletes an agent by ID. Fails with `409` if the agent has dependent
        generations or traces, unless `force=true` is passed, in which case
        those generations and traces are deleted along with the agent.
      operationId: deleteAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: force
          in: query
          required: false
          description: >
            When `true`, deletes the agent's dependent generations and traces
            instead of returning `409 AGENT_HAS_DEPENDENTS`.
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: Deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Agent has dependent generations or traces (pass `force=true` to delete anyway)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents/{agent_id}/generate:
    post:
      tags:
        - Agents
      summary: Run an agent generation
      description: >
        Sends messages to the agent, resolves its tools, and runs the AI model
        loop. Supports streaming via `stream: true`. Client tools pause the
        generation and return `requires_action`.
      operationId: createAgentGeneration
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentGenerationRequest'
            examples:
              basic:
                summary: Simple generation
                value:
                  messages:
                    - role: user
                      content: What is the weather in Tokyo?
              toolOutput:
                summary: Use a tool output as user message content
                value:
                  messages:
                    - role: user
                      content:
                        type: tool_output
                        tool_id: tool_audio_to_text
                        input:
                          url: https://example.com/audio.mp3
                        output_path: text
              streaming:
                summary: Streaming generation
                value:
                  messages:
                    - role: user
                      content: Summarize the latest report.
                  stream: true
      responses:
        '200':
          description: Generation result or SSE stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentGenerationResponse'
            text/event-stream:
              schema:
                type: string
                description: 'SSE stream of delta chunks ending with `data: [DONE]`.'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent or AI provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: >
            Upstream AI provider error (AI_PROVIDER_ERROR). The error `meta`
            includes the `generation_id` and `trace_id` of the failed
            generation for post-mortem debugging via GET /api/v1/generations/{generation_id}.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents/{agent_id}/generate/{generation_id}/tool-outputs:
    post:
      tags:
        - Agents
      summary: Submit tool outputs for a paused generation
      description: >
        Resumes a generation that was paused due to client tool calls.
        Provide tool outputs for each pending tool call.
      operationId: submitAgentToolOutputs
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitToolOutputsRequest'
      responses:
        '200':
          description: Generation result after resuming
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentGenerationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent or generation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token or sk_ api key
  schemas:
    Agent:
      type: object
      properties:
        id:
          type: string
          description: Public ID of the agent
          example: agent_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          description: Public ID of the owning project
          x-soat-ref: projects
        ai_provider_id:
          type: string
          description: Public ID of the AI provider
          x-soat-ref: ai-providers
        name:
          type: string
          nullable: true
          description: Display name
        instructions:
          type: string
          nullable: true
          description: System instructions guiding behavior
        model:
          type: string
          nullable: true
          description: Model identifier
        tool_ids:
          x-soat-ref: tools
          type: array
          nullable: true
          items:
            type: string
          description: Public IDs of attached agent tools
        tools:
          type: array
          nullable: true
          items:
            $ref: './tools.yaml#/components/schemas/CreateToolRequest'
          description: >-
            Ephemeral tool definitions available only to this agent's
            generations — not persisted as separate Tool resources, so they
            never appear in `GET /tools` and cannot be targeted by
            `active_tool_ids`/`step_rules` (which reference `tool_ids`).
            Cannot be of type `pipeline`; nest a persisted pipeline tool via
            `tool_ids` instead. See [Inline Tool Definitions](/docs/modules/agents#inline-tool-definitions).
        max_steps:
          type: integer
          nullable: true
          description: Maximum agent loop steps before stopping
        tool_choice:
          nullable: true
          description: 'Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "name": "my_tool" }`).'
        stop_conditions:
          type: array
          nullable: true
          items:
            type: object
          description: Stop conditions
        active_tool_ids:
          x-soat-ref: tools
          type: array
          nullable: true
          items:
            type: string
          description: Subset of toolIds active per step
        step_rules:
          type: array
          nullable: true
          items:
            type: object
          description: Per-step overrides
        boundary_policy:
          type: object
          nullable: true
          description: Allowed/denied SOAT actions
        temperature:
          type: number
          nullable: true
          description: Sampling temperature
        knowledge_config:
          type: object
          nullable: true
          description: Knowledge retrieval config injected before every generation
          properties:
            memory_ids:
              x-soat-ref: memories
              type: array
              items:
                type: string
            memory_tags:
              type: array
              items:
                type: string
            document_ids:
              x-soat-ref: documents
              type: array
              items:
                type: string
            document_paths:
              type: array
              items:
                type: string
            min_score:
              type: number
            limit:
              type: integer
            write_memory_id:
              x-soat-ref: memories
              type: string
              nullable: true
              description: Public ID of the memory the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
            extraction:
              description: Automatic fact extraction from completed generation turns (requires write_memory_id). Pass `true` to enable with defaults, or an object to customize the provider, model, and prompt used for the extraction completion. Extracted facts are written to the write memory through the standard dedup/merge/skip algorithm.
              oneOf:
                - type: boolean
                - type: object
                  properties:
                    enabled:
                      type: boolean
                      description: Defaults to true when the object form is used. Set false to keep the configuration but disable extraction.
                    ai_provider_id:
                      x-soat-ref: ai-providers
                      type: string
                      description: AI provider override for extraction calls. Must belong to the agent's project. Its default_model becomes the model fallback.
                    model:
                      type: string
                      description: Model override for extraction calls.
                    prompt:
                      type: string
                      description: Replaces the default task instructions. The JSON response contract and the conversation transcript are always appended by the server.
        output_schema:
          type: object
          nullable: true
          description: 'JSON Schema describing the structured object the model must return. When set, non-streaming generations use the AI SDK to constrain output to this schema; the parsed value is returned as `output.object` in the generation response. See the Structured Output section in the Agents module docs.'
        max_context_messages:
          type: integer
          nullable: true
          description: Maximum number of recent messages to include in the context window sent to the model. When null, all messages are included.
        single_session_per_actor:
          type: boolean
          description: When true, only one open session per actor_id is allowed for this agent. Creating a second open session for the same actor returns 409.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateAgentRequest:
      type: object
      required:
        - ai_provider_id
      properties:
        project_id:
          x-soat-ref: projects
          type: string
          description: Public ID of the project
        ai_provider_id:
          x-soat-ref: ai-providers
          type: string
          description: Public ID of the AI provider
        name:
          type: string
        instructions:
          type: string
        model:
          type: string
        tool_ids:
          x-soat-ref: tools
          type: array
          items:
            type: string
        tools:
          type: array
          items:
            $ref: './tools.yaml#/components/schemas/CreateToolRequest'
          description: >-
            Ephemeral tool definitions available only to this agent's
            generations — no separate Tool resource is created (any
            `project_id` on an entry is ignored), so they never appear in
            `GET /tools` and cannot be targeted by `active_tool_ids`/
            `step_rules` (which reference `tool_ids`). Cannot be of type
            `pipeline`; nest a persisted pipeline tool via `tool_ids` instead.
            Use `tool_ids` to reference existing tools and `tools` for ones
            scoped to just this agent.
        max_steps:
          type: integer
        tool_choice:
          description: 'Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "name": "my_tool" }`).'
        stop_conditions:
          type: array
          items:
            type: object
        active_tool_ids:
          x-soat-ref: tools
          type: array
          items:
            type: string
        step_rules:
          type: array
          items:
            type: object
        boundary_policy:
          type: object
        temperature:
          type: number
        knowledge_config:
          type: object
          properties:
            memory_ids:
              x-soat-ref: memories
              type: array
              items:
                type: string
            memory_tags:
              type: array
              items:
                type: string
            document_ids:
              x-soat-ref: documents
              type: array
              items:
                type: string
            document_paths:
              type: array
              items:
                type: string
            min_score:
              type: number
            limit:
              type: integer
            write_memory_id:
              x-soat-ref: memories
              type: string
              nullable: true
              description: Public ID of the memory the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
            extraction:
              description: Automatic fact extraction from completed generation turns (requires write_memory_id). Pass `true` to enable with defaults, or an object to customize the provider, model, and prompt used for the extraction completion. Extracted facts are written to the write memory through the standard dedup/merge/skip algorithm.
              oneOf:
                - type: boolean
                - type: object
                  properties:
                    enabled:
                      type: boolean
                      description: Defaults to true when the object form is used. Set false to keep the configuration but disable extraction.
                    ai_provider_id:
                      x-soat-ref: ai-providers
                      type: string
                      description: AI provider override for extraction calls. Must belong to the agent's project. Its default_model becomes the model fallback.
                    model:
                      type: string
                      description: Model override for extraction calls.
                    prompt:
                      type: string
                      description: Replaces the default task instructions. The JSON response contract and the conversation transcript are always appended by the server.
        output_schema:
          type: object
          nullable: true
          description: 'JSON Schema describing the structured object the model must return. When set, non-streaming generations use the AI SDK to constrain output to this schema; the parsed value is returned as `output.object` in the generation response. See the Structured Output section in the Agents module docs.'
        max_context_messages:
          type: integer
          description: Maximum number of recent messages included in the context window. Null means no limit.
        single_session_per_actor:
          type: boolean
          description: When true, only one open session per actor_id is allowed for this agent.

    UpdateAgentRequest:
      type: object
      properties:
        ai_provider_id:
          x-soat-ref: ai-providers
          type: string
        name:
          type: string
          nullable: true
        instructions:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        tool_ids:
          x-soat-ref: tools
          type: array
          nullable: true
          items:
            type: string
        tools:
          type: array
          nullable: true
          items:
            $ref: './tools.yaml#/components/schemas/CreateToolRequest'
          description: >-
            Ephemeral tool definitions available only to this agent's
            generations — no separate Tool resource is created (any
            `project_id` on an entry is ignored), so they never appear in
            `GET /tools` and cannot be targeted by `active_tool_ids`/
            `step_rules` (which reference `tool_ids`). Cannot be of type
            `pipeline`; nest a persisted pipeline tool via `tool_ids` instead.
            Replaces the agent's entire `tools` array; set to `null` to clear.
        max_steps:
          type: integer
          nullable: true
        tool_choice:
          nullable: true
          description: 'Tool choice strategy. Accepts a string (`"auto"`, `"required"`) or an object (`{ "type": "tool", "name": "my_tool" }`).'
        stop_conditions:
          type: array
          nullable: true
          items:
            type: object
        active_tool_ids:
          x-soat-ref: tools
          type: array
          nullable: true
          items:
            type: string
        step_rules:
          type: array
          nullable: true
          items:
            type: object
        boundary_policy:
          type: object
          nullable: true
        temperature:
          type: number
          nullable: true
        knowledge_config:
          type: object
          nullable: true
          properties:
            memory_ids:
              x-soat-ref: memories
              type: array
              items:
                type: string
            memory_tags:
              type: array
              items:
                type: string
            document_ids:
              x-soat-ref: documents
              type: array
              items:
                type: string
            document_paths:
              type: array
              items:
                type: string
            min_score:
              type: number
            limit:
              type: integer
            write_memory_id:
              x-soat-ref: memories
              type: string
              nullable: true
              description: Public ID of the memory the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
            extraction:
              description: Automatic fact extraction from completed generation turns (requires write_memory_id). Pass `true` to enable with defaults, or an object to customize the provider, model, and prompt used for the extraction completion. Extracted facts are written to the write memory through the standard dedup/merge/skip algorithm.
              oneOf:
                - type: boolean
                - type: object
                  properties:
                    enabled:
                      type: boolean
                      description: Defaults to true when the object form is used. Set false to keep the configuration but disable extraction.
                    ai_provider_id:
                      x-soat-ref: ai-providers
                      type: string
                      description: AI provider override for extraction calls. Must belong to the agent's project. Its default_model becomes the model fallback.
                    model:
                      type: string
                      description: Model override for extraction calls.
                    prompt:
                      type: string
                      description: Replaces the default task instructions. The JSON response contract and the conversation transcript are always appended by the server.
        output_schema:
          type: object
          nullable: true
          description: 'JSON Schema describing the structured object the model must return. When set, non-streaming generations use the AI SDK to constrain output to this schema; the parsed value is returned as `output.object` in the generation response. See the Structured Output section in the Agents module docs.'
        max_context_messages:
          type: integer
          nullable: true
          description: Maximum number of recent messages included in the context window. Null means no limit.
        single_session_per_actor:
          type: boolean
          nullable: true
          description: When true, only one open session per actor_id is allowed for this agent.

    CreateAgentGenerationRequest:
      type: object
      required:
        - messages
      properties:
        messages:
          type: array
          minItems: 1
          items:
            type: object
            additionalProperties: false
            required:
              - role
              - content
            properties:
              role:
                type: string
                enum:
                  - system
                  - user
                  - assistant
              content:
                oneOf:
                  - type: string
                  - $ref: '#/components/schemas/ToolOutputMessageContent'
                  - $ref: '#/components/schemas/DocumentMessageContent'
        stream:
          type: boolean
          default: false
          description: When true the response is an SSE stream
        trace_id:
          x-soat-ref: traces
          type: string
          x-soat-server-managed: true
          description: Optional trace ID to group generations
        parent_trace_id:
          x-soat-ref: traces
          type: string
          nullable: true
          x-soat-server-managed: true
          description: The trace ID of the parent agent generation that triggered this one (for agent-to-agent calls)
        root_trace_id:
          x-soat-ref: traces
          type: string
          nullable: true
          x-soat-server-managed: true
          description: The trace ID of the root generation in the call chain; if omitted, this generation is the root
        max_call_depth:
          type: integer
          minimum: 0
          default: 10
          x-soat-server-managed: true
          description: Maximum nested agent-call depth; 0 short-circuits with a depth-guard response
        tool_context:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Key-value pairs injected as context headers into all tool call requests made during this generation.
        action_id:
          type: string
          description: Logical action label recorded on the generation's usage meter, so spend can be rolled up per action (e.g. an A/B/C/D operating action).
        knowledge_config:
          type: object
          nullable: true
          description: Per-generation knowledge retrieval override. Array filters (memory_ids, memory_tags, document_ids, document_paths) are unioned with the agent's stored knowledge_config; scalar fields (min_score, limit) use the per-generation value when present.
          properties:
            memory_ids:
              x-soat-ref: memories
              type: array
              items:
                type: string
            memory_tags:
              type: array
              items:
                type: string
            document_ids:
              x-soat-ref: documents
              type: array
              items:
                type: string
            document_paths:
              type: array
              items:
                type: string
            min_score:
              type: number
            limit:
              type: integer

    ToolOutputMessageContent:
      type: object
      required:
        - type
        - tool_id
      properties:
        type:
          type: string
          enum:
            - tool_output
        tool_id:
          x-soat-ref: tools
          type: string
          description: Public ID of the tool to execute before generation.
        action:
          type: string
          nullable: true
          description: Optional action name for tools that require action selection (for example soat and mcp tools).
        input:
          type: object
          nullable: true
          additionalProperties: true
          description: Input payload passed to the tool call.
        output_path:
          type: string
          nullable: true
          description: Optional dot-notation path used to extract a value from the tool output.

    DocumentMessageContent:
      type: object
      required:
        - type
        - document_id
      properties:
        type:
          type: string
          enum:
            - document
        document_id:
          x-soat-ref: documents
          type: string
          description: Public ID of a document to use as the message content.

    SubmitToolOutputsRequest:
      type: object
      required:
        - tool_outputs
      properties:
        tool_outputs:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - tool_call_id
              - output
            properties:
              tool_call_id:
                type: string
                description: ID of the tool call to respond to
              output:
                description: Result of the tool execution

    AgentGenerationResponse:
      type: object
      properties:
        id:
          type: string
          description: Public ID of the generation
          example: gen_V1StGXR8Z5jdHi6B
        status:
          type: string
          enum:
            - completed
            - requires_action
          description: Generation status
        text:
          type: string
          nullable: true
          description: Final text output (when completed)
        object:
          type: object
          nullable: true
          description: Structured object matching the agent's `output_schema` (when completed and `output_schema` is set)
        tool_calls:
          type: array
          nullable: true
          items:
            type: object
            properties:
              tool_call_id:
                type: string
              tool_name:
                type: string
              args:
                type: object
          description: Pending tool calls (when requires_action)

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          oneOf:
            - type: string
              description: Generic error message (e.g. "Unauthorized" or "Internal Server Error")
              example: Unauthorized
            - type: object
              description: Structured domain error
              properties:
                code:
                  type: string
                  example: AI_PROVIDER_ERROR
                message:
                  type: string
                  example: 'Provider returned 402: insufficient credits'
                meta:
                  type: object