API Quickstart

Every IonWarp resource lives under /api/v1/ on this product's own domain. The worker answering the request is the agent, so the path names the resource and nothing else.

Authenticate

Mint a personal access token (PAT) in the product: the MCP entry in the dashboard sidebar opens the MCP & API Keys page (/mcp-config), where a key is created and shown once. Send it on every call as a bearer token:

Authorization: Bearer pat_...

A missing or invalid token answers 401 in the standard error envelope — a call never half-succeeds. A token is pinned to a workspace and may reach several projects, which is why the project is always explicit. What each scope grants is on Auth; the envelope and its codes are on Error Codes.

Name the project

Every call names its project: the Project-ID request header, or a ?project_id= query parameter. If the token pins exactly one project, that is the fallback. A bare call with no project resolvable answers 400 project_required — it never guesses. Sending both, disagreeing, answers 400 project_conflict. The call below shows the header in place.

Make the call

Here is the smallest useful read — your open pull requests:

List pull requests — GET /api/v1/pull-requests

curl "https://ionwarp.com/api/v1/pull-requests?state=open" \
  -H "Authorization: Bearer $DASH_API_KEY" \
  -H "Project-ID: pr_acme"

Which pull requests are still waiting on changes?

data_query {
  "collection": "pull_requests",
  "where": {
    "state": "open"
  }
}

{
  "object": "list",
  "data": [
    {
      "object": "pull-request",
      "id": "obj_123",
      "number": 630,
      "title": "Collapse the review dispatch fast path",
      "state": "open",
      "created_at": "2026-07-25T12:00:00.000Z",
      "updated_at": "2026-07-25T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

What comes back

Lists are enveloped:

{ "object": "list", "data": [], "has_more": false, "next_cursor": null }

A single object is returned directly, and a write returns the full object — not a bare id. Field names are snake_case everywhere: arguments, bodies, responses.

Paging is a keyset cursor — Pagination. Failures use one envelope whose param names the offending input — Error Codes. An operation a resource does not declare answers 405 operation_not_supported; which operations each one declares is on its reference page.

Next: Repositories & PRs is the first resource domain; every resource, with cURL · AI Prompt · MCP for each operation, is in the API reference; and the same surface over MCP is MCP Tools.