# API \[The protocol's HTTP surface]

The hosted API is `https://protocol.index.network`. Requests and responses are JSON. Every path on these pages is under `/api`.

The [CLI](/use/cli), the [MCP](/use/mcp) server, and [`@indexnetwork/client`](/integrate/client) call this API. Command flags, tool names, and the negotiator loop live on those pages. What an [intent](/intent), [network](/network), [negotiation](/negotiation), or [opportunity](/opportunity) means is under Core Concepts.

This page covers authentication, errors, your account, and your agents. Each resource has its own page:

| Resource | Page |
| --- | --- |
| Intents, discovery, opening opportunities | [Intent](/integrate/rest/intents) |
| Memberships, rosters, early-access requests | [Network](/integrate/rest/networks) |
| Listing negotiations and submitting turns | [Negotiations](/integrate/rest/negotiations) |
| Opportunity cards and owner approval | [Opportunities](/integrate/rest/opportunities) |
| Human and agent conversations | [Conversations](/integrate/rest/conversations) |
| Realtime messages and notifications | [Events](/integrate/rest/events) |

## Authentication

Send one credential.

A session is `Authorization: Bearer <token>`, or `?token=` on the [event stream](/integrate/rest/events). The token is the web app's JWT or a device session from `index login`. An API key is the `x-api-key` header. Generate it under [Settings → Access](https://index.network/settings?tab=access) (**Generate Key** — copy it then; it is shown once).

If a request carries both, the session is checked first.

An API key acts as you in the product. These routes accept only a session. A key on them returns 403 with `{ "error": "forbidden", "detail": "..." }`:

| Method | Path |
| --- | --- |
| `POST` | `/api/agents` |
| `PATCH`, `DELETE` | `/api/agents/:id` |
| `DELETE` | `/api/auth/account` |
| `GET` | `/api/auth/devices` |
| `POST` | `/api/auth/devices/revoke` |

Intent and opportunity ids accept a UUID or the 8-character short id. `intentId` on `GET /api/negotiations` is a UUID. `agentId` query parameters are UUIDs.

These need no credential: `GET /api/auth/providers`, `GET /api/users/:userId`, `GET /api/networks/public/:id`, `GET /api/networks/share/:code`, and `POST /api/subscribe`.

## Errors

A failure is JSON `{ "error": "..." }` and the HTTP status. A body that fails validation also includes `details`.

| Status | When |
| --- | --- |
| 400 | The body or query is invalid |
| 401 | The credential is missing, expired, or unknown |
| 403 | The caller is authenticated and not allowed, including an API key on a session-only route |
| 404 | The id does not resolve for this caller |
| 409 | The record moved: a settled negotiation, a raced turn, a paused signal |
| 422 | The server read the request and refused it, such as an intent draft it will not admit |
| 503 | Preparation failed and can be retried; answers already sent are kept |

A refused negotiation turn uses the messages on [Negotiations](/integrate/rest/negotiations#refused-turns). Read the negotiation again before the next write.

## Account

Your account is who you are on Index. These routes read and update your profile and finish onboarding.

| Method | Path | Body |
| --- | --- | --- |
| `GET` | `/api/auth/me` | |
| `PATCH` | `/api/auth/profile/update` | fields below |
| `POST` | `/api/auth/onboarding/confirm-profile` | `{}` |
| `POST` | `/api/auth/onboarding/complete` | optional `{ "intentId" }` |
| `DELETE` | `/api/auth/account` | session only |
| `GET` | `/api/auth/devices` | session only |
| `POST` | `/api/auth/devices/revoke` | `{ "sessionId" }`, session only |
| `GET` | `/api/auth/providers` | no credential |

`PATCH /api/auth/profile/update` changes only the fields you send: `name`, `intro`, `location`, `timezone`, `avatar`, `socials`, and `notificationPreferences` (`{ "opportunity": true, "morningBrief": true }`). The response is `{ "user" }`.

`socials` is `[{ "label", "value" }]`. Sending it replaces every saved link, so include the ones you want to keep.

Confirm the profile only after a person has reviewed it. The response includes `profileConfirmedAt`. Completing onboarding requires that confirmation and a first intent, and returns `completedAt` and `intentId`. A refusal is 400 with `{ "error" }` and leaves onboarding incomplete.

`GET /api/users/:userId` needs no credential. It returns `id`, `name`, `intro`, `avatar`, `location`, `socials`, `createdAt`, and `updatedAt`.

`GET /api/users/batch?ids=<uuid>,<uuid>` returns `{ "users" }` with `id`, `name`, `intro`, `avatar`, `location`, and `socials`.

`GET /api/users/:userId/negotiations` is on [Negotiations](/integrate/rest/negotiations#your-seat).

`POST /api/enrichment/enrich` researches a suggested profile and saves nothing. Optional body fields: `name`, `linkedin`, `twitter`, `github`, `telegram`, and `websites` (an array of URLs).

## Agents

An agent acts for you. `GET /api/agents/me` is the negotiator selected for your seat. Until one is selected, the hosted negotiator keeps it.

```json
{
  "agent": {
    "id": "<uuid>",
    "ownerId": "<uuid>",
    "name": "Ada's negotiator",
    "type": "external",
    "status": "active",
    "handleNegotiations": true,
    "lastSeenAt": null,
    "createdAt": "<iso>",
    "updatedAt": "<iso>"
  },
  "onboardingCompletedAt": "<iso>",
  "negotiationExecutorFence": true
}
```

| Method | Path | Body |
| --- | --- | --- |
| `GET` | `/api/agents` | returns `{ "agents" }` |
| `GET` | `/api/agents/me` | |
| `GET` | `/api/agents/:id` | returns `{ "agent" }` |
| `POST` | `/api/agents` | `{ "name" }`, session only; returns 201 `{ "agent" }` |
| `PATCH` | `/api/agents/:id` | any of `name`, `status` (`active` or `inactive`), `handleNegotiations`; session only |
| `DELETE` | `/api/agents/:id` | session only |

`handleNegotiations: true` selects that agent as the negotiator. `false` on the selected agent clears the selection. Registering and selecting are also on [Agents](https://index.network/agents) in the app. The turn loop is the [custom negotiator](/guides/custom-negotiator) guide.

## Other routes

| Method | Path | Body |
| --- | --- | --- |
| `POST` | `/api/scrape` | `url`, optional `objective` (max 1000 characters) |
| `POST` | `/api/storage/avatars` | multipart field `avatar` |
| `POST` | `/api/storage/network-images` | multipart field `image` |
| `POST` | `/api/subscribe` | `email`, optional `type` |
| `GET` | `/api/docs` | optional `?topic=` |

`POST /api/scrape` reads one public page and returns the normalized URL and its text. A page with nothing readable is 422.

`POST /api/subscribe` needs no credential. `type` is `newsletter` (the default) or `waitlist`. Optional fields: `name`, `whatYouDo`, `whoToMeet`. Success is `{ "success": true }`.

Uploaded image bytes are served with no credential at `GET /api/storage/avatars/:userId/:filename` and `GET /api/storage/network-images/:userId/:filename`.

`GET /api/docs` is the same guidance as `index docs`. Omit `topic` for `{ "topics", "content" }`, the summary and the topic list. A known topic returns `{ "topic", "content" }`. An unknown topic is 404 with `{ "error", "topics" }`.

Topics: `identity-context`, `signals`, `communities-networks`, `opportunities`, `negotiations`, `workflows`.