Agent Sessions API - Allternit Docs

Overview

Agent sessions are conversation threads backed by the Gizzi runtime on your data-plane node. The public path is on the Cloud API: it authenticates the Clerk session, resolves your default healthy node, and relays the request to Allternit API. Session rows live in that node’s SQLite, not in Cloud API Postgres. The node translates the session contract (/api/v1/agent-sessions) into the Gizzi runtime contract (/v1/session/*). Sessions support messages, abort, revert/unrevert, compaction, ephemeral incognito chats, and real-time event synchronization via SSE.

HTTP 428 means this account has no healthy paired or provisioned node. Pair a desktop/VPS or start a provisioned instance, then retry.

Base URL

https://api.allternit.com/api/v1

Local data plane (same machine only): http://127.0.0.1:8013/api/v1.

Authentication

All production requests must include a Clerk session JWT in the Authorization header. The Cloud API forwards that header to the node. Gizzi-specific Basic auth is handled internally on the node when GIZZI_PASSWORD / GIZZI_SERVER_PASSWORD is configured.

Session object

Field	Type	Description
`id`	string	Session UUID.
`name`	string \| null	Session title.
`description`	null	Reserved for future use.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 update timestamp.
`last_accessed`	string	Same as `updated_at`.
`message_count`	integer	Always `0` in list responses; use messages endpoints for counts.
`active`	boolean	`true` unless the session is archived.
`tags`	array	Always empty in current responses.
`metadata`	object	Runtime metadata including `project_id`, `directory`, `agent_id`, `surface`, `originSurface`, `permission`, and `ephemeral`.

Endpoints

List sessions

GET /api/v1/agent-sessions

Returns sessions owned by the caller, filtered and searched on the gateway side. Ephemeral sessions are excluded from the list.

Query parameters

Parameter	Type	Description
`surface`	string	Filter by original surface (`chat`, `cowork`, `code`, `browser`, `design`).
`project_id`	string	Filter by cowork project ID.
`q`	string	Case-insensitive substring search over title and message content.

Example request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.allternit.com/api/v1/agent-sessions?surface=chat&q=auth"

Example response

{
  "sessions": [
    {
      "id": "sess_9c1d...",
      "name": "Auth module review",
      "description": null,
      "created_at": "2026-08-13T14:00:00Z",
      "updated_at": "2026-08-13T14:22:00Z",
      "last_accessed": "2026-08-13T14:22:00Z",
      "message_count": 0,
      "active": true,
      "tags": [],
      "metadata": {
        "project_id": "proj_4d5e...",
        "directory": null,
        "version": null,
        "agent_id": "agent_018f3a7c...",
        "surface": "chat",
        "originSurface": "chat",
        "permission": null,
        "ephemeral": false
      }
    }
  ],
  "count": 1
}

Create a session

POST /api/v1/agent-sessions

Creates a new Gizzi session. The gateway stamps the default model, resolves the agent harness config, and records the original surface so it can be restored later.

Request body

Field	Type	Required	Description
`name`	string	No	Session title. Defaults to `New Session`.
`agent_id`	string	No	Bind the session to an agent.
`agent_name`	string	No	Ignored by the server.
`origin_surface`	string	No	Original surface (`chat`, `cowork`, `code`, `browser`, `design`).
`ephemeral`	boolean	No	If `true`, the session is hidden from lists and deleted on abort.
`metadata`	object	No	Bag carried by clients. `metadata.surface`, `metadata.projectId`, and `metadata.project_id` are read by the gateway.
`project_id`	string	No	Project the session belongs to (top-level form used by the web client).
`model`	object	No	Optional model reference stamped on the session.

Example request

curl -X POST https://api.allternit.com/api/v1/agent-sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auth module review",
    "agent_id": "agent_018f3a7c...",
    "origin_surface": "code",
    "metadata": {
      "projectId": "proj_4d5e...",
      "surface": "code"
    }
  }'

Example response

{
  "id": "sess_9c1d...",
  "name": "Auth module review",
  "description": null,
  "created_at": "2026-08-13T14:00:00Z",
  "updated_at": "2026-08-13T14:00:00Z",
  "last_accessed": "2026-08-13T14:00:00Z",
  "message_count": 0,
  "active": true,
  "tags": [],
  "metadata": {
    "project_id": "proj_4d5e...",
    "directory": null,
    "version": null,
    "agent_id": "agent_018f3a7c...",
    "surface": "chat",
    "originSurface": "code",
    "permission": null,
    "ephemeral": false
  }
}

The surface design is normalized to chat for Gizzi compatibility; the original value is preserved in metadata.originSurface.

Get a session

GET /api/v1/agent-sessions/:id

Example request

curl -H "Authorization: Bearer $TOKEN" \
  https://api.allternit.com/api/v1/agent-sessions/sess_9c1d...

Example response

Same shape as the create response.

Update a session

PATCH /api/v1/agent-sessions/:id

Updates the session title, archived state, permission, or surface.

Request body

Field	Type	Description
`name`	string	New title.
`active`	boolean	`false` archives the session.
`origin_surface`	string	New original surface.
`metadata.permission`	object	Permission policy.

Example request

curl -X PATCH https://api.allternit.com/api/v1/agent-sessions/sess_9c1d... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renamed session",
    "active": false
  }'

Example response

Same shape as the create response, with active: false.

Delete a session

DELETE /api/v1/agent-sessions/:id

Deletes the backing Gizzi session and clears any local ephemeral flag.

Example response

204 No Content

List messages

GET /api/v1/agent-sessions/:id/messages

Returns the session’s messages in gateway-normalized form.

Example response

[
  {
    "id": "msg_1a2b...",
    "role": "user",
    "content": "Review the auth module",
    "thinking": null,
    "timestamp": "2026-08-13T14:01:00Z",
    "metadata": {
      "agent": null,
      "model": null,
      "parts": [{ "type": "text", "text": "Review the auth module" }],
      "error": null
    }
  },
  {
    "id": "msg_2c3d...",
    "role": "assistant",
    "content": "I found a potential issue...",
    "thinking": "Let me check the auth routes first...",
    "timestamp": "2026-08-13T14:01:05Z",
    "metadata": {
      "agent": "agent_018f3a7c...",
      "model": { "providerID": "ollama", "modelID": "qwen2.5:0.5b" },
      "parts": [
        { "type": "text", "text": "I found a potential issue..." },
        { "type": "reasoning", "text": "Let me check the auth routes first..." }
      ],
      "error": null
    }
  }
]

Send a message

POST /api/v1/agent-sessions/:id/messages

Sends a message to the session. role: "user" messages are forwarded to the runtime. role: "assistant" with noReply: true stores a static assistant message without a model turn (a bot’s greeting in its new main chat); it is labelled with metadata.source and stored once per session and source, however many clients post it. Other roles are accepted locally and echoed back immediately.

Request body

Field	Type	Required	Description
`text`	string	Yes	Message text.
`role`	string	No	Defaults to `user`.
`thinking`	string	No	Explicit reasoning text.
`metadata`	object	No	May include `model` with `providerID`/`modelID` to override the brain. For a stored assistant message, `source` labels it (for example `bot-greeting`).
`noReply`	boolean	No	Record the message without starting a model turn.
`source`	string	No	Where the text was typed (for example `aci`); stored on the text part’s metadata.

Example request

curl -X POST https://api.allternit.com/api/v1/agent-sessions/sess_9c1d.../messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Review the auth module",
    "metadata": {
      "model": { "providerID": "ollama", "modelID": "qwen2.5:0.5b" }
    }
  }'

Example response

Same shape as a message from list messages.

Abort a session

POST /api/v1/agent-sessions/:id/abort

Aborts the current turn. For ephemeral sessions, this also hard-deletes the backing session and clears the ephemeral flag.

Example response

{
  "success": true
}

Revert a session

POST /api/v1/agent-sessions/:id/revert

Reverts file changes made during the session back to a given message.

Request body

Field	Type	Required	Description
`messageId`	string	Yes	Message ID to revert to.

Example response

Same shape as get session.

Unrevert a session

POST /api/v1/agent-sessions/:id/unrevert

Undoes a prior revert.

Example response

Same shape as get session.

Compact a session

POST /api/v1/agent-sessions/:id/compact

On-demand context condensation via Gizzi’s summarize endpoint.

Example response

{
  "summary": "The session discussed auth module security..."
}

Sync sessions (SSE)

GET /api/v1/agent-sessions/sync

Opens a server-sent event stream that forwards Gizzi bus events in a frontend-friendly shape. Supports Last-Event-ID reconnection.

Supported event types

Type	Description
`created`	A session was created.
`updated`	A session was updated or archived.
`deleted`	A session was deleted.
`message_added`	A new message completed.
`permission_asked`	The runtime is asking for permission.
`permission_replied`	A permission request was answered.
`question_asked`	The runtime asked a clarifying question.
`part_updated`	A message part was updated.
`part_delta`	A streaming delta for a message part.
`part_removed`	A message part was removed.

Example curl

curl -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  https://api.allternit.com/api/v1/agent-sessions/sync

Example event

event: message
data: {"type":"message_added","session_id":"sess_9c1d...","id":"msg_2c3d...","role":"assistant","content":"I found a potential issue..."}

Additional routes

These routes are registered by the same router on the Allternit API node. See the code in cmd/allternit-api/src/agent_session_routes.rs for request shapes.

Method	Path	Purpose
`GET`	`/api/v1/agent-sessions/:id/status`	Session status.
`POST`	`/api/v1/agent-sessions/:id/resume`	Resume a session.
`POST`	`/api/v1/agent-sessions/:id/handoff`	Hand a session off.
`GET`	`/api/v1/agent-sessions/:id/lineage`	Session lineage.
`POST`	`/api/v1/agent-sessions/:id/fetch-origin`	Fetch the native origin of an imported session.
`GET`	`/api/v1/agent-sessions/:id/origin`	Read the native origin.
`POST`	`/api/v1/agent-sessions/:id/export-native`	Export to a native harness session.
`GET`	`/api/v1/questions`	List pending runtime questions.
`POST`	`/api/v1/questions/:id/reply`	Answer a question.
`POST`	`/api/v1/questions/:id/reject`	Reject a question.
`POST`	`/api/v1/permissions/:id/reply`	Answer a permission request.
`GET`	`/api/v1/native-sessions/harnesses`	List native harnesses.
`GET`	`/api/v1/native-sessions`	List native sessions.
`POST`	`/api/v1/native-sessions/pickup`	Pick up a native session.
`POST`	`/api/v1/native-sessions/spawn`	Spawn a native session.
`GET`	`/api/v1/native-sessions/:harness/:id`	Show a native session.

Error codes

Status	Meaning
`200`	Success.
`201`	Created.
`204`	No content.
`400`	Bad request.
`401`	Unauthorized.
`403`	Forbidden — agent not enabled for the requested surface.
`404`	Session not found.
`502`	Bad gateway — Gizzi runtime error.
`500`	Internal server error.

​Overview

​Base URL

​Authentication

​Session object

​Endpoints

​List sessions

​Query parameters

​Example request

​Example response

​Create a session

​Request body

​Example request

​Example response

​Get a session

​Example request

​Example response

​Update a session

​Request body

​Example request

​Example response

​Delete a session

​Example response

​List messages

​Example response

​Send a message

​Request body

​Example request

​Example response

​Abort a session

​Example response

​Revert a session

​Request body

​Example response

​Unrevert a session

​Example response

​Compact a session

​Example response

​Sync sessions (SSE)

​Supported event types

​Example curl

​Example event

​Additional routes

​Error codes

​Related pages

Overview

Base URL

Authentication

Session object

Endpoints

List sessions

Query parameters

Example request

Example response

Create a session

Request body

Example request

Example response

Get a session

Example request

Example response

Update a session

Request body

Example request

Example response

Delete a session

Example response

List messages

Example response

Send a message

Request body

Example request

Example response

Abort a session

Example response

Revert a session

Request body

Example response

Unrevert a session

Example response

Compact a session

Example response

Sync sessions (SSE)

Supported event types

Example curl

Example event

Additional routes

Error codes

Related pages