API keys and limits

Everything in protogrid works without a key. A key raises your limits and shows your usage; it never unlocks different data.

Limits

	Rate	Daily	Keys
Anonymous	20 requests per minute per IP address	none	none
Free account	60 requests per minute	5,000 requests per UTC day	1 active key

Account limits are shared by all your keys; a key only identifies the integration. Every HTTP request with a key counts once, whether it is a REST call or an MCP message (including initialize and tools/list, which standard clients send when they connect).

Get a key

Sign in with GitHub at protogrid.dev/account and create a key. The full key (pgk_…) is shown once; protogrid stores only a hash. If you lose it, revoke it on the same page and create another. The account page also shows today’s use of the daily quota and the last 30 days per operation.

Send it

Use X-API-Key: pgk_… or Authorization: Bearer pgk_…. Keep the key in an environment variable; the examples use PROTOGRID_API_KEY.

curl -H "X-API-Key: $PROTOGRID_API_KEY" 'https://api.protogrid.dev/v1/search?q=send+an+email'

Claude Code:

claude mcp add --transport http -s user protogrid https://api.protogrid.dev/mcp --header "X-API-Key: $PROTOGRID_API_KEY"

Codex (~/.codex/config.toml):

[mcp_servers.protogrid]
url = "https://api.protogrid.dev/mcp"
env_http_headers = { "X-API-Key" = "PROTOGRID_API_KEY" }

OpenCode (opencode.json):

{ "mcp": { "protogrid": { "type": "remote", "url": "https://api.protogrid.dev/mcp", "enabled": true, "headers": { "X-API-Key": "{env:PROTOGRID_API_KEY}" } } } }

The TypeScript and Python SDKs read PROTOGRID_API_KEY by themselves; pass apiKey / api_key to override it, or an empty string to send none.

Responses

Keyed responses carry:

header	meaning
x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset	the per-minute window for your account
x-quota-limit, x-quota-remaining	the daily quota for your account
cache-control: private, no-store	keyed calls are never served from a shared cache

Errors:

status	error	what to do
401	invalid_api_key	the key is malformed, unknown or revoked; a bad key never falls back to anonymous access
429	(rate limit)	wait retry-after seconds
429	daily_quota_exceeded	the quota resets at 00:00 UTC; retry-after is the seconds until then

A bearer token that does not start with pgk_ is not a protogrid key and is ignored, so a proxy’s own token does not break anonymous access.