KeepBal Pay Per Request API

openapi: 3.2.0
info:
  title: KeepBal Pay Per Request 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: pay-per-request
  description: Pay-per-request surface (`/apis/v2`). Not implemented yet.
paths:
  /apis/v2/{path}:
    post:
      tags:
      - pay-per-request
      security: []
      summary: Pay-per-request (planned)
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
      responses:
        '501':
          description: Not implemented yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: postApisV2ByPath
      x-operation-id-source: derived
components:
  schemas:
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: dgk_live_...