Skip to main content
Every /v1 request is identified as exactly one of three callers. The same route handlers serve all three — a subscriber integrating server-to-server, a signed-in user browsing pocketutils.com, and a signed-out visitor trying a tool page — so the endpoint you test in a browser is byte-for-byte the one your integration calls. PocketUtils resolves the caller in that order: a request with a valid API key is always treated as an API-key caller, even if it also happens to carry a session cookie.

​
API keys

API keys are the intended way to call PocketUtils from your own backend. A key starts with pu_live_ followed by a random string, e.g. pu_live_a1b2c3....
Every code example in this documentation uses YOUR_API_KEY as a placeholder. Grab your real key from the dashboard and swap it in to run the requests yourself.
Send it in either header — they’re equivalent:
A key’s plaintext is shown exactly once, in the response to the request that created it. PocketUtils stores only its SHA-256 hash, so if you lose it there is no way to recover it — revoke the key and create a new one.

​
Creating a key

Keys are created and managed from your dashboard, not through the public API. Creating one requires a paid plan — the Free plan is the tool-page browsing allowance only, and never gets programmatic access:

​
Invalid or revoked keys

An API key that is malformed, unknown, or revoked is a hard failure — 401 invalid_api_key — rather than a silent fallback to the anonymous tier. If you’re integrating against the API, you want to know immediately that your credential is wrong, not discover it later as an unexplained 429.

​
Session cookies

When you’re signed in on pocketutils.com, the tool pages call the same /v1 endpoints using your browser session instead of a key. This path is locked to the pocketutils.com origin with credentialed CORS — it isn’t meant for third-party integrations, only for the website itself. If you’re building an integration, use an API key.

​
Anonymous access

No credential at all is a valid, supported way to call every endpoint — it’s what powers trying a tool without signing up. Anonymous requests are tracked by a salted hash of the caller’s IP address (raw IPs are never stored) and get:
  • 10 credits per day
  • 10 requests per minute
This is intentionally small: enough to try a couple of light endpoints, not to run an integration on. Signing in raises your allowance to the Free plan’s 100 credits/month; a paid plan raises it further and unlocks API keys.

​
Choosing a caller type

Rate Limits & Credits

Full plan comparison and credit costs per endpoint.

Errors

Every authentication-related error code.

Related topics

QuickstartErrorsIntroductionRate Limits & Credits