# API - Grep Developers

[Developers](/developers)API Reference

# 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](/developers/api/v2)

[Current](/developers/api/v2)

[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.](/developers/api/v2)

[Browse v2 reference](/developers/api/v2)

### [/api/v1](/developers/api/v1)

[Deprecated](/developers/api/v1)

[The original /api/v1/research surface. Existing integrations continue to work; new integrations should target v2.](/developers/api/v1)

[Read migration note](/developers/api/v1)

Agent2Agent

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

[Agent Card](/.well-known/agent-card.json)[A2A docs](/developers/a2a)[Markdown](/developers/a2a.md)

## Concepts

Cross-cutting guides covering the parts of the API that are easier to understand by topic than by endpoint.

### [Quickstart](/developers/api/quickstart)

[Make your first call in under five minutes — auth setup, create-and-poll, full Python example.](/developers/api/quickstart)

### [Authentication](/developers/api/auth)

[Bearer tokens, capability mode for public job reads, and the difference between 401 and 403.](/developers/api/auth)

### [Idempotency](/developers/api/idempotency)

[Safely retry POST /research without creating duplicate work. Replay semantics, body-hash matching, TTL.](/developers/api/idempotency)

### [Pagination](/developers/api/pagination)

[Cursor-based pagination on /research and /billing/transactions. Why keyset over offset.](/developers/api/pagination)

### [Webhooks](/developers/api/webhooks)

[Register webhooks, verify HMAC signatures, correlate v2 request IDs, retry policy.](/developers/api/webhooks)

### [Errors](/developers/api/errors)

[The structured error envelope and the full code registry — including 402 vs 429.](/developers/api/errors)

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

```
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

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"])
```

[Read the full quickstart](/developers/api/quickstart)