Agent Chat API

Overview

The Agent Chat API forwards user messages to a live Gizzi Runtime session and streams the runtime’s event bus back to the caller. The chatId is the platform agent session id created through the agent-sessions flow; the platform simply proxies the payload, preserving provider, model, harness, and system prompt overrides.

This namespace is served by the Allternit API data-plane node (http://127.0.0.1:8013 on the same machine, or your paired or provisioned node). The hosted Cloud API at https://api.allternit.com does not route it; it relays only agent sessions, canvases, office and beta research/sessions. See Cloud API.

Base URL

http://127.0.0.1:8013/api

Authentication

All requests require a valid bearer token in the Authorization header. See Authentication for details.

Endpoints

Method	Path	Description
`POST`	`/agent-chat`	Send a message to a Gizzi Runtime session and stream the response.
`POST`	`/chat/action`	Acknowledge a chat-level action. The handler logs the body and returns `{"status":"ok"}`; it does not stop or regenerate anything.

Send a chat message

curl -N -X POST http://127.0.0.1:8013/api/agent-chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "sess_01hqx8x7x7x7x7x7x7x7x7x",
    "message": "Refactor the auth module into services.",
    "runtimeModelId": "qwen2.5:0.5b",
    "agentProvider": "ollama",
    "agentModel": "qwen2.5:0.5b",
    "agentName": "code-reviewer",
    "systemPrompt": "You are a senior engineer using Allternit-native terminology.",
    "harness": { "mode": "byok" }
  }'

Request body

Field	Type	Required	Description
`chatId`	string	yes	Platform agent session id (also the Gizzi session id).
`message`	string	yes	User message to forward. Optional when `resume` is set.
`runtimeModelId`	string	no	Model override for this turn.
`agentProvider`	string	no	Provider override for this turn.
`agentModel`	string	no	Model identifier override.
`agentName`	string	no	Agent name override.
`harness`	object	no	Harness configuration for the turn.
`runtimeEnv`	object	no	Map of string environment variables for the runtime.
`systemPrompt`	string	no	System prompt override, read from the flattened request context.
`attachments`	array	no	Images and files for this turn: `[{ "url"?: string, "dataBase64"?: string, "mediaType": string, "name"?: string }]`. `url` is a `data:` URL, an `https://` link (for example an Allternit Cloud file link) or an upload from `POST /api/v1/uploads`; a bare `dataBase64` is sent as a data URL. Each becomes a gizzi file part after the text, so image types reach the model as image input. At most 10 per message and 24 MB of inline data; other URL schemes are dropped. The request body may be up to 32 MB. The Desktop bridge `POST /api/v1/ai/chat` takes the same field.
`resume`	object	no	`{ "cursor": <number>, "messageId"?: string }` — re-attach to the turn already running on `chatId` after a dropped stream. `cursor` is the last SSE `id` received. Nothing new is sent; the bridge replays what happened after the cursor, then continues live. Returns `409 {"error":"resume_unavailable"}` when the session is no longer known.

Response

Returns a server-sent event stream from Gizzi Runtime. Each event is a JSON payload on the event bus, for example:

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Here is the refactored module..."}}

Resume cursor

Frames after a turn’s first trace entry carry an SSE id: the session-trace sequence. Keep the last one and send it as resume.cursor to pick up a dropped stream without duplicating text.

Generated files

A file the model made (an image, deck or document — for example from a connected subscription) arrives after the reply text as an artifact frame:

data: {"type":"artifact","messageId":"msg_…","artifactId":"prt_…","kind":"image","title":"A cat","url":"data:image/png;base64,…","mimeType":"image/png","filename":"art_1.png","sourceUri":"fabric-artifact://art_1"}

kind is one of image, audio, video, html, slides, sheet, document. url is a data URL, or the forwarder download URL for files over 24 MB. Reloaded chat history keeps the file part’s id, mime and source, so the same card can be rebuilt.

Chat action

curl -X POST http://127.0.0.1:8013/api/chat/action \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "stop", "chatId": "sess_01hqx8x7x7x7x7x7x7x7x7x"}'

Response

{
  "status": "ok"
}

Error codes

Status	Code	Description
`401`	`Unauthorized`	Missing or invalid bearer token.
`502`	`bad_gateway`	Gizzi Runtime is unreachable.
`500`	`internal_error`	Platform proxy error.

Platform API

Legal

Overview

Agency API (Preview)

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Authentication

Endpoints

Send a chat message

Request body

Response

Resume cursor

Generated files

Chat action

Response

Error codes

​Overview

​Base URL

​Authentication

​Endpoints

​Send a chat message

​Request body

​Response

​Resume cursor

​Generated files

​Chat action

​Response

​Error codes

​Related pages

Overview

Base URL

Authentication

Endpoints

Send a chat message

Request body

Response

Resume cursor

Generated files

Chat action

Response

Error codes

Related pages