API Authentication

Mint an API key

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 →

Bearer token

Send the key in the Authorization header on every request. Format: parcha-xyz-{32_hex}.

curl

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

Keep your API key secure

Never expose your API key in client-side code. Use server-side requests, environment variables, or a secrets manager.

OAuth2 for agents

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

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

Protected resource

https://api.grep.ai/api/v2

Discovery

bash

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

Scope	Access
`research:read`	Read research jobs, reports, files, timelines, quota, and usage.
`research:write`	Start research and manage research attachments.
`billing:read`	Reserved for stricter billing reads as the billing surface grows.

Capability mode (public jobs)

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.

bash

# 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.

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.

401 vs 403

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

Status	Code	Meaning
`401`	`unauthenticated`	Your key is missing, malformed, or revoked. Don't retry without fixing the credential.
`403`	`forbidden`	Your key is valid but lacks permission for this resource. Often a tenant-mismatch — the job belongs to another tenant.

Error codes

Full registry of error codes and the structured error envelope.

API v2 reference

Browse every endpoint and schema in the auto-generated reference.

Authentication