Cervello turns a bug report or support ticket into a review-ready GitHub
pull request. Submit a ticket, watch the agent triage → plan → execute →
draft a PR over a WebSocket stream, then approve sensitive steps and
inspect the full audit trail. This reference documents every route the
product UI and the embeddable widget call.
Base URLhttps://api.cervellolab.xyz⧉
Authentication
When the server operator sets AGENTOS_API_KEY
(or issues per-client tokens), every route except the ones below requires
an X-API-Key header. If no key is configured
server-side — as on the public demo — auth is bypassed entirely and every
route is reachable unauthenticated.
Create a session from a ticket. The agent loop runs asynchronously in the
background — this call returns immediately with a session id you can poll
or stream.
curl
# create a session
curl https://api.cervellolab.xyz/api/sessions \
-X POST \
-H "Content-Type: application/json" \
-H "X-API-Key: $AGENTOS_API_KEY" \
-d '{
"title": "Checkout button unresponsive on Safari",
"body": "Clicking Pay Now does nothing on iOS Safari 17. No console errors. Works fine on Chrome.",
"source": "manual",
"kind": "bug",
"repo_label": "hooman96/cervello"
}'
Then poll GET /api/sessions/{'{id}'} or open a
WebSocket to /api/stream/{'{id}'} to watch the
triage → plan → execute → PR-draft loop live.
Bring your own key
POST /api/sessions accepts an optional
llm object so you can run a session on your own
model provider instead of the server's default. Pass your key with each
session you create — it is held in memory only for the duration of that
one run, and is never persisted, never echoed back in any response, and
never written to logs or the audit trail.
Field
Type
Description
provider
string
One of anthropic, openai, gemini, ollama, claude-cli, mock.
api_key
string?
Write-only. Used for this session's run, then discarded.
GitHub push credentials are
server-side only. Opening a real pull request requires the
server operator to have configured a GITHUB_TOKEN
with Contents: Read & write and
Pull requests: Read & write on the target
repo. There is currently no per-session field or endpoint for submitting
your own GitHub token — every session on a given deployment pushes
through that one server-configured credential (or drafts a PR without
pushing, if none is configured).
Coming soon
A saved, per-user key vault (so you don't resend a key with every
session) is planned but not built. Today, BYOK is strictly
per-request — there is no /api/keys endpoint.
Group
Sessions
Submit tickets, track the agent loop, and gate sensitive steps behind human approval.
POST/api/sessionsrequires X-API-Key
Submit a ticket and start a session. The agent loop (triage → plan → execute → PR draft) runs in a background thread; this returns immediately with the new session.
Request body
Field
Type
Description
title
string
required — short ticket title.
body
string
required — full ticket description.
source
enum
optional, default manual — one of zendesk, intercom, linear, jira, github, sentry, slack, manual, webhook.
kind
enum
optional, default bug — one of bug, feature_request, support, question, unknown.
reporter
string?
optional — name or handle of whoever filed it.
repo_label
string
optional, default "default" — repo URL, owner/repo, or SSH form.
Full session detail: current status, the PR draft (if any), per-session config, post-PR pipeline results, and clone metadata. Powers the product UI's session view.
Grant or deny a pending approval. The policy engine pauses sensitive actions (writes in sensitive sessions, deletes, dependency changes) here until a human decides.
Action ids currently awaiting a human decision, across all sessions.
Response · 200
{
"action_ids": ["act_3b7f", "act_91ae"]
}
Group
Live updates
Stream the agent loop live, or replay it from the append-only audit log.
WS/api/stream/{session_id}requires X-API-Key*
Live WebSocket feed of audit events for one session. On connect, replays every event so far, then streams new ones as the agent loop progresses (planner → policy → executor → observer → critic → memory).
* the auth middleware only gates /api/ HTTP requests today; treat the session id itself as the access boundary for this stream.
Snapshot of whether this deployment is ready to push a real PR (real LLM configured, GitHub token present, not forced into mock mode). Never returns secrets — token presence is a boolean.
Per-ticket observability snapshot from the queue's live budget counters: token usage, call counts, multi-step cycles, subagent depth, wall time, and cost-ceiling state. Returns 404 if the ticket isn't in the queue. For replayable history, use /api/audit/{'{session_id}'} instead.
Status snapshot of every configured connector (GitHub, CI, preview deploy, merge observer). Connectors observe your existing infra — they never own it.
The customer-facing contract consumed by the embeddable widget (widget.js). Deliberately narrow — no internals, no diffs, no audit ids.
GET/api/widget/sessions/{session_id}/digestopen
Customer-safe progress view of a session, translated into a human-friendly phase and message. This is the one contract stability matters most for — customers may write code against these field names.