KeepBal Operations API

openapi: 3.2.0
info:
  title: KeepBal Operations API
  version: 0.1.0
  summary: One key and one prepaid wallet for agent tools.
  description: 'Hosted MCP: https://keepbal.com/mcp (Streamable HTTP, bearer key). Setup: https://keepbal.com/docs/mcp.

    Search for a tool, inspect its price, and run it with a KeepBal key.

    Tool search status: live. Model inference status: live.

    Read /catalog.json for status and available on each model, tool, and operation.

    Signup includes $1 free credit, once. Top up $10, $20, $50, or $100 in Console Wallet with Paddle.

    Top-up fee: 8% of the credit, rounded up to the cent, + $0.35 before tax.

    Only the credit amount is added to your wallet. No subscription.

    Fixed tools show the per-call price; variable tools bill provider price plus 35%. Inspect returns pricing metadata, not a quote.

    Fixed tools charge the published per-call price. Variable tools charge the provider''s reported actual cost plus the disclosed markup (currently 35%). Missing actual cost on variable tools charges $0. Quotes are estimates, labelled estimated_price; completed price is the settlement debit. Failed, blocked, or timed-out runs cost $0.

    Charges settle after calls. Daily limits are not available. Catalog calls support max_cost_usd spending caps.

    Model charges require returned token usage. Chat Completions, Responses and Messages support SSE on configured live routes. Catalog streams may be buffered until usage settlement is durable. Embeddings do not stream. Image pricing is not implemented.

    MCP is live via Streamable HTTP; A2A transport is not live. Request formats and current availability: /llms.txt and /SKILL.md.

    KeepBal errors use the OpenAI error format. Upstream error bodies may differ.

    Authenticate protected requests with Authorization: Bearer dgk_live_...

    KeepBal error envelope: {"error":{"message","type","code","param","request_id"}}.

    A 503 provider_unavailable is never billed.

    Use x-keepbal-request-id and x-keepbal-cost-micros when present. Catalog responses omit private routing and provider-mode headers.

    Streaming responses have no final cost header; check Usage after the call is recorded.

    Approximate x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, and retry-after headers are exposed to browsers.

    Primary public host: https://keepbal.com. See /llms-full.txt for the technical reference.'
  contact:
    name: KeepBal
    url: https://keepbal.com
    email: hello@keepbal.com
servers:
- url: https://keepbal.com
  description: KeepBal (canonical public origin)
security:
- bearerAuth: []
tags:
- name: Operations
  description: Tool discovery, input/pricing metadata, runs, and run history.
paths:
  /apis/v1/discover:
    post:
      tags:
      - Operations
      summary: Find a tool (free operation)
      description: Check the tool search status in /catalog.json. Unavailable routes return 503 and are not billed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  minLength: 2
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 20
                offset:
                  type: integer
                  minimum: 0
                  default: 0
      responses:
        '200':
          description: Local catalog matches; publicId is the opaque tool identifier, and status/available indicate callability.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                - total
                - limit
                - offset
                - has_more
                properties:
                  object:
                    type: string
                    const: list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        publicId:
                          type: string
                        path:
                          type: string
                        status:
                          type: string
                        available:
                          type: boolean
                      additionalProperties: true
                  total:
                    type: integer
                  limit:
                    type: integer
                    minimum: 1
                    maximum: 100
                  offset:
                    type: integer
                    minimum: 0
                  has_more:
                    type: boolean
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1Discover
      x-operation-id-source: derived
  /apis/v1/inspect:
    post:
      tags:
      - Operations
      summary: Inspect inputs and pricing metadata (free operation)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - publicId
              properties:
                publicId:
                  type: string
                  description: Public tool ID returned by discovery
      responses:
        '200':
          description: Public tool and pricing metadata with input.pathParams/queryParams/body when known; input_schema_available=false otherwise. This is not an input-specific price quote.
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown public tool
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1Inspect
      x-operation-id-source: derived
  /apis/v1/run:
    post:
      tags:
      - Operations
      summary: Run a public tool at its catalog pricing
      parameters:
      - $ref: '#/components/parameters/SpendCapHeader'
      description: 'Fixed tools show the per-call price; variable tools bill provider price plus 35%. Inspect returns pricing metadata, not a quote.

        Fixed tools charge the published per-call price. Variable tools charge the provider''s reported actual cost plus the disclosed markup (currently 35%). Missing actual cost on variable tools charges $0. Quotes are estimates, labelled estimated_price; completed price is the settlement debit. Failed, blocked, or timed-out runs cost $0.

        Pass publicId unchanged from discover. Place provider inputs in input.body, input.queryParams or input.pathParams as described by inspect.

        Set top-level max_cost_usd or X-KeepBal-Max-Cost-USD to cap supported catalog executions. A cap must cover the estimate and requires sufficient balance; conflicting caps are rejected. Some variable tools require a cap or quantity.

        Async runs return 202; poll GET /apis/v1/runs/{runId}. Each successful run is charged once. Provider data and sanitized run receipts vary by tool; price is the settled USD charge, estimated_price is an estimate, and charged/billing_pending describe settlement. Pending billing is not a reason to execute again.'
      x-keepbal:
        price_micros: null
        pricing:
          type: variable
          description: 'Variable: provider price plus 35%'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - publicId
              properties:
                publicId:
                  type: string
                  description: Public tool ID returned by discovery
                input:
                  $ref: '#/components/schemas/ToolInput'
                max_cost_usd:
                  $ref: '#/components/schemas/SpendCap'
      responses:
        '200':
          description: Provider data or a sanitized run receipt; x-keepbal-cost-micros reports the charge when present
        '202':
          description: Pending run receipt with run ID; poll the existing run for settlement
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown public tool or run
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: postApisV1Run
      x-operation-id-source: derived
  /apis/v1/runs:
    get:
      tags:
      - Operations
      summary: List runs (free operation)
      responses:
        '200':
          description: Run list
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getApisV1Runs
      x-operation-id-source: derived
  /apis/v1/runs/{runId}:
    get:
      tags:
      - Operations
      summary: Check a run (variable price for an unpaid successful result)
      description: 'Checking an unpaid successful run records its charge once. No separate polling fee.

        Fixed tools charge the published per-call price. Variable tools charge the provider''s reported actual cost plus the disclosed markup (currently 35%). Missing actual cost on variable tools charges $0. Quotes are estimates, labelled estimated_price; completed price is the settlement debit. Failed, blocked, or timed-out runs cost $0.'
      x-keepbal:
        price_micros: null
        pricing:
          type: variable
          description: 'Variable: provider price plus 35%'
      parameters:
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Run
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getApisV1RunsByRunId
      x-operation-id-source: derived
  /apis/v1/runs/{runId}/stop:
    post:
      tags:
      - Operations
      summary: Request stop (free operation)
      parameters:
      - name: runId
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Stopping
        '409':
          description: Already terminal
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1RunsByRunIdStop
      x-operation-id-source: derived
components:
  schemas:
    ToolInput:
      type: object
      description: Public tool input buckets. Inspect the tool for required fields and examples. Nested query values are rejected.
      properties:
        body:
          type: object
          additionalProperties: true
        queryParams:
          type: object
          additionalProperties:
            type:
            - string
            - number
            - boolean
            - 'null'
        pathParams:
          type: object
          additionalProperties:
            type:
            - string
            - number
        max_cost_usd:
          $ref: '#/components/schemas/SpendCap'
      additionalProperties: false
    SpendCap:
      description: Positive USD amount or decimal string. Sub-micro precision is truncated; the effective cap must be a positive safe integer in micro-USD, cover estimated cost, and fit the wallet reservation.
      oneOf:
      - type: number
        minimum: 1.0e-06
      - type: string
        pattern: ^[0-9]+(\.[0-9]*)?([eE][+-]?[0-9]+)?$
    Error:
      type: object
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
              enum:
              - unauthorized
              - account_exists
              - invalid_api_key
              - missing_api_key
              - key_revoked
              - scope_denied
              - insufficient_credits
              - rate_limited
              - invalid_request
              - model_not_found
              - not_found
              - method_not_allowed
              - not_implemented
              - provider_unavailable
              - upstream_error
              - console_disabled
              - forbidden
              - internal_error
            param:
              type:
              - string
              - 'null'
            request_id:
              type: string
              description: Same value as the x-keepbal-request-id response header.
  responses:
    Unauthorized:
      description: Missing/invalid/revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientCredits:
      description: Wallet below the minimum balance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ProviderUnavailable:
      description: No upstream configured for this route. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: API key scope denied or account access suspended
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key requests/minute exceeded (`retry-after` plus `x-ratelimit-*` headers)
      headers:
        retry-after:
          schema:
            type: integer
        x-ratelimit-limit:
          schema:
            type: integer
        x-ratelimit-remaining:
          schema:
            type: integer
        x-ratelimit-reset:
          schema:
            type: integer
          description: Unix seconds when the current minute window ends
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: Invalid input, missing required parameters, or an invalid/conflicting spend cap
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    SpendCapHeader:
      name: X-KeepBal-Max-Cost-USD
      in: header
      description: Catalog execution spending cap. Multiple supplied caps must agree after conversion to micro-USD.
      schema:
        $ref: '#/components/schemas/SpendCap'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: dgk_live_...