API Reference
Complete REST API reference for Raziel — sessions, projects, templates, prompts, webhooks, analytics, and more.
Try the interactive API Explorer — browse every endpoint with live schemas, parameters, and examples, generated from the OpenAPI spec.
The full OpenAPI 3.1 spec is available at /api/openapi and can be imported into Postman, Insomnia, or any OpenAPI-compatible client.
Authentication
All endpoints require a valid Clerk session token. Include it as a cookie (set automatically by the browser) or pass the Authorization: Bearer <token> header when calling from server-side code.
Unauthenticated requests return 401 Unauthorized. Requests that reference resources belonging to another user/org return 404 Not Found (never 403 — this prevents resource enumeration).
Sessions
List sessions
GET /api/sessionsQuery parameters:
| Parameter | Type | Description |
|---|---|---|
projectId | string | Filter sessions to a single project |
Response:
{
"sessions": [
{
"id": "uuid",
"agent": "claude-code",
"status": "running",
"prompt": "Add dark mode support",
"workBranch": "raziel/alice/add-dark-mode-abc123",
"startedAt": "2025-01-01T00:00:00.000Z"
}
]
}Create a session
POST /api/sessionsBody:
| Field | Type | Required | Description |
|---|---|---|---|
agent | string | Yes | claude-code, codex, or opencode |
prompt | string | No | Initial prompt sent to the agent |
projectId | string | No | Link to an existing project (enables repo + context) |
branch | string | No | Base branch to clone (defaults to project default branch) |
repoFullName | string | No | Override which project repo to clone |
repoClonePath | string | No | Override by clone path (multi-repo projects) |
Returns 201 with { session, warning? }. Returns 402 if the monthly budget is exceeded.
Example request:
{
"agent": "claude-code",
"prompt": "Refactor the auth module to use Clerk",
"projectId": "clx1234abc"
}Example response:
{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"sandboxId": "xyz789abc",
"agent": "claude-code",
"status": "running",
"workBranch": "raziel/alice/refactor-auth-550e",
"startedAt": "2025-01-01T12:00:00.000Z"
}
}Get a session
GET /api/sessions/:idResponse includes session and repos (the project's repo list, primary first).
Pause / resume a session
PATCH /api/sessions/:idBody:
| Field | Type | Description |
|---|---|---|
action | "pause" | "resume" | Pause saves sandbox state (no TTL); resume restores it |
Stop a session
DELETE /api/sessions/:idPermanently kills the sandbox and marks the session stopped. Irreversible.
Get diff
GET /api/sessions/:id/diffReturns git diff HEAD of the sandbox workspace.
Response: { "diff": "<unified diff string>" }
Push to GitHub
POST /api/sessions/:id/pushCommits all staged changes in the sandbox and pushes to a branch on GitHub, then opens a pull request.
Body:
| Field | Type | Default | Description |
|---|---|---|---|
branch | string | session workBranch | Branch name to push to |
baseBranch | string | project default branch | PR base branch |
commitMessage | string | First line of prompt | Git commit message |
prTitle | string | commitMessage | Pull request title |
prBody | string | Auto-generated | Pull request body |
openPr | boolean | true | Whether to open a PR after push |
clonePath | string | primary repo | Multi-repo: which repo to push |
Returns { branch, pushed, prUrl, prNumber, headSha, repoFullName }.
Pull from GitHub
POST /api/sessions/:id/git-pullRuns git fetch --all --prune && git pull --ff-only inside the sandbox.
Response: { output, error }
Fork a session
POST /api/sessions/:id/forkSnapshots the source sandbox (preserving its working tree and uncommitted changes), then boots a new session from that snapshot. The fork starts from where the source left off.
Returns 201 with { session }.
Clone a session
POST /api/sessions/:id/cloneStarts a brand-new sandbox with the same prompt and project but no inherited working tree. This is "replay from scratch" — unlike fork, which continues from the current state.
Returns 201 with { session }.
Share a session
GET /api/sessions/:id/share # get share status
POST /api/sessions/:id/share # enable sharing (idempotent)
DELETE /api/sessions/:id/share # revoke share linkShare generates a public token that allows read-only access at /share/:token.
Get AI summary
GET /api/sessions/:id/summary # get cached summary
POST /api/sessions/:id/summary # trigger (re)generationResponse: { summary: string | null, summaryAt: string | null }
Get timeline
GET /api/sessions/:id/timelineReturns all persisted chat messages with relative timestamps and tool-use annotations.
Response: { messages: EnrichedMessage[], sessionStart, sessionEnd }
Projects
List projects
GET /api/projectsCreate a project
POST /api/projectsBody:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name |
repoFullName | string | Yes | owner/repo |
repoUrl | string | Yes | HTTPS clone URL |
defaultBranch | string | No | Default: main |
description | string | No | Project description |
isPrivate | boolean | No | Default: false |
buildAgent | string | No | Agent for the initial build |
instructions | string | No | AGENTS.md prose (max 10,000 chars) |
skills | array | No | [{ name, description? }] |
plugins | array | No | [{ name, source? }] |
mcps | array | No | [{ name, url?, command?, env? }] |
docs | array | No | [{ title, url }] |
tools | array | No | [{ name, enabled }] |
env | array | No | [{ key, value }] — project secrets |
repos | array | No | Multi-repo: array of { repoFullName, repoUrl, defaultBranch? } |
skipBuild | boolean | No | Skip the initial build; sessions clone fresh |
Returns 201 with { project, build }.
Get a project
GET /api/projects/:idReturns { project, builds } (build history, newest first).
Update a project
PATCH /api/projects/:idUpdatable fields: name, description, defaultBranch, instructions, skills, plugins, mcps, docs, tools, sandboxSize, deployTarget, deployConfig.
Delete a project
DELETE /api/projects/:idReturns 204 No Content.
Project repos
GET /api/projects/:id/repos # list repos
POST /api/projects/:id/repos # add a repo
DELETE /api/projects/:id/repos/:repoId # remove a repoProject secrets
GET /api/projects/:id/secrets # list (hints only, not values)
POST /api/projects/:id/secrets # create
DELETE /api/projects/:id/secrets/:secretId # deleteTrigger a project build
POST /api/projects/:id/buildQueues a new build that clones the repo, installs dependencies, and snapshots the sandbox. New sessions will boot from the latest ready snapshot.
Deploy a project
POST /api/projects/:id/deployTriggers a deployment to the configured target (Vercel or Fly.io). Requires deployTarget and deployConfig to be set on the project.
Templates
Templates let you save a reusable agent configuration (system prompt, env vars) and launch sessions from them.
List templates
GET /api/templatesReturns own templates plus public templates in the same org scope.
Create a template
POST /api/templatesBody:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Template display name |
agent | string | Yes | Agent identifier |
description | string | No | Optional description |
systemPrompt | string | No | Custom system prompt injected at session start |
envVars | object | No | Key/value env vars pre-set for sessions |
isPublic | boolean | No | Visible to all members of the org |
Get / update / delete a template
GET /api/templates/:id
PATCH /api/templates/:id
DELETE /api/templates/:idLaunch a session from a template
POST /api/templates/:id/launchCreates a new session pre-configured with the template's agent, system prompt, and env vars.
Prompts
The prompt library stores reusable prompts you can paste into any session.
List prompts
GET /api/prompts?q=<search>&tag=<tag>Create a prompt
POST /api/promptsBody: { title, content, tags?, agent?, isPublic? }
Get / update / delete a prompt
GET /api/prompts/:id
PATCH /api/prompts/:id
DELETE /api/prompts/:idRecord prompt usage
POST /api/prompts/:id/useIncrements the useCount counter for tracking frequently used prompts.
Webhooks
Raziel fires webhooks on session lifecycle events. Delivery is signed with HMAC-SHA256 using the webhook secret.
Supported events
| Event | Fired when |
|---|---|
session.started | A new session is created |
session.completed | The agent exits cleanly |
session.failed | The agent exits with an error |
List webhooks
GET /api/webhooks/razielCreate a webhook
POST /api/webhooks/razielBody:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name |
url | string | Yes | HTTPS endpoint to POST to |
events | string[] | No | Default: ["session.completed"] |
The response includes a secret field — this is the HMAC signing key shown only once.
Update / delete a webhook
PATCH /api/webhooks/raziel/:id
DELETE /api/webhooks/raziel/:idTest a webhook
POST /api/webhooks/raziel/:id/testSends a test ping to the webhook URL and records the result in lastPingAt / lastPingOk.
Analytics
GET /api/analyticsReturns usage statistics for the last 30 days:
{
"totalSessions": 42,
"totalCost": 3.14,
"totalTokens": 1500000,
"avgDurationMs": 240000,
"byAgent": [{ "agent": "claude-code", "count": 30, "cost": 2.50 }],
"byDay": [{ "date": "2025-01-01", "count": 5 }],
"statusBreakdown": { "completed": 35, "errored": 2, "running": 3, "stopped": 2 },
"topByCost": [...]
}Budget
GET /api/budget # current month spend vs. limit
PATCH /api/budget # update limit: { "budgetUsd": 50 }Set budgetUsd to null to remove the limit. New sessions return 402 when the limit is exceeded.
Search
GET /api/search?q=<query>Full-text search across session prompts, agent types, chat message content, and project names. Returns up to 20 sessions with matched message previews.
Errors
All error responses follow a consistent shape:
{ "error": "Human-readable message" }| Status | Meaning |
|---|---|
400 | Bad request — missing or invalid field |
401 | Unauthenticated — no valid Clerk session |
402 | Budget exceeded — monthly limit reached |
404 | Not found (also used for unauthorised resource access) |
409 | Conflict — e.g. pausing a session that is not running |
502 | Upstream error — sandbox or GitHub API failure |