KeepBal Tools API

openapi: 3.2.0
info:
  title: KeepBal Tools 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: Tools
  description: Tool / data APIs (`/apis/v1`). Billed per successful call.
paths:
  /mcp:
    post:
      tags:
      - Tools
      summary: KeepBal MCP server (Streamable HTTP, JSON-RPC 2.0)
      description: Initialize, ping and list the four meta-tools anonymously. All tools/call requests require a bearer key. Search and inspect are free; run uses REST billing and polls up to 25 seconds. get_run checks and settles an existing run without a new execution or polling fee. Do not retry paid truncated or unsupported results. Supports protocol versions 2025-06-18 and 2025-03-26, single requests only, no sessions or SSE. Accept may be omitted; when supplied it must include application/json or text/event-stream. Responses are JSON in either case. MCP-Protocol-Version is optional; unsupported header versions are rejected, while initialize negotiates a supported version. Accepted-run poll errors retain run_id and unresolved billing; resume with get_run. Known terminal receipts retain their settled charge, including zero-charge failures.
      security:
      - {}
      - bearerAuth: []
      parameters:
      - name: Accept
        in: header
        schema:
          type: string
        description: Include application/json or text/event-stream when supplied. Replies use application/json.
      - name: MCP-Protocol-Version
        in: header
        schema:
          type: string
          enum:
          - '2025-06-18'
          - '2025-03-26'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: JSON-RPC result or error; tool failures can be results with isError=true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '202':
          description: Notification accepted (empty body)
        '400':
          $ref: '#/components/responses/McpError'
        '401':
          $ref: '#/components/responses/McpError'
        '403':
          $ref: '#/components/responses/McpError'
        '406':
          $ref: '#/components/responses/McpError'
        '413':
          $ref: '#/components/responses/McpError'
        '415':
          $ref: '#/components/responses/McpError'
      operationId: postMcp
      x-operation-id-source: derived
    get:
      tags:
      - Tools
      security: []
      summary: MCP setup for HTML clients; SSE is not supported
      responses:
        '200':
          description: HTML setup page when Accept includes text/html
        '405':
          description: Use POST for MCP messages
        '403':
          $ref: '#/components/responses/McpError'
      operationId: getMcp
      x-operation-id-source: derived
  /apis/v1/:
    get:
      tags:
      - Tools
      summary: List tool APIs with KeepBal prices
      responses:
        '200':
          description: List
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getApisV1
      x-operation-id-source: derived
  /apis/v1/tavily/search:
    post:
      tags:
      - Tools
      summary: Web search with extracted page text (Tavily)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                max_results:
                  type: integer
                search_depth:
                  type: string
                  enum:
                  - basic
                  - advanced
              additionalProperties: true
      responses:
        '200':
          description: Search results (provider shape)
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1TavilySearch
      x-operation-id-source: derived
  /apis/v1/tavily/extract:
    post:
      tags:
      - Tools
      summary: Extract content from URLs (Tavily)
      responses:
        '200':
          description: Extracted content
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1TavilyExtract
      x-operation-id-source: derived
  /apis/v1/exa/search:
    post:
      tags:
      - Tools
      summary: Neural web search (Exa)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
              additionalProperties: true
      responses:
        '200':
          description: Results
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      operationId: postApisV1ExaSearch
      x-operation-id-source: derived
  /apis/v1/exa/contents:
    post:
      tags:
      - Tools
      summary: Fetch page contents (Exa)
      responses:
        '200':
          description: Contents
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
      operationId: postApisV1ExaContents
      x-operation-id-source: derived
  /apis/v1/firecrawl/scrape:
    post:
      tags:
      - Tools
      summary: Scrape a page to markdown (Firecrawl)
      responses:
        '200':
          description: Scrape
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1FirecrawlScrape
      x-operation-id-source: derived
  /apis/v1/firecrawl/search:
    post:
      tags:
      - Tools
      summary: Search + scrape (Firecrawl)
      responses:
        '200':
          description: Results
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1FirecrawlSearch
      x-operation-id-source: derived
  /apis/v1/scholar/search/scholar:
    post:
      tags:
      - Tools
      summary: Academic paper search (Scholar)
      responses:
        '200':
          description: Papers
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1ScholarSearchScholar
      x-operation-id-source: derived
  /apis/v1/scholar/search/web:
    post:
      tags:
      - Tools
      summary: Research-oriented web search (Scholar)
      responses:
        '200':
          description: Results
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1ScholarSearchWeb
      x-operation-id-source: derived
  /apis/v1/{provider}/{operation}:
    post:
      tags:
      - Tools
      summary: Execute a public tool; unavailable routes return 503 and are not billed
      description: 'Append the exact publicId from discover to /apis/v1/. The provider/operation parameters represent the public namespace and operation, not a private provider mapping; operation may include additional path segments.

        Send an input object using body, queryParams and pathParams, or the flat JSON body documented by inspect. Query values are scalar; templated path values occupy one segment. Catalog caps can be sent as max_cost_usd in the top-level JSON body, URL query, or X-KeepBal-Max-Cost-USD header. Conflicting caps are rejected.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ToolInput'
              - type: object
                additionalProperties: true
            example:
              body:
                urls:
                - https://example.com
              max_cost_usd: 0.1
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
      - name: operation
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/SpendCapHeader'
      - name: max_cost_usd
        in: query
        schema:
          $ref: '#/components/schemas/SpendCap'
      responses:
        '200':
          description: Provider data, sanitized receipt or a supported download; content type varies
        '202':
          description: Pending run; poll its run ID without starting a second execution
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          description: Unknown public tool
        '503':
          $ref: '#/components/responses/ProviderUnavailable'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: postApisV1ByProviderByOperation
      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]+)?$
    JsonRpcError:
      type: object
      required:
      - jsonrpc
      - id
      - error
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          type:
          - string
          - number
          - 'null'
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: integer
            message:
              type: string
            data: {}
          additionalProperties: true
      additionalProperties: false
    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.
    JsonRpcResponse:
      oneOf:
      - type: object
        required:
        - jsonrpc
        - id
        - result
        properties:
          jsonrpc:
            type: string
            const: '2.0'
          id:
            type:
            - string
            - number
            - 'null'
          result:
            type: object
            additionalProperties: true
        additionalProperties: false
      - $ref: '#/components/schemas/JsonRpcError'
  responses:
    Unauthorized:
      description: Missing/invalid/revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    McpError:
      description: JSON-RPC transport error (invalid input/version 400, authentication 401/403, origin 403, Accept 406, body over 1 MiB 413, or content type 415)
      headers:
        WWW-Authenticate:
          schema:
            type: string
        Retry-After:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonRpcError'
    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_...