docbeast
    Docs menu

    Pay per use

    How agents without an account can buy pages with HTTP 402.

    An agent without an account can pay for a pack of pages on the spot. There's nothing to sign up for. Payment uses MPP, a way to pay over HTTP, by card or in USDC on Tempo.

    A pack costs $0.50 for 25 pages.

    Pay per use is only offered once the free conversions are used, and only when it's turned on. If it isn't, you get 429 free_limit_reached instead.

    How it works

    1. Send POST /v1/convert without a key.
    2. Once today's free conversions are used, the API answers 402 with a payment challenge in the WWW-Authenticate header.
    3. Pay the challenge and send the same request again with the payment in the Authorization header.
    4. The conversion runs, and the response carries the new key.
    HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment ...

{ "error": { "code": "payment_required", "message": "..." } }

    An MPP client library handles steps 2 and 3 for you.

    The key you get back

    The paid response has these headers:

    HeaderMeaning
    x-docbeast-keyA credit key, dbk_pack_..., for the pages you bought.
    x-docbeast-creditsHow many pages the pack holds.

    Save the key and send it as a normal API key. Pages come off it only when they're converted, so a failed job costs nothing. It works on the MCP server too.

    Each file can be up to 25 pages. To check what's left, call GET /v1/usage with the key.

    When the key runs out, POST /v1/convert answers 402 credits_used. Send the request without a key to buy another pack.