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 for details.

Request Format

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

Send JSON for POST, PUT, and PATCH requests:

{
  "name": "My Agent",
  "template": "template-uuid"
}

Response Format

Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Agent",
  "status": "sleeping",
  "created_at": "2026-01-15T10:30:00Z"
}

List Response (Paginated)

{
  "results": [...],
  "pagination": {
    "total_count": 100,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Error Response

{
  "detail": "Not found."
}

Validation errors include field details:

{
  "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 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=<id>` or `?adapter=<id>`)
`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=<id>&span_type=<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 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 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 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/

​API Reference

​Base URL

​Authentication

​Request Format

​Headers

​Request Body

​Response Format

​Success Response

​List Response (Paginated)

​Error Response

​HTTP Status Codes

​Organizations

​Auth

​Organizations

​Organization API Keys

​Members

​Invites

​Templates

​Agents

​Agents

​Usage Records

​Adapters & Tools

​Adapters

​Adapter Configs

​Tools

​Tracing

​Traces

​Spans

​Trace Reviews

​Legacy Eval Cases

​Default Adapter State

​Contacts

​Documents

​Projects

​Notifications

​SMS / MMS / Surge / Blooio Messages

​Email Messages

​Webchat

​OAuth — Gmail / Google Calendar / Drive / Strava

​OpenAPI Specification

API Reference

Base URL

Authentication

Request Format

Headers

Request Body

Response Format

Success Response

List Response (Paginated)

Error Response

HTTP Status Codes

Organizations

Auth

Organizations

Organization API Keys

Members

Invites

Templates

Agents

Agents

Usage Records

Adapters & Tools

Adapters

Adapter Configs

Tools

Tracing

Traces

Spans

Trace Reviews

Legacy Eval Cases

Default Adapter State

Contacts

Documents

Projects

Notifications

SMS / MMS / Surge / Blooio Messages

Email Messages

Webchat

OAuth — Gmail / Google Calendar / Drive / Strava

OpenAPI Specification