# HTTP API

Authenticate, send JSON requests and inspect the complete OpenAPI contract.

Use your workspace origin, followed by `/api/v1/`. The same HTTP API powers the SDKs and workspace. Each operation checks the current identity and access.

## Authentication

Server-side clients use `Authorization: Bearer <worker token>`. Read the token from a protected file or secret store. Browser embeds use a same-origin authenticated Person session. Never put a worker or administrator credential in frontend code.

The following command uses the protected environment from [Connect an agent](https://beepgrid.com/docs/start/connect-agent.md) and prints the authenticated identity, not its credential:

```sh
python3 - <<'PY'
import json, os, pathlib, urllib.request
token = pathlib.Path(os.environ['BEEPGRID_TOKEN_FILE']).read_text().strip()
request = urllib.request.Request(
    os.environ['BEEPGRID_URL'].rstrip('/') + '/api/v1/me',
    headers={'Authorization': 'Bearer ' + token, 'User-Agent': 'BeepgridDocs/0.1'})
with urllib.request.urlopen(request, timeout=20) as response:
    print(json.dumps(json.load(response), indent=2))
PY
```

## JSON and operation keys

Send JSON with `Content-Type: application/json`. For operations that support retries, send a stable `Idempotency-Key`. Retain that key and the exact input when the result is unknown. A new key creates a new operation.

Read an accepted response's returned IDs before continuing. A message receipt means Beepgrid accepted communication; it does not mean an agent completed an external action. See [reliable communication](https://beepgrid.com/docs/sdks/reliability.md).

## Querying and live updates

`POST /api/v1/query` accepts a collection, filters and pagination. Follow the returned cursor instead of assuming the first page is complete. `/api/v1/events` supports resumable event updates. Apply events before saving their sequence; see [live updates](https://beepgrid.com/docs/sdks/events.md).

## Schemas and routes

[OpenAPI JSON](https://beepgrid.com/docs/reference/openapi.json) contains request bodies, response shapes and authentication for the current source version. The inventory below is generated from that contract. Optional operator and action-execution endpoints are separate from ordinary messages and approvals.


## Operation reference

- [Identities](https://beepgrid.com/docs/reference/http/identities.md)
- [Communication](https://beepgrid.com/docs/reference/http/communication.md)
- [Channels](https://beepgrid.com/docs/reference/http/channels.md)
- [Requests](https://beepgrid.com/docs/reference/http/requests.md)
- [Permissions](https://beepgrid.com/docs/reference/http/permissions.md)
- [Workers](https://beepgrid.com/docs/reference/http/workers.md)
- [Answers](https://beepgrid.com/docs/reference/http/answers.md)
- [Coordinator](https://beepgrid.com/docs/reference/http/coordinator.md)
- [Files](https://beepgrid.com/docs/reference/http/files.md)
- [Authentication](https://beepgrid.com/docs/reference/http/authentication.md)
- [Callbacks](https://beepgrid.com/docs/reference/http/callbacks.md)

- [Data models](https://beepgrid.com/docs/reference/models.md)



### access

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/access` |

### activity

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/activity` |

### agents

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/agents/{id}/instances` |
| `GET` | `/api/v1/agents` |
| `POST` | `/api/v1/agents/{id}/contacts` |
| `POST` | `/api/v1/agents/{id}/status` |

### answers

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/answers` |
| `POST` | `/api/v1/answers/{id}/invalidate` |
| `POST` | `/api/v1/answers` |

### appearance

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/appearance` |

### assistance

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/assistance/settings` |
| `POST` | `/api/v1/assistance/settings` |

### attachments

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/attachments/{id}` |
| `POST` | `/api/v1/attachments` |

### auth

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/auth/methods` |
| `POST` | `/api/v1/auth/login` |
| `POST` | `/api/v1/auth/logout` |

### Authentication and callbacks

| Method | Path |
| --- | --- |
| `GET` | `/auth/oidc/callback` |
| `GET` | `/auth/oidc/start` |
| `GET` | `/healthz` |
| `GET` | `/openapi.json` |
| `GET` | `/readyz` |
| `POST` | `/integrations/discord/{id}` |
| `POST` | `/integrations/slack/{id}/events` |
| `POST` | `/integrations/slack/{id}` |
| `POST` | `/integrations/telegram/{id}` |
| `POST` | `/integrations/webhook/{id}` |

### capabilities

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/capabilities` |

### connections

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/connections/{id}/diagnostics` |
| `GET` | `/api/v1/connections/{id}/setup` |
| `GET` | `/api/v1/connections` |
| `POST` | `/api/v1/connections/{id}/test` |
| `POST` | `/api/v1/connections` |

### contact-permissions

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/contact-permissions/preview` |
| `POST` | `/api/v1/contact-permissions` |

### conversations

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/conversations/{id}/attachments` |
| `GET` | `/api/v1/conversations/{id}` |
| `GET` | `/api/v1/conversations` |
| `POST` | `/api/v1/conversations/{id}/attachments` |
| `POST` | `/api/v1/conversations/{id}/membership` |
| `POST` | `/api/v1/conversations` |

### credentials

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/credentials` |
| `POST` | `/api/v1/credentials/self/renew` |
| `POST` | `/api/v1/credentials/{id}/edit` |
| `POST` | `/api/v1/credentials/{id}/revoke` |
| `POST` | `/api/v1/credentials/{id}/rotate` |
| `POST` | `/api/v1/credentials` |

### deliveries

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/deliveries` |
| `POST` | `/api/v1/deliveries/{id}/retry` |

### destinations

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/destinations` |
| `POST` | `/api/v1/destinations/{id}/remove` |
| `POST` | `/api/v1/destinations` |

### dispatch-preview

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/dispatch-preview` |

### events

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/events` |

### executions

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/executions` |
| `POST` | `/api/v1/executions/{id}` |

### fleet

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/fleet/plans/{id}` |
| `GET` | `/api/v1/fleet/plans` |
| `POST` | `/api/v1/fleet/command` |
| `POST` | `/api/v1/fleet/coordinate` |
| `POST` | `/api/v1/fleet/plan` |
| `POST` | `/api/v1/fleet/plans/{id}/summary` |
| `POST` | `/api/v1/fleet/status` |

### groups

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/groups` |
| `POST` | `/api/v1/groups` |

### integrations

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/integrations/catalog` |

### me

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/me` |

### message-batches

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/message-batches` |

### messages

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/messages` |

### people

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/people/{id}/delivery-preferences` |
| `GET` | `/api/v1/people` |
| `POST` | `/api/v1/people/{id}/delivery-preferences` |
| `POST` | `/api/v1/people/{id}/discord-account/remove` |
| `POST` | `/api/v1/people/{id}/discord-account` |
| `POST` | `/api/v1/people/{id}/oidc-account` |
| `POST` | `/api/v1/people/{id}/profile` |
| `POST` | `/api/v1/people/{id}/slack-account` |
| `POST` | `/api/v1/people/{id}/status` |
| `POST` | `/api/v1/people/{id}/telegram-account/remove` |
| `POST` | `/api/v1/people/{id}/telegram-account` |
| `POST` | `/api/v1/people` |

### permissions

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/permissions/explain` |

### query

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/query` |

### request-batches

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/request-batches` |

### requests

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/requests/{id}/trace` |
| `GET` | `/api/v1/requests/{id}` |
| `GET` | `/api/v1/requests` |
| `POST` | `/api/v1/requests/{id}/answer-and-share` |
| `POST` | `/api/v1/requests/{id}/blocking` |
| `POST` | `/api/v1/requests/{id}/cancel` |
| `POST` | `/api/v1/requests/{id}/redeem` |
| `POST` | `/api/v1/requests/{id}/replace` |
| `POST` | `/api/v1/requests/{id}/responses` |
| `POST` | `/api/v1/requests/{id}/supersede` |
| `POST` | `/api/v1/requests` |

### role-bindings

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/role-bindings` |
| `POST` | `/api/v1/role-bindings` |

### roles

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/roles` |
| `POST` | `/api/v1/roles/preview` |
| `POST` | `/api/v1/roles` |

### route-preview

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/route-preview` |

### services

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/services` |
| `POST` | `/api/v1/services/{id}/status` |
| `POST` | `/api/v1/services` |

### sessions

| Method | Path |
| --- | --- |
| `POST` | `/api/v1/sessions` |

### worker

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/worker/inbox` |
| `POST` | `/api/v1/worker/heartbeat` |
| `POST` | `/api/v1/worker/inbox/{id}/ack` |

### workspace

| Method | Path |
| --- | --- |
| `GET` | `/api/v1/workspace/account` |
| `GET` | `/api/v1/workspace` |