Getting Started

Authentication

All HyperAPI requests are authenticated with an API key passed in the X-API-Key request header.

API key types

hk_live_

Production

Used for live API calls. Billed to your account. Store securely — never expose in client-side code.

hk_test_

Test mode (admin-issued)

Hit the same models as live keys, but bypass the live rate-limit ceiling (1,000 req/min) and skip billing entirely — no charges, no row in usage exports. Admin-issued only: contact your platform admin to obtain one. Useful for CI smoke tests and engaged-customer integration work.

Generate hk_live_ keys from your API Keys dashboard. hk_test_ keys are admin-issued — the Live/Test selector is visible only to platform admins.

Using your API key

Pass your key in the X-API-Key header on every request.

curl -X POST https://apis.hyperbots.com/v1/parse \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@invoice.pdf"

curl -X POST https://apis.hyperbots.com/v1/parse \
  -H "X-API-Key: hk_live_your_key_here" \
  -F "file=@invoice.pdf"

Key scope

API keys are organization-scoped — not user- or key-scoped. Any active key in your organization can access your organization's resources, including results created in the Playground. A Playground job is owned by your org (not by any one key), so retrieving it with GET /v1/jobs/{job_id} works with any of your org's keys — retrieval checks only that the key's organization matches the job's, not which key (or the Playground session) submitted it.

Separate keys are for credential management — independent revocation, per-key rate tiers, and per-key attribution in your Usage logs — not for isolating data between keys. For a hard data boundary between teams, use separate organizations.

Security best practices

Protect your API keys

—Store keys in environment variables — never hardcode them in source.
—Never expose hk_live_ keys in client-side JavaScript or public repositories.
—Rotate keys immediately if you suspect compromise.
—For CI/CD that shouldn't consume billable usage, ask your platform admin for an hk_test_ key (admin-issued, 1,000 req/min, no billing).
—Create separate keys per environment (dev, staging, production).