Pick a version
Run 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. The original /api/v1/research surface. Existing integrations continue to work; new integrations should target v2.
- /api/v2CurrentRun 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/v1DeprecatedThe original /api/v1/research surface. Existing integrations continue to work; new integrations should target v2.Read migration note
Call GREP AI 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. Make your first call in under five minutes — auth setup, create-and-poll, full Python example. Bearer tokens, capability mode for public job reads, and the difference between 401 and 403. Safely retry POST /research without creating duplicate work. Replay semantics, body-hash matching, TTL. Cursor-based pagination on /research and /billing/transactions. Why keyset over offset. Register webhooks, verify HMAC signatures, correlate v2 request IDs, retry policy. The structured error envelope and the full code registry — including 402 vs 429.
- QuickstartMake your first call in under five minutes — auth setup, create-and-poll, full Python example.
- AuthenticationBearer tokens, capability mode for public job reads, and the difference between 401 and 403.
- IdempotencySafely retry POST /research without creating duplicate work. Replay semantics, body-hash matching, TTL.
- PaginationCursor-based pagination on /research and /billing/transactions. Why keyset over offset.
- WebhooksRegister webhooks, verify HMAC signatures, correlate v2 request IDs, retry policy.
- ErrorsThe 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.
bash
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"
}'bash
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"])