APIs & authentication
Use the interfaces that exist today, with the right credentials for each boundary.
Application authentication
The web application uses Better Auth under /api/auth and a typed RPC surface under /rpc. Browser requests use the deployment’s session and origin checks; internal RPC procedures are not presented as a stable public REST SDK.
No universal public “One API key” is documented here. For a bot webhook, use the dedicated webhook secret configured for that bot. Never substitute a model-provider key or a browser cookie.
Send a bot webhook
The implemented route is POST /api/v1/bots/:botId/webhook. Enable and obtain the webhook secret for an ordinary, non-archived bot in your own deployment. Send it as a bearer token from your server, never from public browser code.
The endpoint accepts JSON and bounds the raw request body to 64 KiB. Use an idempotency key for retrying the same delivery. Active webhook-enabled routines may be selected by the server.
curl --request POST \
"https://one.example.com/api/v1/bots/BOT_ID/webhook" \
--header "Authorization: Bearer $ONE_BOT_WEBHOOK_SECRET" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: example-event-001" \
--data '{"event":"brief.ready","id":"example-event-001","brief":"Prepare a review of the attached context."}'Handle delivery correctly
Missing bots, missing webhook secrets, and invalid bearer credentials return 401 without revealing whether a bot exists. Oversized request bodies return 413. A successful HTTP delivery does not mean the bot’s downstream task has finished.
The payload is treated as untrusted event data, not privileged instructions. Keep the bot’s allowed behavior and review requirements in its configured instructions and tool permissions.
Deployment health
The API exposes GET /health for operator health checks. Readiness includes configured subsystems. Calling reports its own state so an optional calling outage does not automatically fail the entire application health.
curl --fail "https://one.example.com/health"