# Grep API v2 Programmatic access to Grep — kick off research jobs, fetch their reports and files, and check your credit balance. All endpoints accept either a UUID or a slug for ``{job_id_or_slug}``. ## Authentication Use a bearer token in the `Authorization` header. ```http Authorization: Bearer $GREP_API_KEY ``` ## OpenAPI - [OpenAPI v2 JSON](https://grep.ai/openapi/v2.json) ## Endpoints ### POST /api/v2/a2a A2A Jsonrpc A2A JSON-RPC endpoint for Grep research tasks. Tags: Agent-to-Agent ### POST /api/v2/attachments Create Research Attachment Upload files and receive an ``attachment_id`` for ``POST /research``. The upload is independent of any job. Pass the returned ``attachment_id`` in ``attachment_ids`` when creating research and the server will copy these files into that job's ``./input_files/``. Tags: Attachments ### DELETE /api/v2/attachments/\{attachment\_id\} Delete Research Attachment Delete an attachment so it cannot be used by future jobs. Tags: Attachments ### GET /api/v2/attachments/\{attachment\_id\} Get Research Attachment Return attachment metadata for the authenticated owner. Tags: Attachments ### GET /api/v2/billing/transactions Get Billing Transactions List the caller's wallet transactions, newest first. Cursor-paginated. Each entry has the transaction type (``deposit``, ``consumption``, ``bonus``, ``refund``, ``expiration``, ``auto_topup``), credit amount, balance after, optional ``job_id`` for consumption tied to a research job, and Stripe metadata for paid deposits. Tags: Billing ### GET /api/v2/billing/usage Get Billing Usage Aggregate credit spend over the requested period. Returns total credits used, dollars spent (paid credits only — bonus credits are excluded from the cents fields), per-effort breakdown, and a projection of where the period will end at current burn rate. Defaults to the current billing period; pass ``period=last_30d`` for a rolling 30-day window or ``period=custom`` with ``from`` + ``to`` for an explicit range. Tags: Billing ### GET /api/v2/experts List public research experts Returns the canonical list of public research experts that v2 and the MPP gateway both accept on the ``expert_id`` field. Use this to pick an ``expert_id`` for ``POST /api/v2/research``. Public — no auth required. Tags: Experts ### GET /api/v2/quota Get Quota Current quota for the authenticated caller. Returns the caller's subscription tier, remaining credits, and the cost in credits of each effort tier. To answer "will my next call succeed?", compare ``credits_remaining`` against ``credits_required_for_effort[ ]`` — or use ``GET /quota/check?effort= `` for the same check in one call. Tags: Billing ### GET /api/v2/quota/check Check Quota Non-consuming quota check for a specific effort tier. Returns whether the caller has enough credits to run ``POST /research`` at the requested ``effort`` without actually starting a job. Use this to gate UX (disable a "Run" button when the response says ``allowed=false``) instead of catching a 402 after submitting. Tags: Billing ### GET /api/v2/research List Research Jobs List the caller's research jobs, newest first. Cursor-paginated. Each row carries the minimum needed to render a list and link to the detail view: ``job_id``, ``slug``, ``status``, ``question``, ``effort``, and timestamps. Use ``GET /research/{job_id_or_slug}`` to fetch the full job — including the rendered report and revision history — for any row you want to inspect. Tags: Research ### POST /api/v2/research Create Research Job Start a research job. Tags: Research ### GET /api/v2/research/\{job\_id\_or\_slug\} Get Research Job With Auth Context Fetch a single research job by UUID or slug. Returns identity, lifecycle status, original request echo, timing metadata, the rendered Markdown report (for completed jobs), and the list of published revisions. The path parameter accepts either a UUID or a human-readable slug. Pass ``?revision= `` to read the report at a specific commit; otherwise the latest report is returned. Tags: Research ### POST /api/v2/research/\{job\_id\_or\_slug\}/cancel Cancel Research Job Endpoint Cancel a queued or running research job. Cancellation is terminal. The job status becomes ``cancelled`` and running check results are marked ``interrupted``. Repeating the call for a terminal job is safe and returns the current terminal status. Tags: Research ### POST /api/v2/research/\{job\_id\_or\_slug\}/continue Continue Research Job Endpoint Continue a completed research job in place. Only successfully completed jobs can be continued. Active, paused, failed, locked, and cancelled jobs return ``409`` with a stable machine-readable error code. REST keeps the same Grep job id/slug and adds a new continuation check result. A2A uses this same service but returns the continuation check result as a new A2A task id so terminal A2A tasks are not restarted. Tags: Research ### GET /api/v2/research/\{job\_id\_or\_slug\}/files List Research Files List files in a research job's workspace. Returns every file the agent produced or modified during the run, with sizes, MIME types, and last-commit timestamps. Use ``GET /research/{job_id_or_slug}/files/{file_path}`` to download individual file contents. Tags: Research ### GET /api/v2/research/\{job\_id\_or\_slug\}/files/\{file\_path\} Read Research File Download a single file from a research job's workspace. Returns the raw file bytes with a matching ``Content-Type`` header. ``file_path`` is the slash-separated path from any entry in the ``GET /research/{job_id_or_slug}/files`` listing. Tags: Research ### GET /api/v2/research/\{job\_id\_or\_slug\}/timeline Get Research Timeline With Auth Context Paginated, recent-first execution timeline for a research job. Returns the events the agent emitted while working on the job — tool calls, sub-agent progress, thinking traces, text outputs. Newest first; walk older pages with the returned ``next_cursor``. Each event is a flat projection of the internal status-message log (see ``TimelineEvent``). The full SDK content shape is intentionally not exposed; secrets, raw shell commands, and cost/token fields are stripped or redacted before the response is built. Use this to drive a "what's the agent doing right now?" UI by polling every few seconds while ``status`` is ``in_progress``. Tags: Research