# API

Base URL: `https://infrapilot.fly`. JSON over HTTPS. Send `Authorization: Bearer <token>`.

| Token | Looks like | Get it | Use it for |
| --- | --- | --- | --- |
| Setup token | `ipsetup_...` | the workspace's setup page; lasts 14 days, and is read-only once Pilot has completed its first review | the setup API, one workspace |
| API token | `ipapi_...` | `POST /api/workspaces/<id>/tokens` while signed in; lasts 90 days unless you send `expires_in_days` (1 to 365) | the workspace API, one workspace |

Changes made with a token are recorded under the workspace owner's name, with the token they came through.

Errors are `{"error": "..."}` with a 4xx status. Validation errors add `errors`, naming each field.

## Setup API

| Method and path | Does |
| --- | --- |
| `GET /api/v1/setup` | the workspace, steps done, `next`, connection needs |
| `GET /api/v1/setup/aws-role` | AWS only: the role's trust and permission policies |
| `POST /api/v1/setup/cloud` | submit the cloud connection; checked from the sandbox |
| `PUT /api/v1/setup/manifest` | submit the fleet spec (YAML or JSON); `?dry_run=1` validates it and says what would change, saving nothing |
| `POST /api/v1/setup/discover` | what the spec would adopt and build; changes nothing |
| `POST /api/v1/setup/contacts` | add people and channels for requests |
| `POST /api/v1/setup/start` | start Pilot |
| `GET /api/v1/setup/status` | `ready`, agent state, objectives, first review, open requests |

`POST /api/v1/setup/cloud` bodies, by `kind`:

```json
{"kind": "aws_role", "role_arn": "arn:aws:iam::123456789012:role/InfrapilotAgent", "region": "us-east-1"}
{"kind": "azure_federated", "tenant_id": "...", "client_id": "...", "subscription_id": "...", "resource_group": "rg-shop", "region": "eastus"}
{"kind": "gcp_impersonation", "service_account": "<connection.trust.service_account_name>@my-project.iam.gserviceaccount.com", "project_id": "my-project", "region": "us-central1"}
{"kind": "gcp_key", "key": { "...the service account key JSON..." : "" }, "project_id": "my-project", "region": "us-central1"}
```

## Workspace API

`<id>` is the workspace id (`ws_...`).

| Method and path | Does |
| --- | --- |
| `GET /api/workspaces/<id>/overview` | agent state, objectives, cost, counts, open requests |
| `GET /api/workspaces/<id>/ledger?limit=&before=&kinds=` | the ledger, newest first; `before` pages back from a `seq` |
| `GET /api/workspaces/<id>/ledger/<seq>` | one entry, with its hash and transaction |
| `GET /api/workspaces/<id>/ledger/verify` | recompute the hash chain and replay into the graph |
| `GET /api/workspaces/<id>/graph` | resources, controllers, intents and their edges |
| `GET /api/workspaces/<id>/export` | spec, graph and full ledger as one JSON document |
| `GET /api/workspaces/<id>/manifest` | the spec and its revisions |
| `PUT /api/workspaces/<id>/manifest` | replace the spec (YAML or JSON); `?dry_run=1` previews it |
| `GET /api/workspaces/<id>/requests` | Pilot's requests and answers |
| `POST /api/workspaces/<id>/requests/<request id>/answer` | `{"decision": "approve" | "deny", "note": "..."}` |
| `POST /api/workspaces/<id>/ask` | `{"text": "..."}`: tell Pilot something |
| `POST /api/workspaces/<id>/agent` | `{"action": "pause" | "resume" | "restart" | "stop" | "start"}` |
| `GET /api/workspaces/<id>/connectors`, `POST`, `DELETE .../<connector id>` | who Pilot reaches, and how |

Signed in only (not with a token):

| Method and path | Does |
| --- | --- |
| `GET /api/workspaces/<id>/tokens`, `POST`, `DELETE .../<token id>` | list, create and revoke API tokens |
| `GET /api/workspaces/<id>/members`, `POST {"email": "..."}`, `DELETE .../<email>` | who can see the workspace and answer requests; the owner adds and removes |

Deploy a new image from CI (`https://infrapilot.fly/docs/deploy.md`): `POST /api/v1/deploy {"workload", "image"}`, then `GET /api/v1/deploy/<id>` for the outcome.

Update the spec from CI:

```bash
curl -s -X PUT https://infrapilot.fly/api/workspaces/$WORKSPACE/manifest \
  -H "Authorization: Bearer $INFRAPILOT_API_TOKEN" -H "Content-Type: application/yaml" \
  --data-binary @infrapilot.yaml
```

Warn Pilot about something it can't see coming:

```bash
curl -s -X POST https://infrapilot.fly/api/workspaces/$WORKSPACE/ask \
  -H "Authorization: Bearer $INFRAPILOT_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "A sale starts at 12:00 UTC. Expect three times the usual checkout traffic for two hours."}'
```

Pilot answers in the ledger and stays inside the spec.

## MCP server

The same API for coding agents (Claude Code, Cursor, Codex), as an MCP server at `https://infrapilot.fly/mcp`
(Streamable HTTP; protocol `2026-07-28`, and `2025-11-25` back to `2025-03-26` through `initialize`).
It takes the same tokens: a setup token can set a workspace up, an API token can do everything below.

```bash
claude mcp add --transport http infrapilot https://infrapilot.fly/mcp --header "Authorization: Bearer $INFRAPILOT_TOKEN"
```

| Tool | Does |
| --- | --- |
| `setup_status` | where setup stands and the next step |
| `list_types` | an index of what Pilot understands on a cloud; with `type`, one resource type in full |
| `connect_cloud` | submit the cloud connection |
| `submit_manifest` | preview the fleet spec's changes; `apply: true` saves it |
| `discover` | what the spec would adopt and build; changes nothing |
| `start_pilot` | start Pilot |
| `overview` | objectives, cost, Pilot's state, open requests |
| `read_ledger`, `explain_change` | what changed, why, and the whole transaction |
| `ask_pilot` | have Pilot look at something; it answers in the ledger |
| `list_requests` | what Pilot is waiting on people for |

Resources: every docs page (`infrapilot://docs/<name>`) and the current spec (`infrapilot://workspace/spec`).
Requests are not answered here: people answer them in the dashboard, Slack or email.

## Other

| Path | Does |
| --- | --- |
| `GET /api/types/<provider>` | what Pilot understands on `aws`, `azure` or `gcp` |
| `GET /api/plans` | plans and prices |
| `GET /llms.txt` | index of these docs for agents |
| `GET /docs/<name>.md` | any docs page as Markdown |
