API and webhook reference

This describes integration doors present in application code. It does not deploy anything or present every internal endpoint as a stable public product API. For no-code administration see Advanced settings.

Catalogue and action calls

GET /api/os/tools returns permitted workspace actions, schemas and event triggers for the signed-in person. ?localized=1 supplies translated screen labels; automation uses English contract names.

POST /api/os/actions/<action> uses the same browser session and exact action name. Its JSON body is the action input; success returns ok, result, activity summaries and event names. For example, if permitted, inspect crm.update_lead in the catalogue before sending its input. This route uses getSession(); adding a Settings API key as a Bearer token to every browser route is not documented to work.

UI actions and Era MCP/CLI calls use the same action-runtime rules. See MCP tools and commands.

Incoming webhooks

Create an inbound endpoint under /settings/webhooks; its displayed URL is /api/webhooks/trigger/<path>. Use POST, JSON and Authorization: Bearer <token> or x-era-token. Tokens are shown on creation/rotation. Keep a unique Idempotency-Key stable for one operation; OS replay protection lasts seven days. Body limit is 256 KiB. This does not impose the same limit on unrelated provider workflow webhook paths.

POST /api/webhooks/trigger/DEMO_PATH
Authorization: Bearer DEMO_TOKEN
Idempotency-Key: demo-order-001
Content-Type: application/json

{"orderReference":"demo-001"}

Never insert real tokens in examples. Responses: 202 accepted/event ID, 200 duplicate, 401 wrong token, 429 rate limit, 410 inactive and 413 oversized body. Acceptance emits platform.webhook_received; it does not guarantee workflow completion. Inspect run history separately.

Outgoing webhooks

Endpoints listen for events and queue deliveries. Verify x-era-signature: timestamp and HMAC-SHA256 from t=…,v1=…. The signed bytes are timestamp + dot + raw body; do not reformat JSON before verification. Reject timestamps older than five minutes. Idempotency-Key remains stable across retries.

Timeout/attempt/failure disablement and rotation settings are in Advanced. Older unsigned endpoints can appear with warnings; inspect Signed state. Send test uses the real delivery queue/history.

Other doors and secrets

Calendar/notetaker and voice services use their own validated webhooks; obtain URLs from their settings. Internal Station, service and workflow APIs use different authentication from browser sessions. A route existing in the repository does not make it a public integration. Keep API/provider secrets out of chat, docs, Git and screenshots.