Authentication

Generate an API key from /developers/keys. Keys follow the format parcha-xyz-{32_hex} and are tied to your tenant. Treat them like passwords.

• Open API keys

Send the key in the Authorization header on every request. Format: parcha-xyz-{32_hex}. Keep your API key secure Never expose your API key in client-side code. Use server-side requests, environment variables, or a secrets manager.

curl "https://api.grep.ai/api/v2/research" \
  -H "Authorization: Bearer parcha-xyz-1234567890abcdef..."

Agent and delegated integrations can use Descope-issued OAuth access tokens minted for the Grep Public API v2 resource. API keys are still supported for direct server-to-server integrations.

curl "https://api.grep.ai/api/v2/research" \
  -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN"

curl "https://api.grep.ai/.well-known/oauth-protected-resource/api/v2"
curl "https://api.grep.ai/.well-known/api-catalog"

When a job is shared publicly, the job_id itself acts as a read capability. No Authorization header is needed for GET /api/v2/research/{public_job_id}. This is what powers public share links — anyone with the URL can read, but nobody can mutate. Read-only capability Capability mode is read-only. POST/PATCH/DELETE always require an API key. Capability access is silently skipped if the job's visibility is private.

# Capability mode — public job, read-only access via the job_id itself.
curl "https://api.grep.ai/api/v2/research/$PUBLIC_JOB_ID"
# No Authorization header required when the job is shared publicly.

Both indicate auth failure but mean different things — distinguishing them helps you write better retry logic.

Full registry of error codes and the structured error envelope. Browse every endpoint and schema in the auto-generated reference.

• Error codesFull registry of error codes and the structured error envelope.
• API v2 referenceBrowse every endpoint and schema in the auto-generated reference.