Quickstart
Make your first call to the v2 API in under five minutes. Auth, create-and-poll, full Python example.
1. Get an API key
Mint an API key from /developers/keys. Keys follow the format parcha-xyz-{32_hex}. Store it as an environment variable — never commit it to source.
Auth guide →2. Create a job
POST to /api/v2/research with your question. For production retry loops, add an Idempotency-Key header.
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"
}'The response returns immediately with a job_id and a status of queued or running:
json
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"created_at": "2026-04-27T10:30:00Z"
}3. Poll for completion
GET /api/v2/research/{job_id} until status is completed, complete, failed, blocked, or cancelled. Or register a webhook_url on creation to skip polling entirely.
curl
curl "https://api.grep.ai/api/v2/research/$JOB_ID" \
-H "Authorization: Bearer $GREP_API_KEY"Full Python example
End-to-end script: create, poll every two seconds, return the report when the job terminates.
python
import os
import time
import httpx
API_KEY = os.environ["GREP_API_KEY"]
BASE = "https://api.grep.ai/api/v2"
def run_research(question: str) -> dict:
headers = {"Authorization": f"Bearer {API_KEY}"}
create = httpx.post(
f"{BASE}/research",
json={"question": question, "effort": "medium"},
headers=headers,
timeout=30,
)
create.raise_for_status()
job_id = create.json()["job_id"]
while True:
poll = httpx.get(
f"{BASE}/research/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
poll.raise_for_status()
body = poll.json()
if body["status"] in ("completed", "complete", "failed", "blocked", "cancelled"):
return body
time.sleep(2)
result = run_research("Due diligence on Stripe Inc")
print(result.get("report", {}).get("markdown", ""))