# 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

### GET /api/v2/agents

List public agents

Alias of ``GET /api/v2/experts``. Returns the canonical list of public agents that v2 and the MPP gateway both accept on the ``expert_id`` field. Public — no auth required.

Tags: Experts

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

### POST /api/v2/attachments/import

Create an attachment from a URL

JSON alternative to the multipart upload: the server fetches `source_url` (public http(s) only — private, loopback, link-local/cloud-metadata, and reserved addresses are blocked, redirects re-validated per hop, size-capped) and stores the result exactly like an uploaded file.

Tags: Attachments

### GET /api/v2/batches

List your research batches

List your research batches, newest first. `query` filters by batch name (case-insensitive substring); `status` filters by batch status (e.g. `PENDING`, `PROCESSING`, `PROCESSED_SUCCESSFULLY`, `PROCESSED_WITH_ERRORS`, `CANCELLED`). Page with `cursor` from the previous response.

Tags: Batches

### POST /api/v2/batches

Create a research batch

Create a batch that runs one research job per question (up to 100 rows). Config — expert, effort, approach, response language, concurrency — is chosen once for the whole batch. The create only persists intent; a dispatcher launches rows within ~30 seconds, respecting `max_concurrent`. Poll `GET /batches/{batch_id}` for progress; each row links to a normal research job readable via `GET /research/{job_id}`. Rows are metered like ordinary research at dispatch time — if credits run out mid-batch the batch pauses with `paused_reason: quota_exhausted` and resumes when credits return. `max_credits` caps total spend: the dispatcher never launches a row the remaining budget cannot cover and pauses the batch (`budget_exhausted`) at the cap; `credits_spent` on the detail response tracks consumption. An optional `Idempotency-Key` header makes the create replay-safe.

Tags: Batches

### GET /api/v2/batches/\{batch\_id\}

Get a research batch

Batch status, progress counters, config, and (by default) every row with its question, per-row status, and linked research job id — read a finished row's report via `GET /research/{job_id}`. Pass `include_rows=false` for a cheap status poll.

Tags: Batches

### POST /api/v2/batches/\{batch\_id\}/cancel

Cancel a research batch

Stop launching new rows: still-pending rows are marked failed, rows already running settle on their own. Cancelling an already-terminal batch is a no-op that returns the batch unchanged.

Tags: Batches

### GET /api/v2/batches/\{batch\_id\}/results

Get every batch row's result in one call

The batch's return path: per row — status, `error_code`, the linked research job id and report link, the structured output (when the run produced one), and a short answer (`headline` or `excerpt`). Assembled in two database queries with no per-row fetches, so one call replaces reading each row's job individually. The full report body is not inlined (it can be hundreds of KB per row) — follow `report_link` or `GET /research/{job_id}` for a specific row. Filter with `row_status` (e.g. `SUCCESS`, `FAILED`).

Tags: Batches

### POST /api/v2/batches/\{batch\_id\}/retry-failed

Retry every failed batch row

Re-run every FAILED row in one call: retryable rows reset to pending, the batch reopens, and the dispatcher launches fresh research jobs for them. Returns `retried_rows` — zero means nothing was retryable, which is a successful no-op. Rows on a cancelled batch are not retryable (409). Use each row's `error_code` to decide whether retrying is rational (`quota_exhausted` clears when credits return; `timed_out` and `dispatch_error` are worth retrying).

Tags: Batches

### POST /api/v2/batches/\{batch\_id\}/rows/\{row\_number\}/retry

Retry one failed batch row

Re-run one FAILED row: the row resets to pending, the batch reopens, and the dispatcher launches a fresh research job for it within ~30 seconds. Rows on a cancelled batch are not retryable (409).

Tags: Batches

### GET /api/v2/batches/estimate

Estimate a batch's credit cost

Preflight credit estimate for a batch, before creating it. Uses the same cost table the dispatcher bills from and applies the same account-tier clamp creation applies, so the quoted total matches what a batch you create will actually run and bill (`requested_effort`/`downgraded` surface any clamp). There is no upfront reservation: rows are metered as they dispatch.

Tags: Batches

### 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 accepts on the ``expert_id`` field. Use this to pick an ``expert_id`` for ``POST /api/v2/research``. Public — no auth required.

Tags: Experts

### POST /api/v2/experts

Create a custom expert

Create a custom expert directly from a full configuration (name, system prompt, skills, tools). The expert is immediately usable with `POST /api/v2/research` via its `expert_id` unless created as a `building` draft.

Tags: Experts

### DELETE /api/v2/experts/\{expert\_id\}

Archive a custom expert

Archive a custom expert you own. The expert disappears from pickers and can no longer be run; its configuration and version history are kept. Idempotent.

Tags: Experts

### GET /api/v2/experts/\{expert\_id\}

Get an expert's configuration

Read the full configuration of a custom expert (by id or slug) or a built-in registry expert: system prompt, skills, tools, output type/schema/SOP, template, input form, context files, defaults, cost cap and sharing flags.

Tags: Experts

### PATCH /api/v2/experts/\{expert\_id\}

Update a custom expert

Partial update: omitted fields are unchanged; lists replace; `output_template_file` accepts an empty string to clear; `pinned_workflow` and `max_cost_usd` accept an explicit `null` to clear. `status: active` finalizes a `building` draft. Publishing (`is_public`), `allow_free_tier_use` and `owner_email` are Parcha-admin-only. Every change is snapshotted as a restorable version.

Tags: Experts

### GET /api/v2/experts/\{expert\_id\}/context-files

List context files

Context files attached to an expert, merged from the expert repository and the text mirror.

Tags: Experts

### POST /api/v2/experts/\{expert\_id\}/context-files

Attach a context file

Upload a reference document (multipart `file`). Accepted: pdf, docx, pptx, xlsx, png, jpg, jpeg, gif, webp, and text formats (md, txt, json, yaml, csv, …). Archives (.zip) are rejected — expand them and upload the members. The original bytes are committed to the expert repository and the extracted text is mirrored onto the expert so runs, search and the output-template scaffold can use it. Re-uploading a name replaces it.

Tags: Experts

### DELETE /api/v2/experts/\{expert\_id\}/context-files/\{name\}

Remove a context file

Detach a context file: removes the text mirror entry and the repository copy. A file that is the current `output_template_file` must be cleared from that setting first.

Tags: Experts

### GET /api/v2/experts/\{expert\_id\}/context-files/\{name\}

Download a context file

Raw bytes of one context file (original upload when present, otherwise the mirrored text).

Tags: Experts

### POST /api/v2/experts/\{expert\_id\}/context-files/import

Import a context file by URL or from an attachment

JSON alternative to the multipart upload for callers where inline bytes are impractical (MCP base64 puts the file through the agent's context window). Provide exactly one of `source_url` (server-side SSRF-guarded fetch: http(s) only, public addresses only, size-capped, redirects re-validated) or `attachment_id` (copy from a research attachment you own). The fetched bytes run the same admission as a direct upload — extension allowlist, archive rejection, binary magic-byte validation.

Tags: Experts

### POST /api/v2/experts/\{expert\_id\}/plan-preview

Preview the research plan for a question

Run ONLY the planning phase with this expert attached — no sandbox, no research run — and return the plan the pipeline's planner would execute. Costs one cheap model call (rate limited per caller), so SOP edits can be iterated for cents instead of full runs. The preview covers the expert's planning contract (SOP, skills, tools, optional `context`); per-run inputs a real job adds — uploaded workspace files, connected customer tools — are not simulated.

Tags: Experts

### DELETE /api/v2/experts/\{expert\_id\}/share

Revoke a share

Revoke a previously granted user, tenant, or team access.

Tags: Experts

### GET /api/v2/experts/\{expert\_id\}/share

List shares

Access grants on the expert (owner, Parcha admins, team admins, ACL admins).

Tags: Experts

### POST /api/v2/experts/\{expert\_id\}/share

Share an expert

Grant a user (email), an email-domain tenant, or a team access to the expert. Owners and ACL admins may share within their own email domain; Parcha admins may share anywhere.

Tags: Experts

### GET /api/v2/experts/\{expert\_id\}/versions

List configuration versions

Version history of the expert's configuration, newest first (editors only).

Tags: Experts

### GET /api/v2/experts/\{expert\_id\}/versions/\{version\_num\}

Get one configuration version

The full configuration snapshot stored for a version.

Tags: Experts

### POST /api/v2/experts/\{expert\_id\}/versions/\{version\_num\}/restore

Restore a configuration version

Roll the expert's configuration back to a version. The current configuration is snapshotted first (`new_version_num`) so the restore is itself reversible.

Tags: Experts

### POST /api/v2/experts/\{expert\_id\}/visibility

Set public/private visibility

Owner-only. Making an expert public (visible to everyone in the picker) is Parcha-admin-only; owners may always make it private again.

Tags: Experts

### POST /api/v2/experts/apply

Apply a declarative expert manifest

Diff a full desired-state manifest against the current expert (targeted by `expert_id`, adopted by exact caller-owned name, or created fresh) and perform the minimal create/update/upload/delete set — custom skills included. Idempotent: re-applying an unchanged manifest is a no-op. `dry_run` returns the plan without applying; validation runs before any mutation and an invalid manifest applies nothing. `context_files` is the complete set (omitted names are pruned unless `prune_context_files` is false).

Tags: Experts

### POST /api/v2/experts/build

Start an async expert build

Start the prompt-driven expert builder: describe a domain and the builder agent designs the expert (system prompt, skills, tools) in a sandbox. Poll `GET /api/v2/experts/build/{job_id}` for progress; on success the expert registers as a `building` draft — activate it with `PATCH /api/v2/experts/{expert_id}`.

Tags: Experts

### GET /api/v2/experts/build/\{job\_id\}

Get expert build status

Poll the status of an async expert build. Terminal states are `succeeded` (the `expert` field carries the registered draft) and `failed` (see `error`).

Tags: Experts

### GET /api/v2/experts/custom

List your custom experts

List custom experts you own or can access. Distinct from the unauthenticated `GET /api/v2/experts` registry list: this returns user-created experts, including `building` drafts.

Tags: Experts

### POST /api/v2/experts/extract

Preview config extraction from pasted text

Run the config extractor on a pasted SOP / agent config and return the clean system prompt, structured `output_sop` and `output_schema` without saving anything. Pass the results to `POST /api/v2/experts` or `PATCH /api/v2/experts/{expert_id}`.

Tags: Experts

### POST /api/v2/experts/generate-workflow

Preview a generated workflow for an SOP

Author and validate a workflow DSL from an SOP (and optional sample input / output schema) without saving. When `valid`, pass `workflow` as `pinned_workflow`. Available only on deployments with workflow authoring enabled (404 otherwise); rate limited per caller.

Tags: Experts

### GET /api/v2/experts/mcp-tools

List MCP tools available to experts

The tools an expert can be granted via `mcp_tool_names` (and required via `required_tool_calls`). Filter with `query`, `server`, `category`, `limit`. Entries flagged `always_on` ride along with every research run and need not be granted.

Tags: Experts

### GET /api/v2/experts/skills

List skills available to experts

The skill catalog an expert can be linked to via `skill_names`, plus the custom skills you authored with `POST /api/v2/experts/skills`. Filter server-side with `query` (keyword match over name/description/tags), `category`, and `limit` (default 50); `total` reports the filtered match count so a capped response is recognizable.

Tags: Experts

### POST /api/v2/experts/skills

Create a custom skill

Author a custom skill (SKILL.md) that any of your experts can link via `skill_names`. Re-posting the same name overwrites your own skill in place (`created: false`).

Tags: Experts

### GET /api/v2/experts/skills/\{skill\_name\}

Read a skill's SKILL.md

Full SKILL.md content of a catalog skill or one of your custom skills.

Tags: Experts

### POST /api/v2/experts/validate

Validate an expert config without saving

Run every persistence-side validation — skill/tool names against the catalogs, required_tool_calls availability, output_schema JSON-Schema validity, output_template_file existence, pinned_workflow structure — and return ok/errors/warnings without persisting anything. Pass `expert_id` to validate an update against that expert's merged state; omit it to validate a fresh create.

Tags: Experts

### GET /api/v2/keys

List your API keys

Metadata only (label, display fragments, scopes, timestamps) — never the secret.

Tags: API Keys

### POST /api/v2/keys

Create an API key

Mint a `parcha-` API key for your own identity (OAuth authentication required — an API key cannot mint another key). Scopes must be a subset of the OAuth token's; omit to inherit them exactly. The secret is returned only in this response.

Tags: API Keys

### DELETE /api/v2/keys/\{key\_id\}

Revoke an API key

Revoke one of your keys. Idempotent — re-revoking an already-revoked key succeeds.

Tags: API Keys

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

### PATCH /api/v2/research/\{job\_id\_or\_slug\}

Update Research Job

Update mutable fields on a research job.

Set ``is_public`` to ``true`` to make the job and its linked apps
publicly viewable without authentication; set it to ``false`` to
revert them to owner/admin-only access. Jobs with linked apps can
also set ``anonymous_cta_enabled`` and ``anonymous_cta_variant`` in the same call.

Only the job's owner or a Parcha admin can change visibility.
Locked jobs (content moderation) reject the call.

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

### GET /api/v2/run

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/run

Create Research Job

Start a research job.

Tags: Research

### GET /api/v2/run/\{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