RAZIEL.docs
API Explorer

Sessions

AI agent sandbox sessions — lifecycle, git operations, sharing, and history

List sessions

Returns up to 50 sessions for the authenticated scope, ordered by start time descending.

GET
/api/sessions
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Query Parameters

projectId?string

Filter sessions to a single project

Response Body

curl -X GET "https://app.raziel.fun/api/sessions?projectId=string"
{
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "string",
      "orgId": "string",
      "projectId": "string",
      "sandboxId": "xyz789abc",
      "agent": "claude-code",
      "image": "raziel-agents",
      "prompt": "Refactor the auth module",
      "repoUrl": "https://github.com/owner/repo.git",
      "branch": "main",
      "workBranch": "raziel/alice/refactor-auth-550e",
      "prNumber": 0,
      "prUrl": "string",
      "headSha": "string",
      "status": "running",
      "snapshotName": "string",
      "agentStarted": true,
      "inputTokens": 10000,
      "outputTokens": 2500,
      "estimatedCostUsd": 0.0312,
      "exitCode": 0,
      "errorMessage": "string",
      "shareToken": "string",
      "sharedAt": "2019-08-24T14:15:22Z",
      "aiSummary": "string",
      "summaryAt": "2019-08-24T14:15:22Z",
      "forkedFromId": "string",
      "tags": [
        "auth",
        "refactor"
      ],
      "startedAt": "2019-08-24T14:15:22Z",
      "stoppedAt": "2019-08-24T14:15:22Z"
    }
  ]
}
{
  "error": "Unauthorized"
}

Create a session

Provisions a new E2B sandbox, optionally linked to a project with repo cloning and agent context. Returns 402 when the monthly budget is exceeded.

POST
/api/sessions
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

agentstring

Agent to run in the sandbox

Value in"claude-code" | "codex" | "opencode"
prompt?string

Initial prompt sent to the agent

projectId?string

Link to an existing project (enables repo cloning + agent context)

branch?string

Base branch to clone (defaults to project default branch)

repoFullName?string

Override which project repo to clone (multi-repo projects)

repoClonePath?string

Override by clone path (multi-repo projects)

snapshotName?string

E2B snapshot to boot from (overridden by project build snapshot)

Response Body

curl -X POST "https://app.raziel.fun/api/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "claude-code",
    "prompt": "Refactor the auth module to use Clerk",
    "projectId": "clx1234abc"
  }'
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "string",
    "orgId": "string",
    "projectId": "string",
    "sandboxId": "xyz789abc",
    "agent": "claude-code",
    "image": "raziel-agents",
    "prompt": "Refactor the auth module",
    "repoUrl": "https://github.com/owner/repo.git",
    "branch": "main",
    "workBranch": "raziel/alice/refactor-auth-550e",
    "prNumber": 0,
    "prUrl": "string",
    "headSha": "string",
    "status": "running",
    "snapshotName": "string",
    "agentStarted": true,
    "inputTokens": 10000,
    "outputTokens": 2500,
    "estimatedCostUsd": 0.0312,
    "exitCode": 0,
    "errorMessage": "string",
    "shareToken": "string",
    "sharedAt": "2019-08-24T14:15:22Z",
    "aiSummary": "string",
    "summaryAt": "2019-08-24T14:15:22Z",
    "forkedFromId": "string",
    "tags": [
      "auth",
      "refactor"
    ],
    "startedAt": "2019-08-24T14:15:22Z",
    "stoppedAt": "2019-08-24T14:15:22Z"
  },
  "warning": "string"
}
{
  "error": "Not found"
}
{
  "error": "Unauthorized"
}
{
  "error": "string",
  "spent": 0,
  "budget": 0
}
Empty

Get a session

Returns the session and its project repo list (primary first).

GET
/api/sessions/{id}
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X GET "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "string",
    "orgId": "string",
    "projectId": "string",
    "sandboxId": "xyz789abc",
    "agent": "claude-code",
    "image": "raziel-agents",
    "prompt": "Refactor the auth module",
    "repoUrl": "https://github.com/owner/repo.git",
    "branch": "main",
    "workBranch": "raziel/alice/refactor-auth-550e",
    "prNumber": 0,
    "prUrl": "string",
    "headSha": "string",
    "status": "running",
    "snapshotName": "string",
    "agentStarted": true,
    "inputTokens": 10000,
    "outputTokens": 2500,
    "estimatedCostUsd": 0.0312,
    "exitCode": 0,
    "errorMessage": "string",
    "shareToken": "string",
    "sharedAt": "2019-08-24T14:15:22Z",
    "aiSummary": "string",
    "summaryAt": "2019-08-24T14:15:22Z",
    "forkedFromId": "string",
    "tags": [
      "auth",
      "refactor"
    ],
    "startedAt": "2019-08-24T14:15:22Z",
    "stoppedAt": "2019-08-24T14:15:22Z"
  },
  "repos": [
    {
      "id": "string",
      "projectId": "string",
      "repoFullName": "owner/repo",
      "repoUrl": "https://github.com/owner/repo.git",
      "defaultBranch": "main",
      "clonePath": "repo",
      "isPrimary": true,
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Pause, resume, or update session status

Use action: pause|resume for sandbox lifecycle control. Use status: completed|failed for internal status updates from the session bridge.

PATCH
/api/sessions/{id}
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid
action?string
Value in"pause" | "resume"
status?string
Value in"completed" | "failed"
exitCode?integer
errorMessage?string

Response Body

curl -X PATCH "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "pause"
  }'
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "string",
    "orgId": "string",
    "projectId": "string",
    "sandboxId": "xyz789abc",
    "agent": "claude-code",
    "image": "raziel-agents",
    "prompt": "Refactor the auth module",
    "repoUrl": "https://github.com/owner/repo.git",
    "branch": "main",
    "workBranch": "raziel/alice/refactor-auth-550e",
    "prNumber": 0,
    "prUrl": "string",
    "headSha": "string",
    "status": "running",
    "snapshotName": "string",
    "agentStarted": true,
    "inputTokens": 10000,
    "outputTokens": 2500,
    "estimatedCostUsd": 0.0312,
    "exitCode": 0,
    "errorMessage": "string",
    "shareToken": "string",
    "sharedAt": "2019-08-24T14:15:22Z",
    "aiSummary": "string",
    "summaryAt": "2019-08-24T14:15:22Z",
    "forkedFromId": "string",
    "tags": [
      "auth",
      "refactor"
    ],
    "startedAt": "2019-08-24T14:15:22Z",
    "stoppedAt": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "Not found"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}
Empty

Stop a session

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

DELETE
/api/sessions/{id}
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X DELETE "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "ok": true
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Export session as Markdown

Returns the full conversation transcript as a downloadable Markdown file.

GET
/api/sessions/{id}/export
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X GET "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/export"
"string"
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Get share status

GET
/api/sessions/{id}/share
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X GET "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/share"
{
  "shared": true,
  "shareUrl": "https://app.raziel.fun/share/abc123"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Enable public sharing

Generates a public share token (idempotent — returns existing token if already shared).

POST
/api/sessions/{id}/share
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X POST "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/share"
{
  "shareUrl": "https://app.raziel.fun/share/abc123"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Removes the share token and disables public access.

DELETE
/api/sessions/{id}/share
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X DELETE "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/share"
{
  "ok": true
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Get session tags

GET
/api/sessions/{id}/tags
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X GET "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/tags"
{
  "tags": [
    "string"
  ]
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Update session tags

Replaces the full tag list. Maximum 10 tags, each up to 30 characters.

PATCH
/api/sessions/{id}/tags
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid
tagsarray<string>

Response Body

curl -X PATCH "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/tags" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "auth",
      "refactor"
    ]
  }'
{
  "tags": [
    "string"
  ]
}
{
  "error": "Not found"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Pull latest changes from GitHub

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

POST
/api/sessions/{id}/git-pull
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X POST "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/git-pull"
{
  "output": "string",
  "error": "string"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}
Empty

Fork a session

Snapshots the source sandbox (preserving working tree + uncommitted changes) and boots a new session from that snapshot. The fork continues from where the source left off.

POST
/api/sessions/{id}/fork
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X POST "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/fork"
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "string",
    "orgId": "string",
    "projectId": "string",
    "sandboxId": "xyz789abc",
    "agent": "claude-code",
    "image": "raziel-agents",
    "prompt": "Refactor the auth module",
    "repoUrl": "https://github.com/owner/repo.git",
    "branch": "main",
    "workBranch": "raziel/alice/refactor-auth-550e",
    "prNumber": 0,
    "prUrl": "string",
    "headSha": "string",
    "status": "running",
    "snapshotName": "string",
    "agentStarted": true,
    "inputTokens": 10000,
    "outputTokens": 2500,
    "estimatedCostUsd": 0.0312,
    "exitCode": 0,
    "errorMessage": "string",
    "shareToken": "string",
    "sharedAt": "2019-08-24T14:15:22Z",
    "aiSummary": "string",
    "summaryAt": "2019-08-24T14:15:22Z",
    "forkedFromId": "string",
    "tags": [
      "auth",
      "refactor"
    ],
    "startedAt": "2019-08-24T14:15:22Z",
    "stoppedAt": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}
Empty

Clone a session

Starts a brand-new sandbox with the same prompt and project but no inherited working tree — replay from scratch, unlike fork which continues from current state.

POST
/api/sessions/{id}/clone
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X POST "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/clone"
{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "string",
    "orgId": "string",
    "projectId": "string",
    "sandboxId": "xyz789abc",
    "agent": "claude-code",
    "image": "raziel-agents",
    "prompt": "Refactor the auth module",
    "repoUrl": "https://github.com/owner/repo.git",
    "branch": "main",
    "workBranch": "raziel/alice/refactor-auth-550e",
    "prNumber": 0,
    "prUrl": "string",
    "headSha": "string",
    "status": "running",
    "snapshotName": "string",
    "agentStarted": true,
    "inputTokens": 10000,
    "outputTokens": 2500,
    "estimatedCostUsd": 0.0312,
    "exitCode": 0,
    "errorMessage": "string",
    "shareToken": "string",
    "sharedAt": "2019-08-24T14:15:22Z",
    "aiSummary": "string",
    "summaryAt": "2019-08-24T14:15:22Z",
    "forkedFromId": "string",
    "tags": [
      "auth",
      "refactor"
    ],
    "startedAt": "2019-08-24T14:15:22Z",
    "stoppedAt": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}
Empty

Get sandbox diff

Returns git diff HEAD of the session's E2B sandbox workspace.

GET
/api/sessions/{id}/diff
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X GET "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/diff"
{
  "diff": "string"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Push changes and open a PR

Commits all staged changes in the sandbox, pushes to a branch on GitHub, and optionally opens a pull request. Requires the session to belong to a project with a connected repo.

POST
/api/sessions/{id}/push
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid
branch?string

Branch name to push to (defaults to session workBranch)

baseBranch?string

PR base branch (defaults to project default branch)

commitMessage?string

Git commit message (defaults to first line of prompt)

prTitle?string

Pull request title

prBody?string

Pull request body

openPr?boolean

Whether to open a PR after push

Defaulttrue
clonePath?string

Multi-repo: which repo to push (by clonePath)

repoFullName?string

Multi-repo: which repo to push (by full name)

Response Body

curl -X POST "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/push" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "branch": "string",
  "pushed": true,
  "prUrl": "string",
  "prNumber": 0,
  "headSha": "string",
  "repoFullName": "string",
  "error": "string"
}
{
  "error": "Not found"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}
Empty
Empty

Get session timeline

Returns all persisted chat messages with relative timestamps and tool-use annotations (name + input summary).

GET
/api/sessions/{id}/timeline
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X GET "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/timeline"
{
  "messages": [
    {
      "seq": 0,
      "kind": "user",
      "content": {},
      "relativeMs": 0,
      "toolName": "string",
      "toolInputSummary": "string"
    }
  ],
  "sessionStart": "2019-08-24T14:15:22Z",
  "sessionEnd": "2019-08-24T14:15:22Z"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Get AI summary

Returns the cached AI-generated summary of what the agent accomplished.

GET
/api/sessions/{id}/summary
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X GET "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/summary"
{
  "summary": "string",
  "summaryAt": "2019-08-24T14:15:22Z"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}

Trigger AI summary generation

Manually triggers (re)generation of the session summary using the chat transcript and diff.

POST
/api/sessions/{id}/summary
AuthorizationBearer <token>

Clerk session token. Automatically set as a cookie in the browser; pass as Authorization: Bearer for server-side calls.

In: header

Path Parameters

idstring
Formatuuid

Response Body

curl -X POST "https://app.raziel.fun/api/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/summary"
{
  "summary": "string",
  "summaryAt": "2019-08-24T14:15:22Z"
}
{
  "error": "Unauthorized"
}
{
  "error": "Not found"
}
Empty