API Reference
Two ways in: read the auto-generated OpenAPI spec for every endpoint, or jump into the conceptual guides for auth, idempotency, pagination, webhooks, and errors.
Pick a version
/api/v2
CurrentRun research jobs and read their results. Pin the effort tier or expert, list past jobs, fetch the rendered report and the files it produced, and check your credit balance before each call.
Browse v2 reference/api/v1
DeprecatedThe original /api/v1/research surface. Existing integrations continue to work; new integrations should target v2.
Read migration noteCall Grep as a research agent.
A2A clients can discover Grep through an Agent Card, start research tasks over JSON-RPC, stream status, cancel runs, and continue from completed research.
Concepts
Cross-cutting guides covering the parts of the API that are easier to understand by topic than by endpoint.
Quickstart
Make your first call in under five minutes — auth setup, create-and-poll, full Python example.
Authentication
Bearer tokens, capability mode for public job reads, and the difference between 401 and 403.
Idempotency
Safely retry POST /research without creating duplicate work. Replay semantics, body-hash matching, TTL.
Pagination
Cursor-based pagination on /research and /billing/transactions. Why keyset over offset.
Webhooks
Register webhooks, verify HMAC signatures, correlate v2 request IDs, retry policy.
Errors
The structured error envelope and the full code registry — including 402 vs 429.
Five-minute quickstart
Create a job, poll for completion. Both shapes shown side-by-side — see the full quickstart for optional idempotency, webhooks, and error handling.
cURL
curl -X POST "https://api.grep.ai/api/v2/research" \
-H "Authorization: Bearer $GREP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "Due diligence on Stripe Inc",
"effort": "medium"
}'Python
import os, httpx
r = httpx.post(
"https://api.grep.ai/api/v2/research",
headers={"Authorization": f"Bearer {os.environ['GREP_API_KEY']}"},
json={"question": "Due diligence on Stripe Inc", "effort": "medium"},
)
print(r.json()["job_id"])