> ## Documentation Index > Fetch the complete documentation index at: https://docs.bedrock.orinlabs.org/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Complete reference for the Bedrock API # API Reference The Bedrock API is a REST API for building and managing autonomous AI agents. ## Base URL ``` https://api.bedrock.orinlabs.org ``` ## Authentication Bedrock supports two authentication schemes: * **API Key** (most use cases) — send `Authorization: Bearer YOUR_API_KEY` using an organization-scoped key from `/api/organizations/api-keys/`. * **Token Auth** (portal / user-scoped) — DRF `TokenAuthentication`; send `Authorization: Token YOUR_USER_TOKEN`. Tokens are returned by `/api/organizations/auth/signup/` and `/api/organizations/auth/login/`. Endpoints like `/api/organizations/organizations/`, `/api/organizations/api-keys/`, and `/api/templates/` accept either scheme. See [Authentication](/authentication) for details. ## Request Format ### Headers ``` Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` ### Request Body Send JSON for `POST`, `PUT`, and `PATCH` requests: ```json theme={null} { "name": "My Agent", "template": "template-uuid" } ``` ## Response Format ### Success Response ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "My Agent", "status": "sleeping", "created_at": "2026-01-15T10:30:00Z" } ``` ### List Response (Paginated) ```json theme={null} { "results": [...], "pagination": { "total_count": 100, "limit": 50, "offset": 0, "has_more": true } } ``` ### Error Response ```json theme={null} { "detail": "Not found." } ``` Validation errors include field details: ```json theme={null} { "name": ["This field is required."], "model": ["Invalid model specified."] } ``` ## HTTP Status Codes | Code | Description | | ------------------ | -------------------------------------------- | | `200 OK` | Request succeeded | | `201 Created` | Resource created | | `202 Accepted` | Request accepted for asynchronous processing | | `204 No Content` | Deleted successfully | | `400 Bad Request` | Invalid request or validation error | | `401 Unauthorized` | Missing or invalid API key | | `403 Forbidden` | Valid key but insufficient permissions | | `404 Not Found` | Resource not found | *** ## Organizations Base path: `/api/organizations/` ### Auth | Method | Endpoint | Description | | ------ | --------------- | ------------------------------------ | | `POST` | `/auth/signup/` | Create organization, user, and token | | `POST` | `/auth/login/` | Log in and receive a token | | `GET` | `/auth/me/` | Get the current user + organization | | `POST` | `/auth/logout/` | Invalidate the current token | ### Organizations | Method | Endpoint | Description | | --------------- | ---------------------- | --------------------------------------------------------------------------------- | | `GET` | `/organizations/` | List organizations (your own unless `is_admin`) | | `GET` | `/organizations/{id}/` | Get organization | | `PUT` / `PATCH` | `/organizations/{id}/` | Update organization (including write-only `openai_api_key` / `anthropic_api_key`) | | `DELETE` | `/organizations/{id}/` | Delete organization | ### Organization API Keys | Method | Endpoint | Description | | --------------- | ----------------- | --------------------------------- | | `GET` | `/api-keys/` | List organization-scoped API keys | | `POST` | `/api-keys/` | Create API key | | `GET` | `/api-keys/{id}/` | Get API key | | `PUT` / `PATCH` | `/api-keys/{id}/` | Update API key | | `DELETE` | `/api-keys/{id}/` | Delete API key | ### Members | Method | Endpoint | Description | | -------- | --------------------- | ---------------------------------------- | | `GET` | `/members/` | List organization members | | `GET` | `/members/{user_id}/` | Get member | | `DELETE` | `/members/{user_id}/` | Remove a member (cannot remove yourself) | ### Invites | Method | Endpoint | Description | | -------- | ----------------------- | ------------------------------------- | | `GET` | `/invites/` | List pending invites | | `POST` | `/invites/` | Create invite | | `DELETE` | `/invites/{id}/` | Revoke invite | | `POST` | `/invites/{id}/accept/` | Accept invite and create user account | *** ## Templates Base path: `/api/templates/` [AgentTemplates](/concepts/templates) blueprint new agents. Their configuration is snapshotted onto each agent at creation time. | Method | Endpoint | Description | | --------------- | -------- | --------------- | | `GET` | `/` | List templates | | `POST` | `/` | Create template | | `GET` | `/{id}/` | Get template | | `PUT` / `PATCH` | `/{id}/` | Update template | | `DELETE` | `/{id}/` | Delete template | *** ## Agents Base path: `/api/cloud/` ### Agents | Method | Endpoint | Description | | -------- | ------------------------------ | ----------------------------------------- | | `GET` | `/agents/` | List agents | | `POST` | `/agents/` | Create agent | | `GET` | `/agents/{id}/` | Get agent | | `PUT` | `/agents/{id}/` | Replace agent | | `PATCH` | `/agents/{id}/` | Update agent | | `DELETE` | `/agents/{id}/` | Delete agent | | `POST` | `/agents/{id}/run/` | Wake/run agent | | `POST` | `/agents/{id}/stop/` | Stop running agent | | `POST` | `/agents/{id}/sleep/` | Sleep endpoint (used by the harness) | | `GET` | `/agents/{id}/usage/` | Agent usage stats | | `GET` | `/agents/{id}/harness-config/` | `AgentConfig` the harness bootstraps with | | `POST` | `/agents/{id}/tags/` | Attach a free-form tag (idempotent) | | `DELETE` | `/agents/{id}/tags/{tag}/` | Detach a tag (idempotent) | ### Usage Records | Method | Endpoint | Description | | ------ | ----------------- | ------------------------ | | `GET` | `/usage/` | List usage records | | `GET` | `/usage/{id}/` | Get a usage record | | `GET` | `/usage/summary/` | Aggregated usage summary | *** ## Adapters & Tools Base path: `/api/toolbox/` ### Adapters | Method | Endpoint | Description | | --------------- | ----------------- | -------------- | | `GET` | `/adapters/` | List adapters | | `POST` | `/adapters/` | Create adapter | | `GET` | `/adapters/{id}/` | Get adapter | | `PUT` / `PATCH` | `/adapters/{id}/` | Update adapter | | `DELETE` | `/adapters/{id}/` | Delete adapter | ### Adapter Configs Per-template configuration (API keys, phone numbers, etc.) for an adapter. Creating an `AdapterConfig` both enables the adapter on the template and stores its config. Delete the row to detach the adapter. | Method | Endpoint | Description | | --------------- | ------------------------ | -------------------------------------------------------------------- | | `GET` | `/adapter-configs/` | List adapter configs (filter by `?template=` or `?adapter=`) | | `POST` | `/adapter-configs/` | Create adapter config | | `GET` | `/adapter-configs/{id}/` | Get adapter config | | `PUT` / `PATCH` | `/adapter-configs/{id}/` | Update adapter config | | `DELETE` | `/adapter-configs/{id}/` | Delete adapter config | ### Tools | Method | Endpoint | Description | | --------------- | -------------- | ----------- | | `GET` | `/tools/` | List tools | | `POST` | `/tools/` | Create tool | | `GET` | `/tools/{id}/` | Get tool | | `PUT` / `PATCH` | `/tools/{id}/` | Update tool | | `DELETE` | `/tools/{id}/` | Delete tool | *** ## Tracing Base path: `/api/tracing/` ### Traces | Method | Endpoint | Description | | ------ | ------------------------- | ------------------------------------------------------------------------------- | | `GET` | `/traces/` | List traces (router default) | | `GET` | `/traces/list/` | Paginated trace listing with filters (`agent`, `name`, `started_after`, `sort`) | | `POST` | `/traces/` | Create trace | | `GET` | `/traces/{trace_id}/` | Get trace with spans | | `POST` | `/traces/{trace_id}/end/` | End trace | ### Spans | Method | Endpoint | Description | | ------- | -------------------------- | ----------------------------------------------------- | | `GET` | `/spans/` | List spans (filter by `?trace=&span_type=`) | | `POST` | `/spans/` | Create span | | `GET` | `/spans/{span_id}/` | Get span | | `PATCH` | `/spans/{span_id}/` | Update span | | `POST` | `/spans/{span_id}/end/` | End span | | `POST` | `/spans/{span_id}/flag/` | Flag span for review | | `POST` | `/spans/{span_id}/unflag/` | Remove flag from span | **Span types:** `text`, `audio`, `tool`, `function`, `llm`, `checkpoint`. See [Evaluations](/concepts/evals) for the `checkpoint` span shape. ### Trace Reviews Human (or automated) review attached to any trace. Rubric scores live in `criterion_scores`; `checkpoint_pass_rate` and `weighted_score` are computed on read from the trace's `span_type="checkpoint"` spans and the review's scores respectively. | Method | Endpoint | Description | | --------------- | ----------------------------- | -------------------------------- | | `GET` / `POST` | `/traces/{trace_id}/reviews/` | List / create reviews on a trace | | `GET` / `PATCH` | `/reviews/{review_id}/` | Get / update a review | ### Legacy Eval Cases A small read/write endpoint for stand-alone `Eval` records. Bedrock no longer runs end-to-end simulations (those live in the [bedrock-harness](https://github.com/orinlabs/bedrock-harness) repo) — this endpoint is kept for storing individual eval inputs/rubrics. | Method | Endpoint | Description | | -------- | ------------------- | ---------------- | | `GET` | `/evals/` | List eval cases | | `POST` | `/evals/` | Create eval case | | `GET` | `/evals/{eval_id}/` | Get eval case | | `PATCH` | `/evals/{eval_id}/` | Update eval case | | `DELETE` | `/evals/{eval_id}/` | Delete eval case | *** ## Default Adapter State Base path: `/api/defaults/` REST endpoints for data managed by the built-in adapters. Agents interact with this state through tools; these endpoints let your own backend read/write the same data. ### Contacts | Method | Endpoint | Description | | --------------- | ----------------- | -------------- | | `GET` | `/contacts/` | List contacts | | `POST` | `/contacts/` | Create contact | | `GET` | `/contacts/{id}/` | Get contact | | `PUT` / `PATCH` | `/contacts/{id}/` | Update contact | | `DELETE` | `/contacts/{id}/` | Delete contact | ### Documents | Method | Endpoint | Description | | --------------- | ------------------ | --------------- | | `GET` | `/documents/` | List documents | | `POST` | `/documents/` | Create document | | `GET` | `/documents/{id}/` | Get document | | `PUT` / `PATCH` | `/documents/{id}/` | Update document | | `DELETE` | `/documents/{id}/` | Delete document | ### Projects | Method | Endpoint | Description | | --------------- | --------------------------- | -------------- | | `GET` | `/calendars/projects/` | List projects | | `POST` | `/calendars/projects/` | Create project | | `GET` | `/calendars/projects/{id}/` | Get project | | `PUT` / `PATCH` | `/calendars/projects/{id}/` | Update project | | `DELETE` | `/calendars/projects/{id}/` | Delete project | ### Notifications See [Notifications](/concepts/notifications) for semantics. | Method | Endpoint | Description | | --------------- | ---------------------- | ------------------------------------------------------ | | `GET` | `/notifications/` | List notifications | | `POST` | `/notifications/` | Create notification (wakes agent if `priority="high"`) | | `GET` | `/notifications/{id}/` | Get notification | | `PUT` / `PATCH` | `/notifications/{id}/` | Update notification | | `DELETE` | `/notifications/{id}/` | Delete notification | ### SMS / MMS / Surge / Blooio Messages Inbound + outbound history for each messaging adapter. | Method | Endpoint | Description | | ------ | ------------------------ | ------------------------------ | | `GET` | `/sms/messages/` | List SMS messages | | `GET` | `/sms/messages/{id}/` | Get SMS message | | `GET` | `/mms/messages/` | List MMS/iMessage/RCS messages | | `GET` | `/mms/messages/{id}/` | Get MMS message | | `GET` | `/surge/messages/` | List Surge messages | | `GET` | `/surge/messages/{id}/` | Get Surge message | | `GET` | `/blooio/messages/` | List Blooio messages | | `GET` | `/blooio/messages/{id}/` | Get Blooio message | ### Email Messages | Method | Endpoint | Description | | ------ | ----------------------- | ------------------- | | `GET` | `/email/messages/` | List email messages | | `GET` | `/email/messages/{id}/` | Get email message | ### Webchat Local web-based chat channel (alternative to SMS for dev / testing). | Method | Endpoint | Description | | ------ | -------------------- | -------------------------------------- | | `GET` | `/webchat/messages/` | List chat messages | | `POST` | `/webchat/send/` | Send a user message, wake the agent | | `GET` | `/webchat/status/` | Poll for the latest assistant response | ### OAuth — Gmail / Google Calendar / Drive / Strava Connect per-user third-party accounts to an agent. Each adapter follows the same shape. | Method | Endpoint | Description | | ------------------------- | -------------------------------- | -------------------------------------- | | `GET` | `/gmail/oauth/accounts/` | List connected Gmail accounts | | `POST` | `/gmail/oauth/accounts/` | Attach an OAuth account | | `GET` | `/gmail/oauth/accounts/{id}/` | Get account | | `DELETE` | `/gmail/oauth/accounts/{id}/` | Disconnect account | | `POST` | `/gmail/oauth/accounts/connect/` | Start OAuth flow, returns redirect URL | | `GET` / `POST` / `DELETE` | `/gcal/oauth/accounts/...` | Same shape, Google Calendar | | `GET` / `POST` / `DELETE` | `/drive/oauth/accounts/...` | Same shape, Google Drive | | `GET` / `POST` / `DELETE` | `/strava/oauth/accounts/...` | Same shape, Strava | *** ## OpenAPI Specification The complete OpenAPI 3.0 spec powers this reference and is also available at: * **Interactive Docs**: `https://api.bedrock.orinlabs.org/api/docs/` * **ReDoc**: `https://api.bedrock.orinlabs.org/api/redoc/` * **Raw Schema**: `https://api.bedrock.orinlabs.org/api/schema/`