HTTP API

The hosted API is the primary way to use kove. It renders your documents in the cloud: zero infra, no Chromium to maintain, and we handle the scale. This is what runs in your app in production, and what your coding agent integrates for you.

You usually do not write against this reference by hand. You point your agent at the OpenAPI spec below and tell it what you need, and it wires the call, the auth, and your data into your app. This page is the reference behind that.

Base URL: https://api.kove.dev
OpenAPI spec: /openapi.json

Authentication

Every product route uses an API key as a Bearer token:

Authorization: Bearer kove_sk_...

Get your key with npx kove login (the browser opens, you sign in with GitHub / Google / email, and the key comes back on its own). See Auth and billing. Without a valid Authorization header you get a 401.

`POST /v1/documents`

Renders a document to PDF. The body is { "document": <kove document> }.

curl -X POST https://api.kove.dev/v1/documents \
  -H "Authorization: Bearer $KOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "footer": { "pageNumbers": "Page {page} of {pages}" },
      "body": [
        { "type": "heading", "text": "Hello, kove" },
        { "type": "text", "text": "My first PDF from the API." }
      ]
    }
  }'

The service validates the document, compiles it, and renders it, then returns the PDF (stored, with its URL). Each successful render counts toward your monthly quota.

If the document does not validate, you get a 400 with the list of errors. This is the same validation the CLI and MCP run, so a document that passes in one passes everywhere.

`GET /v1/account`

Your account status: plan, period usage, limit, and remaining.

curl https://api.kove.dev/v1/account \
  -H "Authorization: Bearer $KOVE_API_KEY"

{ "plan": "free", "usage": 12, "limit": 100, "remaining": 88 }

`POST /v1/checkout`

Creates a Stripe Checkout session to upgrade your plan and returns the URL to open in the browser. The plan activates automatically after payment (via a Stripe webhook). The body takes { "plan": "pro" } (default pro).

curl -X POST https://api.kove.dev/v1/checkout \
  -H "Authorization: Bearer $KOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "pro" }'

{ "checkout_url": "https://checkout.stripe.com/c/pay/..." }

Managing API keys

POST /v1/keys · issues a new API key (requires a login session; the secret is returned only once).
GET /v1/keys · lists your keys (metadata: id, name, created, last used, revoked). Never returns the secret.
DELETE /v1/keys/:id · revokes a key.

From the terminal the easiest way is npx kove keys list and npx kove keys revoke <id>. See CLI.

Errors

The API returns JSON { "error": "..." } with standard HTTP codes:

Code	Meaning	Typical cause
`400`	Invalid document	The document does not match the schema (includes the list of errors).
`401`	Not authenticated	Missing Bearer token, or the API key is invalid or revoked.
`413`	Body too large	The payload is over the size limit (see below).
`429`	Too many requests	You hit the rate limit or used up the period quota.
`500`	Internal error	Something failed on our side (no internals leaked).

Limits

Body size: max 256 KB per request. Above that you get a 413 before we even authenticate. For large images, use https URLs in the image block, not giant embedded data URIs.
Quota: the free tier is 100 documents per month. When you run out you get a 429. Upgrade to Pro with POST /v1/checkout or npx kove upgrade.
Rate limit: there is a per-window request limit to protect the service. If you cross it, you get a 429 with “too many requests, wait a moment”.

For the exact fields of each response, see the OpenAPI spec.