API Reference

Sesame provides a REST API for programmatic access to all features. The API is built with Hono and runs on port 13531.

Base URL

http://localhost:13531/api

If you're accessing remotely, use your deployment URL:

https://your-domain.com/api

Authentication

By default, no authentication is required. If AUTH_PASSWORD is set, all endpoints require HTTP Basic Auth:

curl -u ":your-password" \
  http://localhost:13531/api/session

Any username is accepted — only the password must match. See Settings > Authentication for details.

Endpoints

Health

`GET /api/health`

Check server health status.

Response:

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Sessions

`GET /api/session`

List all sessions.

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `processing`, `completed`, `error`, `stopped`
`limit`	number	Max results (default: 50)
`offset`	number	Pagination offset

Response:

[
  {
    "id": "abc123",
    "title": "Add authentication",
    "status": "completed",
    "selectedAgent": "claude",
    "repoUrl": "https://github.com/owner/repo",
    "branchName": "sesame/abc123",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:15:00.000Z"
  }
]

`POST /api/session`

Create a new session.

Request Body:

{
  "prompt": "Add user authentication with JWT",
  "repoUrl": "https://github.com/owner/repo",
  "selectedAgent": "claude"
}

Response:

{
  "id": "abc123",
  "status": "pending"
}

`GET /api/session/status`

Get bulk session status. Returns a map of session IDs to their current status.

`GET /api/session/:sessionId`

Get details for a specific session.

Response:

{
  "id": "abc123",
  "title": "Add authentication",
  "prompt": "Add user authentication with JWT",
  "status": "processing",
  "selectedAgent": "claude",
  "repoUrl": "https://github.com/owner/repo",
  "branchName": "sesame/abc123",
  "progress": 45,
  "createdAt": "2025-01-15T10:00:00.000Z"
}

`PATCH /api/session/:sessionId`

Update a session (e.g. title).

`DELETE /api/session/:sessionId`

Delete a session (soft delete).

`POST /api/session/:sessionId/abort`

Abort a running session.

`POST /api/session/:sessionId/prompt_async`

Continue or resume a session with a follow-up prompt.

`GET /api/session/:sessionId/message`

Get all messages and parts for a session.

Response:

[
  {
    "info": {
      "id": "msg_1",
      "sessionId": "abc123",
      "role": "user",
      "timeCreated": 1705312800000,
      "content": "Add user authentication with JWT"
    },
    "parts": []
  },
  {
    "info": {
      "id": "msg_2",
      "sessionId": "abc123",
      "role": "assistant",
      "timeCreated": 1705312805000,
      "modelId": "claude-sonnet-4-5",
      "tokensInput": 1200,
      "tokensOutput": 3400
    },
    "parts": [
      {
        "id": "p_1",
        "sessionId": "abc123",
        "messageId": "msg_2",
        "type": "text",
        "text": "I'll implement JWT authentication..."
      },
      {
        "id": "p_2",
        "sessionId": "abc123",
        "messageId": "msg_2",
        "type": "tool",
        "callId": "tc_1",
        "tool": "Write",
        "state": {
          "status": "completed",
          "input": "{\"path\": \"auth.ts\"}",
          "output": "File written successfully",
          "timeStarted": 1705312806000,
          "timeCompleted": 1705312810000
        }
      }
    ]
  }
]

`POST /api/session/:sessionId/message`

Create a new message in a session.

`POST /api/session/:sessionId/clear-logs`

Clear all messages and parts for a session.

`GET /api/session/:sessionId/stream`

Stream session output via Server-Sent Events (SSE).

Response: SSE stream using SessionEvent objects. Each event uses its type field as the SSE event name:

Event Type	Description
`message.updated`	Message metadata created or updated (contains `info: Message`)
`message.part.updated`	Part content created or updated (contains `part: Part`, optional `delta: string`)
`message.removed`	Message removed from session
`message.part.removed`	Part removed from message
`session.updated`	Session status change (contains `sessionId`, `status`, optional `error`)
`log`	Log entry from session execution (`logType`: info, command, error, success)
`ping`	Keepalive signal (every 30 seconds)

On reconnect, the server replays all messages and parts from the database. Clients de-duplicate by part ID.

event: session.updated
data: {"type":"session.updated","sessionId":"abc123","status":"processing"}

event: log
data: {"type":"log","sessionId":"abc123","logType":"info","message":"Cloning repository..."}

event: message.updated
data: {"type":"message.updated","info":{"id":"msg_2","sessionId":"abc123","role":"assistant","timeCreated":1705312805000}}

event: message.part.updated
data: {"type":"message.part.updated","part":{"id":"p_1","sessionId":"abc123","messageId":"msg_2","type":"text","text":"I'll add JWT auth..."},"delta":"I'll add JWT auth..."}

event: message.part.updated
data: {"type":"message.part.updated","part":{"id":"p_2","sessionId":"abc123","messageId":"msg_2","type":"tool","callId":"tc_1","tool":"Write","state":{"status":"running","input":"{\"path\":\"auth.ts\"}","timeStarted":1705312806000}}}

event: session.updated
data: {"type":"session.updated","sessionId":"abc123","status":"completed"}

event: ping
data: keepalive

`GET /api/session/:sessionId/files`

Browse files in the session sandbox.

`GET /api/session/:sessionId/terminal`

Access terminal output for a session.

Settings

`GET /api/settings`

Get current settings.

Response:

{
  "settings": {
    "ai.model": "gpt-5-nano",
    "ai.baseUrl": "https://api.openai.com/v1"
  }
}

`PUT /api/settings/:key`

Set a specific setting.

Request Body:

{
  "value": "claude-haiku-4-5"
}

`DELETE /api/settings/:key`

Delete a specific setting (reverts to default).

Error Responses

All errors follow the RFC 7807 Problem Details format:

{
  "type": "urn:sesame:error:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Session not found"
}

Field	Type	Description
`type`	`string`	URN identifying the error type (stable, machine-readable)
`title`	`string`	Short human-readable summary
`status`	`number`	HTTP status code
`detail`	`string`	Human-readable explanation of this specific occurrence

Error type URNs:

Type	HTTP Status	Description
`urn:sesame:error:bad-request`	400	Invalid request data
`urn:sesame:error:unauthorized`	401	Not authenticated
`urn:sesame:error:forbidden`	403	Not authorized for this action
`urn:sesame:error:not-found`	404	Resource not found
`urn:sesame:error:conflict`	409	Resource conflict
`urn:sesame:error:gone`	410	Resource no longer available
`urn:sesame:error:payload-too-large`	413	Request payload too large
`urn:sesame:error:unprocessable-entity`	422	Valid request but cannot process
`urn:sesame:error:internal-error`	500	Server error

Sesame does not have application-level rate limiting. For production deployments, configure rate limiting at your reverse proxy (nginx, Caddy, Cloudflare, etc.). See Reverse Proxies for configuration examples.

WebSocket / SSE

Real-time features use Server-Sent Events (SSE) rather than WebSockets:

Session streaming: GET /api/session/:sessionId/stream
Terminal output: GET /api/session/:sessionId/terminal/stream

SSE provides simpler proxy configuration and automatic reconnection. On reconnect, the server replays all messages and parts from the database. Clients de-duplicate by part ID. All session events use a SessionEvent schema discriminated by type — the frontend doesn't need to know which agent provider produced the output.

On this page