Relay REST API
Capture agent sessions from developer machines and review them in Architect. Twenty-six routes split between CLI ingest (org secret) and dashboard (Cognito JWT).
Base URL: https://api.dev.relay.oprag.ai. All JSON bodies use Content-Type: application/json. Errors return { error, code }.
| Audience | Auth | Start here |
|---|---|---|
| Relay CLI / automation | X-Relay-Secret or Bearer sk_live_* | CLI ingest |
| Architect dashboard | Cognito JWT | Dashboard API |
| Browser bootstrap | None | Platform |
| Endpoint | Credential | What it does |
|---|---|---|
GET /health | Public | Liveness probe for the Relay API. |
GET /config | Public | Cognito pool/client IDs and API URL for the Architect SPA bootstrap. |
POST /v1/organizations | Cognito JWT | Create an organization for the signed-in user who has no tenant yet. |
GET /v1/organizations/me | Cognito JWT | Return the caller's organization. |
PATCH /v1/organizations/me | Cognito JWT | Replace the organization display name. |
GET /v1/organizations/me/members | Cognito JWT | List active and invited organization members. |
POST /v1/organizations/me/members | Cognito JWT | Invite a user to the organization by email. |
POST /v1/organizations/me/secrets | Cognito JWT | Issue a new organization secret for CLI ingest. |
GET /v1/organizations/me/secrets | Cognito JWT | List organization secrets (metadata only — no plaintext). |
DELETE /v1/organizations/me/secrets/{secretId} | Cognito JWT | Revoke an organization secret. |
POST /v1/environments | Org secret | Register or update a developer machine environment from the CLI. |
POST /v1/environments/{environmentId}/heartbeat | Org secret | Refresh last-seen timestamp for a registered environment. |
GET /v1/organizations/me/environments | Cognito JWT | List developer environments registered for the organization. |
GET /v1/organizations/me/environments/{environmentId} | Cognito JWT | Fetch one developer environment by id. |
DELETE /v1/organizations/me/environments/{environmentId} | Cognito JWT | Revoke a developer environment. |
GET /v1/agents | Cognito JWT | List supported agent definitions in the Relay catalog. |
GET /v1/organizations/me/agents | Cognito JWT | List agent installations for the organization. |
POST /v1/organizations/me/agents | Cognito JWT | Create an agent installation from the dashboard. |
PATCH /v1/organizations/me/agents/{installationId} | Cognito JWT | Update an agent installation's version, config, or status. |
POST /v1/environments/{environmentId}/agents | Org secret | Register or upsert an agent installation from the CLI. |
POST /v1/sessions | Org secret | Open a new agent session for event capture. |
POST /v1/sessions/{sessionId}/events | Org secret | Append one or more session events (CLI hooks and sync). Each event's payload is optional and defaults to {}. |
POST /v1/sessions/{sessionId}/complete | Org secret | Mark a session completed or failed. |
GET /v1/organizations/me/sessions | Cognito JWT | List captured sessions for review in Architect. |
GET /v1/organizations/me/sessions/{sessionId} | Cognito JWT | Fetch one session with metadata for the review UI. |
GET /v1/organizations/me/sessions/{sessionId}/events | Cognito JWT | Page through events for a session. |
Ready to ship?
Get started free