HTTP & WebSocket
Pie's native HTTP/SSE and WebSocket protocol.
All routes below are served on the [server] listen address alongside the OpenAI, Anthropic, and Gemini endpoints.
Routes
| Route | Purpose |
|---|---|
GET /v1/ws | WebSocket for installing programs, launching inferlets, and running multi-turn sessions. |
POST /v1/generate | Run one inferlet over HTTP, streamed back as server-sent events (SSE). |
GET /v1/models | List the served model in OpenAI format. |
POST /v1/chat/completions · /v1/completions · /v1/responses | OpenAI endpoints. |
POST /v1/messages | Anthropic endpoint. |
POST /v1beta/models/{model}:generateContent · :streamGenerateContent | Gemini endpoints. |
WebSocket (GET /v1/ws)
Messages are binary MessagePack maps with a type field. Client requests include a corr_id, and the server replies with a response message carrying the same corr_id.
Client to server
type | Fields | Purpose |
|---|---|---|
auth_identify · auth_prove | username · signature | Authenticate the client connection. |
check_program | inferlet | Check whether an inferlet is already installed. |
add_program | Program bytes in chunks | Upload and install an inferlet. |
launch_process | inferlet, input (JSON string), capture_outputs, props, session, files | Start an inferlet process. |
attach_process | process_id | Reconnect to a running process. |
signal_process | process_id, message | Deliver a message to the process's session.receive(). |
transfer_file | process_id, chunk | Stream a binary file chunk to session.receive_file(). |
terminate_process | process_id | Stop a running process. |
list_processes · query · ping | — | Inspect active processes or server status. |
Server to client
type | Fields | Meaning |
|---|---|---|
response | corr_id, ok, result | Reply to a client request. |
process_event | process_id, event, value | message, stdout, stderr, return, or error. |
file | process_id, chunk, name | A file sent by session.send_file(), in 256 KiB chunks. |
The Python client (pie-client) and the JavaScript, Swift, and Kotlin clients implement this protocol, so you rarely need to construct MessagePack frames directly.
POST /v1/generate
The request body is a launch_process message encoded as JSON, and the response streams process_event messages as server-sent events until the process returns. When running behind an authenticating proxy, pass the caller's identity in the x-pie-identity header.
Props
launch_process can attach props: small typed values (such as priority or keep-ms) read by scheduling policies.