RAZIEL.docs

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/sessions

Query parameters:

ParameterTypeDescription
projectIdstringFilter 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/sessions

Body:

FieldTypeRequiredDescription
agentstringYesclaude-code, codex, or opencode
promptstringNoInitial prompt sent to the agent
projectIdstringNoLink to an existing project (enables repo + context)
branchstringNoBase branch to clone (defaults to project default branch)
repoFullNamestringNoOverride which project repo to clone
repoClonePathstringNoOverride 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/:id

Response includes session and repos (the project's repo list, primary first).

Pause / resume a session

PATCH /api/sessions/:id

Body:

FieldTypeDescription
action"pause" | "resume"Pause saves sandbox state (no TTL); resume restores it

Stop a session

DELETE /api/sessions/:id

Permanently kills the sandbox and marks the session stopped. Irreversible.


Get diff

GET /api/sessions/:id/diff

Returns git diff HEAD of the sandbox workspace.

Response: { "diff": "<unified diff string>" }

Push to GitHub

POST /api/sessions/:id/push

Commits all staged changes in the sandbox and pushes to a branch on GitHub, then opens a pull request.

Body:

FieldTypeDefaultDescription
branchstringsession workBranchBranch name to push to
baseBranchstringproject default branchPR base branch
commitMessagestringFirst line of promptGit commit message
prTitlestringcommitMessagePull request title
prBodystringAuto-generatedPull request body
openPrbooleantrueWhether to open a PR after push
clonePathstringprimary repoMulti-repo: which repo to push

Returns { branch, pushed, prUrl, prNumber, headSha, repoFullName }.

Pull from GitHub

POST /api/sessions/:id/git-pull

Runs git fetch --all --prune && git pull --ff-only inside the sandbox.

Response: { output, error }

Fork a session

POST /api/sessions/:id/fork

Snapshots 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/clone

Starts 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 link

Share 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)generation

Response: { summary: string | null, summaryAt: string | null }

Get timeline

GET /api/sessions/:id/timeline

Returns all persisted chat messages with relative timestamps and tool-use annotations.

Response: { messages: EnrichedMessage[], sessionStart, sessionEnd }


Projects

List projects

GET /api/projects

Create a project

POST /api/projects

Body:

FieldTypeRequiredDescription
namestringYesDisplay name
repoFullNamestringYesowner/repo
repoUrlstringYesHTTPS clone URL
defaultBranchstringNoDefault: main
descriptionstringNoProject description
isPrivatebooleanNoDefault: false
buildAgentstringNoAgent for the initial build
instructionsstringNoAGENTS.md prose (max 10,000 chars)
skillsarrayNo[{ name, description? }]
pluginsarrayNo[{ name, source? }]
mcpsarrayNo[{ name, url?, command?, env? }]
docsarrayNo[{ title, url }]
toolsarrayNo[{ name, enabled }]
envarrayNo[{ key, value }] — project secrets
reposarrayNoMulti-repo: array of { repoFullName, repoUrl, defaultBranch? }
skipBuildbooleanNoSkip the initial build; sessions clone fresh

Returns 201 with { project, build }.

Get a project

GET /api/projects/:id

Returns { project, builds } (build history, newest first).

Update a project

PATCH /api/projects/:id

Updatable fields: name, description, defaultBranch, instructions, skills, plugins, mcps, docs, tools, sandboxSize, deployTarget, deployConfig.

Delete a project

DELETE /api/projects/:id

Returns 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 repo

Project secrets

GET    /api/projects/:id/secrets              # list (hints only, not values)
POST   /api/projects/:id/secrets              # create
DELETE /api/projects/:id/secrets/:secretId    # delete

Trigger a project build

POST /api/projects/:id/build

Queues 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/deploy

Triggers 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/templates

Returns own templates plus public templates in the same org scope.

Create a template

POST /api/templates

Body:

FieldTypeRequiredDescription
namestringYesTemplate display name
agentstringYesAgent identifier
descriptionstringNoOptional description
systemPromptstringNoCustom system prompt injected at session start
envVarsobjectNoKey/value env vars pre-set for sessions
isPublicbooleanNoVisible to all members of the org

Get / update / delete a template

GET    /api/templates/:id
PATCH  /api/templates/:id
DELETE /api/templates/:id

Launch a session from a template

POST /api/templates/:id/launch

Creates 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/prompts

Body: { title, content, tags?, agent?, isPublic? }

Get / update / delete a prompt

GET    /api/prompts/:id
PATCH  /api/prompts/:id
DELETE /api/prompts/:id

Record prompt usage

POST /api/prompts/:id/use

Increments 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

EventFired when
session.startedA new session is created
session.completedThe agent exits cleanly
session.failedThe agent exits with an error

List webhooks

GET /api/webhooks/raziel

Create a webhook

POST /api/webhooks/raziel

Body:

FieldTypeRequiredDescription
namestringYesDisplay name
urlstringYesHTTPS endpoint to POST to
eventsstring[]NoDefault: ["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/:id

Test a webhook

POST /api/webhooks/raziel/:id/test

Sends a test ping to the webhook URL and records the result in lastPingAt / lastPingOk.


Analytics

GET /api/analytics

Returns 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.


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" }
StatusMeaning
400Bad request — missing or invalid field
401Unauthenticated — no valid Clerk session
402Budget exceeded — monthly limit reached
404Not found (also used for unauthorised resource access)
409Conflict — e.g. pausing a session that is not running
502Upstream error — sandbox or GitHub API failure
API Reference · Raziel