API

Syte API

v0.9.2 · Machine-readable: /api/ai.json · Sycord: /sycord/api/ · Hash routes like #agent/agent-change

External page integration

Minimal flow to drive a Syte cloud agent from an external site (token API under /api).

Integration flow
Six steps from token to live turn
  1. Create token Use Users → Create token when an authenticated operator session is available; programmatic callers must send an existing operator credential to POST /api/tokens. Send X-API-Key on every later call.
  2. Warm runtime POST /api/agent_warm with {"uuid"}, then poll GET /api/agent_status?uuid= until agent_status="running" and agent_healthy=true. Running-since = agent_last_started_at (not a stream event).
  3. Send work POST /api/agent_change (preferred for external pages — background). Response includes turso_session_id + request_id.
  4. Follow progress Open SSE GET /api/agent_activity/stream?uuid=&since_id= and/or poll durable GET /api/agent_session/{turso_session_id}?since_id=N.
  5. Answer questions On question events, call POST /api/agent_answer_question.
  6. Interrupt / stop POST /api/agent_interrupt or /agent_cancel for the turn; /agent_stop for the runtime.
curl -s -X POST https://host/api/agent_change \
  -H "X-API-Key: $TOKEN" -H "Content-Type: application/json" \
  -d '{"uuid":"my-site","message":"Add a pricing page"}'

# → { "ok": true, "request_id": "req_…", "turso_session_id": "sess_…", "status": "accepted" }
Saving & streaming hot path
Hot eventstoken_delta, thinking_delta — skip Turso; slim wire only
Minimal deltaFields: id, event_type, detail, payload.{delta,request_id,session,agent}
Batching16–32 tokens or 300–500 chars before one SSE frame (~80ms idle flush)
CompressionSSE body may be gzip/br when Accept-Encoding allows
Cold eventsFull JSON; mirrored to Turso agent_session_event in background
Durable pollGET /api/agent_session/{id}?since_id=N
Slim hot SSE frame
id: 130
event: token_delta
data: {"id":130,"event_type":"token_delta","detail":"I'll add a pricing","payload":{"delta":"I'll add a pricing","request_id":"req_8f2a","session":3,"agent":"main"}}
Full cold SSE frame
id: 150
event: tool_call_started
data: {"id":150,"event_type":"tool_call_started","role":"assistant","title":"write_file","detail":"app/app/pricing/page.tsx","payload":{"tool":"write_file","tool_call_id":"call_91","request_id":"req_8f2a","session":3,"agent":"main"},"source":"agent","created_at":"2026-07-25T21:00:10Z"}
Heartbeat
: heartbeat
Session-auth mirrors

GUI / cookie session uses the same capabilities under /api/projects/{uuid}/agent/*. External pages should prefer the flat token API (/api/agent_*) with X-API-Key.

StatusGET /api/projects/{uuid}/agent ↔ GET /api/agent_status
Warm / start / stop…/agent/warm|start|stop|interrupt|restart
Activity SSEGET …/agent/activity/stream ↔ /api/agent_activity/stream
SessionsGET …/agent/sessions ↔ /api/agent_sessions
Chat (GUI)POST …/agent/chat ↔ /api/agent_communicate / agent_change
Machine specs/api/ai.json · /sycord/api/

Authentication

All external API endpoints require an API key, except GET /api/health. Token management additionally accepts an authenticated same-origin operator session.

https://your-syte-host.com/api
POST /tokens
Create API token
Request Body application/json
name* string
Label for this token (shown in GUI).
{
  "ok": true,
  "token": "syte_abc123…",
  "prefix": "syte_abc…"
}
Token shown once. Protected GUI actions require an authenticated operator session; external callers must use an existing API token or server operator credential. Save the new token immediately.
https://your-syte-host.com/api
— All authenticated endpoints
Send the API key
Authorization x-api-key
X-API-Key? header
In: header
Preferred for external pages.
Authorization? header
In: header
Alternative: Bearer syte_your_token_here.
curl -H "X-API-Key: syte_…" https://host/api/agent_status?uuid=my-site
Errors
401 missing_api_keyNo X-API-Key or Bearer header
401 invalid_api_keyToken wrong or revoked
400 invalid_pathPath escapes workspace
400 create_failedDuplicate uuid or validation error
400 preview_failedDev server failed to start
404 not_foundProject or session UUID missing

Platform & Managed Databases

Provision private database containers (PostgreSQL, MySQL, MariaDB, MongoDB, Redis, KeyDB, Dragonfly, ClickHouse), view connections, and schedule logical backups.

https://your-syte-host.com/api
GET /platform/databases/catalog
Get database engines catalog
Response application/json
{
  "engines": [
    { "id": "postgres", "name": "PostgreSQL", "default_version": "16", "default_port": 5432 },
    { "id": "mysql", "name": "MySQL", "default_version": "8.0", "default_port": 3306 },
    { "id": "redis", "name": "Redis", "default_version": "7.2", "default_port": 6379 }
  ]
}
https://your-syte-host.com/api
GET /platform/databases
List managed databases
Response application/json
[
  {
    "uuid": "db-pg-12345",
    "name": "app-postgres",
    "engine": "postgres",
    "version": "16",
    "status": "running",
    "created_at": "2025-01-15T12:00:00Z"
  }
]
https://your-syte-host.com/api
POST /platform/databases
Provision managed database
Request Body application/json
name* string
Instance name.
engine* string
Engine type (e.g. postgres, mysql, redis, mongodb, mariadb, keydb, dragonfly, clickhouse).
Response application/json
{
  "uuid": "db-pg-12345",
  "name": "app-postgres",
  "engine": "postgres",
  "status": "running",
  "connection_url": "postgres://postgres:password@db-pg-12345:5432/postgres"
}
https://your-syte-host.com/api
GET /platform/databases/{uuid}/connection
Get connection details
Response application/json
{
  "uuid": "db-pg-12345",
  "DATABASE_URL": "postgres://postgres:secret@db-pg-12345:5432/postgres",
  "internal_host": "db-pg-12345",
  "port": 5432
}
https://your-syte-host.com/api
GET /platform/backups
List backup schedules
Response application/json
[
  {
    "uuid": "bck-sched-01",
    "database_uuid": "db-pg-12345",
    "cron_expression": "0 2 * * *",
    "enabled": true
  }
]
https://your-syte-host.com/api
POST /platform/backups
Create backup schedule
Request Body application/json
database_uuid* string
Target database UUID.
cron_expression* string
Cron schedule (e.g. "0 2 * * *").
https://your-syte-host.com/api
POST /platform/backups/{uuid}/run
Run immediate database backup
Response application/json
{
  "execution_id": "exec-991",
  "status": "completed",
  "file_path": "/var/lib/syte/backups/db-pg-12345-20250115.sql.gz"
}
https://your-syte-host.com/api
POST /platform/backup-executions/{uuid}/restore
Restore database backup
Response application/json
{ "success": true, "message": "Database restored successfully from local artifact" }

Project

Create, delete, start, and stop deployment projects.

https://your-syte-host.com/api
POST /create_project
Create project
Request Body application/json
name* string
Display name.
uuid? string
Custom project ID; auto-generated if omitted.
git_url? string
Cloned on issue_deploy, not required at create.
git_provider? string
Shorthand: github.com/user/repo.git
branch? string
Default main.
start_command? string
Shell fallback when no Dockerfile.
domain? string
Custom HTTPS production domain.
env_vars? object
Initial environment variables.
deploy? boolean
Default false. Prefer issue_deploy.
{
  "ok": true,
  "uuid": "my-site-a1b2c3",
  "status": "created"
}
https://your-syte-host.com/api
POST /delete_project
Delete project
Request Body application/json
uuid* string
Stops container and removes workspace.
{"uuid":"my-site-a1b2c3"}
https://your-syte-host.com/api
POST /start_service
Start service
Request Body application/json
uuid* string
Start existing container without rebuilding.
{"ok":true,"uuid":"…","running":true}
https://your-syte-host.com/api
POST /stop_service
Stop service
Request Body application/json
uuid* string
Stop production container.
{"ok":true,"uuid":"…","running":false}
https://your-syte-host.com/api
GET /workspace_get?uuid=
Get project
Query
uuid* string
Returns URLs, env, git, preview, stream URLs.
https://your-syte-host.com/api
GET /workspace_list
List projects
All projects with uuid, url, port, status, running.
https://your-syte-host.com/api
POST /set_domain
Set domain
Request Body application/json
uuid* string
domain* string
Production HTTPS domain. Auto TLS via Caddy.

Workspace

List, read, write, and execute inside the project workspace.

https://your-syte-host.com/api
GET /list_files?uuid=&path=
List files
Query
uuid* string
path? string
Relative to workspace root (default: root).
https://your-syte-host.com/api
POST /read_file
Read file
Request Body application/json
uuid* string
path* string
e.g. app/package.json. UTF-8 or base64 for binary.
{"ok":true,"path":"app/package.json","content":"{…}","encoding":"utf-8"}
https://your-syte-host.com/api
POST /write_file
Write file
Request Body application/json
uuid* string
path* string
content* string
Full file body (overwrite).
https://your-syte-host.com/api
POST /upload_file
Upload file
Multipart: uuid, path, file.
https://your-syte-host.com/api
POST /delete_file
Delete file
Request Body application/json
uuid* string
path* string
https://your-syte-host.com/api
POST /execute_command
Execute command
npm run build is blocked. Use issue_deploy for production builds.
Request Body application/json
uuid* string
command* string
Shell command (npm install, lint, scaffolding).
cwd? string
Default app.
timeout? integer
Default 300
Default 300, max 1800.
env? object
Extra env for this run only.
{"ok":true,"exit_code":0,"output":"…","command":"npm run lint"}
https://your-syte-host.com/api
POST /execute_commands
Execute command sequence
Request Body application/json
uuid* string
commands* array
Steps with command, optional cwd, timeout, stop_on_error.
env? object
Shared env for the batch.

Deploy / Preview / Env

Production deploy, fast HMR preview, and environment variables.

https://your-syte-host.com/api
POST /issue_deploy
Issue deploy
The only way to build and deploy. Git pull (if configured) + Docker build + container restart.
Request Body application/json
uuid* string 
{"ok":true,"uuid":"…","stream_url":"/api/projects/…/logs/stream?live=1"}
https://your-syte-host.com/api
POST /deploy_cancel
Cancel deploy
Request Body application/json
uuid* string
https://your-syte-host.com/api
GET /get_logs?uuid=&lines=200
Get logs (snapshot)
Snapshot of build + runtime logs.
https://your-syte-host.com/api
GET /projects/{uuid}/logs/stream?live=1
Deploy logs (SSE)
Live deploy log stream. Optional api_key query param.
{"type":"build","text":"Step 1/21 …"}
https://your-syte-host.com/api
POST /start_preview
Start preview
preview_url uses the domain, not the IP when GUI domain is set.
Request Body application/json
uuid* string
Requires package.json with a dev script.
{
  "ok": true,
  "preview_url": "https://previewk-mysite.example.com",
  "preview_ready": true,
  "preview_running": true
}
https://your-syte-host.com/api
GET /preview_status?uuid=
Preview status
Poll until preview_ready: true.
https://your-syte-host.com/api
POST /stop_preview
Stop preview
Request Body application/json
uuid* string
Stops dev server and Caddy preview route.
https://your-syte-host.com/api
POST /set_env
Set env
Request Body application/json
uuid* string
env_vars* object
e.g. {"NODE_ENV":"production"}
merge? boolean
Default true — merge; false replaces all.
{"uuid":"…","env_vars":{"NODE_ENV":"production"},"merge":true}

Agent (token API)

Manage a project agent from an external page. Base /api, header X-API-Key. Session-auth mirrors live at /api/projects/{uuid}/agent/*.

Profiles: syra-nano (Go / Gemini 2.5), syra-ultra (Air / Aliyun Qwen), and syra-havy (Metal / VyceAI Claude Sonnet 4.6). Configure keys in Settings → AI. Prefer agent_change (background) for external UIs; agent_communicate waits for the turn.
https://your-syte-host.com/api
GET /agent_status?uuid=
Agent status
Query
uuid* string
Project UUID.
agent_last_started_at is the "running since" timestamp — it is not a stream event. agent_turso_sync drives the brain indicator.
{
  "ok": true,
  "uuid": "my-site",
  "agent_status": "running",
  "agent_running": true,
  "agent_busy": false,
  "agent_healthy": true,
  "agent_last_started_at": "2026-07-25T20:59:50Z",
  "agent_last_error": "",
  "agent_turso_sync": {
    "turso_configured": true,
    "session": 3,
    "turso_session_id": "sess_9c1e…",
    "total_messages": 12,
    "synced_messages": 12,
    "all_saved": true
  },
  "agent_model": {"profile": "syra-nano", "model": "gemini-2.5-flash"}
}
https://your-syte-host.com/api
POST /agent_warm
Warm agent (non-blocking)
Recommended. Returns immediately while runtime starts. Poll status or listen for agent_started.
Request Body application/json
uuid* string 
{"uuid":"my-site","ok":true,"status":"warming","already_warming":false}
https://your-syte-host.com/api
POST /agent_start
Start agent (blocking ready)
Request Body application/json
uuid* string
Waits until runtime is ready. Prefer warm for UX.
{"uuid":"my-site"}
https://your-syte-host.com/api
POST /agent_stop
Stop agent runtime
Request Body application/json
uuid* string
https://your-syte-host.com/api
POST /agent_interrupt
Interrupt active turn
Request Body application/json
uuid* string
Cancels the in-flight job/turn.
Alias behavior matches cancel — stops the current turn without a new message.
https://your-syte-host.com/api
POST /agent_cancel
Cancel active turn
Request Body application/json
uuid* string
Cancel without submitting a new message.
https://your-syte-host.com/api
POST /agent_restart
Restart agent
Request Body application/json
uuid* string
https://your-syte-host.com/api
POST /agent_settings
Update agent settings
Request Body application/json
uuid* string
model_profile? string
syra-nano|syra-ultra|syra-havy
{"uuid":"my-site","model_profile":"syra-nano"}
https://your-syte-host.com/api
GET /agent_logs?uuid=&lines=200
Agent logs
Query
uuid* string
lines? integer
1–2000, default 200.
{"ok":true,"uuid":"…","logs":"…","stream_url":"/api/projects/…/agent/logs/stream?live=1"}
https://your-syte-host.com/api
GET /agent_activity?uuid=&since_id=&session=
Local activity snapshot
Query
uuid* string
since_id? integer
Default 0
Return events with id > since_id.
limit? integer
1–2000, default 200.
session? string
last or session number — filter that session only.
For the durable UUID-addressable trail use GET /api/agent_session/{{id}}.
{
  "ok": true,
  "events": […],
  "sessions_url": "/api/agent_sessions?uuid=…",
  "stream_url": "/api/agent_activity/stream?uuid=…&since_id=0"
}
https://your-syte-host.com/api
GET /agent_activity/stream?uuid=&since_id=
Live activity SSE (token API)
NEW token API. Hot token_delta/thinking_delta are minimal-delta; body may be gzip/brotli. Heartbeat : heartbeat ~15s.
Query / headers
uuid* string
since_id? integer
Replay backlog after this id.
session? string
Optional filter: last or session number.
Accept-Encoding? header
Send gzip, br for compressed SSE.
X-API-Key* header
Required.
GET /api/agent_activity/stream?uuid=my-site&since_id=0
X-API-Key: syte_…
Accept: text/event-stream
Accept-Encoding: gzip, br
Example frames
id: 130
event: token_delta
data: {"id":130,"event_type":"token_delta","detail":"Hello","payload":{"delta":"Hello","request_id":"req_1","session":1,"agent":"main"}}

: heartbeat

id: 150
event: tool_call_started
data: {"id":150,"event_type":"tool_call_started",…}
https://your-syte-host.com/api
GET /agent_sessions?uuid=&limit=&resume=
List Turso sessions
Query
uuid* string
limit? integer
1–500, default 50.
resume? integer
0|1 — include resume hints.
{
  "ok": true,
  "turso_configured": true,
  "sessions": [{{"id":"sess_…","session_url":"/api/agent_session/sess_…"}}],
  "open_session": "sess_…",
  "resume_session": "sess_…"
}
https://your-syte-host.com/api
GET /agent_session/{session_id}?since_id=
Poll durable session
Query
session_id* path
Turso session UUID from agent_change.
since_id? integer
Incremental poll cursor.
uuid? string
Optional project check (or project_id).
{
  "ok": true,
  "id": "sess_9c1e…",
  "project_id": "my-site",
  "status": "open",
  "events": [{{"id": 12, "event_type": "assistant_message", …}}],
  "next_since_id": 12
}
https://your-syte-host.com/api
GET /agent_turso_sync?uuid=
Turso message sync (brain)
all_saved: true → green brain; false → red (unsynced local messages).
{
  "ok": true,
  "turso_configured": true,
  "session": 3,
  "turso_session_id": "sess_…",
  "total_messages": 12,
  "synced_messages": 12,
  "all_saved": true
}
https://your-syte-host.com/api
GET /agent_turso_debug?uuid=
Turso connectivity debug
Diagnose why the brain stays red — live connectivity + schema check.
https://your-syte-host.com/api
POST /agent_communicate
Communicate (waits for turn)
Request Body application/json
uuid* string
message* string
model_profile? string
syra-nano | syra-ultra | syra-havy
thinking_level? integer
1 Instant … 5 Max (per-request).
improve_from_screenshot? boolean
visual_analysis_id? string 
{
  "ok": true,
  "request_id": "req_…",
  "turso_session_id": "sess_…",
  "reply": "…",
  "status": "completed"
}
https://your-syte-host.com/api
POST /agent_change
Change request (background — preferred)
External pages: fire-and-forget. Poll SSE or Turso session for progress.
Request Body application/json
uuid* string
message* string
Change request text.
model_profile? string
Alias also accepted as model_name.
thinking_level? integer
1–5.
idempotency_key? string
Retries return the same request_id.
improve_from_screenshot? boolean
visual_analysis_id? string 
{
  "ok": true,
  "request_id": "req_8f2a",
  "turso_session_id": "sess_9c1e…",
  "status": "accepted",
  "change_applied": null
}
https://your-syte-host.com/api
GET /agent_questions?uuid=&status=
List questions
Query
uuid* string
status? string
Filter e.g. pending.
limit? integer 
{"ok":true,"questions":[{{"id":"q_7","prompt":"Which tiers?","status":"pending","options":[…]}}]}
https://your-syte-host.com/api
POST /agent_answer_question
Answer a question
Request Body application/json
uuid* string
question_id* string
answer* string|number|array|object
User answer.
{"uuid":"my-site","question_id":"q_7","answer":"Free / Pro / Enterprise"}
https://your-syte-host.com/api
GET /agent_screenshots?uuid=
List screenshots
Query
uuid* string
limit? integer
1–200.
https://your-syte-host.com/api
GET /agent_plans?uuid=
List plans
Query
uuid* string
limit? integer
https://your-syte-host.com/api
GET /agent_stops?uuid=
List session stops
Query
uuid* string
limit? integer
https://your-syte-host.com/api
GET/POST /agent_mcp*
MCP addons (brief)
Token API mirrors of GUI MCP management.
GET /agent_mcpList addons
POST /agent_mcp_registername, command, args, env, transport
POST /agent_mcp_connectuuid + addon
POST /agent_mcp_calluuid, addon, tool, arguments
POST /agent_mcp_updateUpdate addon config
POST /agent_mcp_disconnectDisconnect addon
Session-auth: /api/projects/{{uuid}}/agent/mcp (+ connect/call).
https://your-syte-host.com/api
GET/POST /agent_skills*
Skills (brief)
GET /agent_skillsList project skills
POST /agent_skills_addname, content, description, parameters, enable
POST /agent_skills_updateskill_id + fields
POST /agent_skills_enableskill_id + parameters
POST /agent_skills_disableskill_id
POST /agent_skills_deleteskill_id
Session-auth: /api/projects/{{uuid}}/agent/skills.

Stream events

Every activity event key emitted on /api/agent_activity/stream. Use mini-tabs to jump. Hot keys are slim; everything else is full cold JSON.

https://your-syte-host.com/api
GET /agent_activity/stream?uuid=
Connect to SSE
Token API. Also available as session-auth /api/projects/{{uuid}}/agent/activity/stream and Sycord /sycord/api/agent_activity/stream.
Query
uuid* string
since_id? integer
Replay after this local event id.
session? string
Optional filter.
Each frame: id: + event: + data: JSON. Idle connections receive comment heartbeats.
Hot path rules
Hot typestoken_delta, thinking_delta
Wire shapeid, event_type, detail, tiny payload
Batch16–32 tokens or 300–500 chars; ~80ms idle flush
TursoHot events skip Turso; cold events mirror in background
EncodingContent-Encoding: gzip|br when accepted
Running sinceFrom agent_status.agent_last_started_at — not a stream key
https://your-syte-host.com/api
SSE request_started
Turn accepted — durable request row opened.
Turn accepted — durable request row opened.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 101,
  "event_type": "request_started",
  "role": "system",
  "title": "Request started",
  "detail": "Build a pricing page",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "turso_session_id": "sess_9c1e…"
  },
  "source": "api",
  "created_at": "2026-07-25T21:00:00Z"
}
SSE frame
id: …
event: request_started
data: {…}
https://your-syte-host.com/api
SSE processing
Agent is working on the active turn.
Agent is working on the active turn.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 102,
  "event_type": "processing",
  "role": "system",
  "title": "Processing",
  "detail": "Planning layout",
  "payload": {"request_id": "req_8f2a", "session": 3, "agent": "main"},
  "source": "agent",
  "created_at": "2026-07-25T21:00:01Z"
}
SSE frame
id: …
event: processing
data: {…}
https://your-syte-host.com/api
SSE status
Generic status line for UI banners.
Generic status line for UI banners.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 103,
  "event_type": "status",
  "role": "system",
  "title": "Status",
  "detail": "Waiting for preview",
  "payload": {"request_id": "req_8f2a", "session": 3, "agent": "main", "level": "info"},
  "source": "agent",
  "created_at": "2026-07-25T21:00:02Z"
}
SSE frame
id: …
event: status
data: {…}
https://your-syte-host.com/api
SSE agent_started
Cloud runtime became ready.
Cloud runtime became ready.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 10,
  "event_type": "agent_started",
  "role": "system",
  "title": "Cloud agent ready",
  "detail": "VM-native Syte cloud runtime is ready",
  "payload": {"runtime": "syte-cloud"},
  "source": "syte-cloud",
  "created_at": "2026-07-25T20:59:50Z"
}
SSE frame
id: …
event: agent_started
data: {…}
https://your-syte-host.com/api
SSE agent_stopped
Runtime stopped.
Runtime stopped.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 400,
  "event_type": "agent_stopped",
  "role": "system",
  "title": "Agent stopped",
  "detail": "Runtime shut down",
  "payload": {},
  "source": "api",
  "created_at": "2026-07-25T22:00:00Z"
}
SSE frame
id: …
event: agent_stopped
data: {…}
https://your-syte-host.com/api
SSE agent_restarted
Runtime restarted (crash recovery or explicit restart).
Runtime restarted (crash recovery or explicit restart).
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 50,
  "event_type": "agent_restarted",
  "role": "system",
  "title": "Cloud session restarted",
  "detail": "",
  "payload": {},
  "source": "syte-cloud",
  "created_at": "2026-07-25T21:10:00Z"
}
SSE frame
id: …
event: agent_restarted
data: {…}
https://your-syte-host.com/api
SSE thinking
Cold thinking snapshot (full text).
Cold thinking snapshot (full text).
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 110,
  "event_type": "thinking",
  "role": "assistant",
  "title": "Thinking",
  "detail": "I should inspect the existing layout before editing…",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "content": "I should inspect the existing layout before editing…"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:03Z"
}
SSE frame
id: …
event: thinking
data: {…}
https://your-syte-host.com/api
SSE thinking_delta
Hot path — minimal-delta only (batched).
Hot path — minimal-delta only (batched).
Hot event — minimal-delta wire. Batched before emit. Not mirrored to Turso.
SSE frame
id: …
event: thinking_delta
data: {
  "id": 111,
  "event_type": "thinking_delta",
  "detail": " before editing",
  "payload": {
    "delta": " before editing",
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  }
}
https://your-syte-host.com/api
SSE plan
Structured plan artifact published.
Structured plan artifact published.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 120,
  "event_type": "plan",
  "role": "assistant",
  "title": "Plan",
  "detail": "1. Audit home 2. Add pricing section 3. Wire CTA",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "plan_id": "plan_12",
    "steps": [
      {"id": "s1", "text": "Audit home", "status": "done"},
      {"id": "s2", "text": "Add pricing section", "status": "running"},
      {"id": "s3", "text": "Wire CTA", "status": "pending"}
    ]
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:05Z"
}
SSE frame
id: …
event: plan
data: {…}
https://your-syte-host.com/api
SSE token_delta
Hot path — assistant text chunk (batched, slim wire).
Hot path — assistant text chunk (batched, slim wire).
Hot event — minimal-delta wire. Batched before emit. Not mirrored to Turso.
SSE frame
id: …
event: token_delta
data: {
  "id": 130,
  "event_type": "token_delta",
  "detail": "I'll add a pricing",
  "payload": {
    "delta": "I'll add a pricing",
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  }
}
https://your-syte-host.com/api
SSE message_snapshot
Full assistant message so far (reconnect-friendly).
Full assistant message so far (reconnect-friendly).
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 140,
  "event_type": "message_snapshot",
  "role": "assistant",
  "title": "Assistant",
  "detail": "I'll add a pricing section with three tiers…",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "content": "I'll add a pricing section with three tiers…"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:08Z"
}
SSE frame
id: …
event: message_snapshot
data: {…}
https://your-syte-host.com/api
SSE assistant_message
Final assistant message for the turn (cold).
Final assistant message for the turn (cold).
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 200,
  "event_type": "assistant_message",
  "role": "assistant",
  "title": "Assistant",
  "detail": "Done — pricing section is live on /pricing.",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "content": "Done — pricing section is live on /pricing."
  },
  "source": "agent",
  "created_at": "2026-07-25T21:01:20Z"
}
SSE frame
id: …
event: assistant_message
data: {…}
https://your-syte-host.com/api
SSE user_message
User prompt recorded.
User prompt recorded.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 100,
  "event_type": "user_message",
  "role": "user",
  "title": "User",
  "detail": "Build a pricing page",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "content": "Build a pricing page"
  },
  "source": "external_api",
  "created_at": "2026-07-25T21:00:00Z"
}
SSE frame
id: …
event: user_message
data: {…}
https://your-syte-host.com/api
SSE tool_call_started
Tool invocation began.
Tool invocation began.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 150,
  "event_type": "tool_call_started",
  "role": "assistant",
  "title": "write_file",
  "detail": "app/app/pricing/page.tsx",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "tool": "write_file",
    "tool_call_id": "call_91",
    "args": {"path": "app/app/pricing/page.tsx"}
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:10Z"
}
SSE frame
id: …
event: tool_call_started
data: {…}
https://your-syte-host.com/api
SSE tool_call_finished
Tool finished successfully.
Tool finished successfully.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 151,
  "event_type": "tool_call_finished",
  "role": "tool",
  "title": "write_file",
  "detail": "wrote 1842 bytes",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "tool": "write_file",
    "tool_call_id": "call_91",
    "ok": true,
    "result": {"bytes": 1842}
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:11Z"
}
SSE frame
id: …
event: tool_call_finished
data: {…}
https://your-syte-host.com/api
SSE tool_error
Tool failed.
Tool failed.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 152,
  "event_type": "tool_error",
  "role": "tool",
  "title": "execute_command",
  "detail": "exit 1",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "tool": "execute_command",
    "tool_call_id": "call_92",
    "ok": false,
    "error": "npm ERR! Missing script: lint"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:15Z"
}
SSE frame
id: …
event: tool_error
data: {…}
https://your-syte-host.com/api
SSE tool_call
Legacy/combined tool_call event.
Legacy/combined tool_call event.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 153,
  "event_type": "tool_call",
  "role": "assistant",
  "title": "read_file",
  "detail": "app/package.json",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "tool": "read_file",
    "path": "app/package.json"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:06Z"
}
SSE frame
id: …
event: tool_call
data: {…}
https://your-syte-host.com/api
SSE file_created
File created in workspace.
File created in workspace.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 160,
  "event_type": "file_created",
  "role": "system",
  "title": "Created file",
  "detail": "app/app/pricing/page.tsx",
  "payload": {"path": "app/app/pricing/page.tsx", "request_id": "req_8f2a", "session": 3, "agent": "main"},
  "source": "agent",
  "created_at": "2026-07-25T21:00:11Z"
}
SSE frame
id: …
event: file_created
data: {…}
https://your-syte-host.com/api
SSE file_modified
File overwritten/edited.
File overwritten/edited.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 161,
  "event_type": "file_modified",
  "role": "system",
  "title": "Modified file",
  "detail": "app/components/Header.tsx",
  "payload": {"path": "app/components/Header.tsx", "request_id": "req_8f2a", "session": 3, "agent": "main"},
  "source": "agent",
  "created_at": "2026-07-25T21:00:12Z"
}
SSE frame
id: …
event: file_modified
data: {…}
https://your-syte-host.com/api
SSE file_deleted
File removed.
File removed.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 162,
  "event_type": "file_deleted",
  "role": "system",
  "title": "Deleted file",
  "detail": "app/app/old-promo/page.tsx",
  "payload": {"path": "app/app/old-promo/page.tsx", "request_id": "req_8f2a", "session": 3, "agent": "main"},
  "source": "agent",
  "created_at": "2026-07-25T21:00:13Z"
}
SSE frame
id: …
event: file_deleted
data: {…}
https://your-syte-host.com/api
SSE file_read
File contents read by agent.
File contents read by agent.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 163,
  "event_type": "file_read",
  "role": "system",
  "title": "Read file",
  "detail": "app/package.json",
  "payload": {"path": "app/package.json", "request_id": "req_8f2a", "session": 3, "agent": "main"},
  "source": "agent",
  "created_at": "2026-07-25T21:00:04Z"
}
SSE frame
id: …
event: file_read
data: {…}
https://your-syte-host.com/api
SSE file_changed
Generic file change notification.
Generic file change notification.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 165,
  "event_type": "file_changed",
  "role": "system",
  "title": "File changed",
  "detail": "app/app/page.tsx",
  "payload": {"path": "app/app/page.tsx", "op": "modify", "request_id": "req_8f2a", "session": 3, "agent": "main"},
  "source": "agent",
  "created_at": "2026-07-25T21:00:14Z"
}
SSE frame
id: …
event: file_changed
data: {…}
https://your-syte-host.com/api
SSE command_run
Shell command started/finished summary.
Shell command started/finished summary.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 170,
  "event_type": "command_run",
  "role": "system",
  "title": "Command",
  "detail": "npm install lucide-react",
  "payload": {
    "command": "npm install lucide-react",
    "cwd": "app",
    "exit_code": 0,
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:16Z"
}
SSE frame
id: …
event: command_run
data: {…}
https://your-syte-host.com/api
SSE command_output
Incremental command stdout/stderr.
Incremental command stdout/stderr.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 171,
  "event_type": "command_output",
  "role": "system",
  "title": "Output",
  "detail": "added 1 package in 1s",
  "payload": {
    "command": "npm install lucide-react",
    "stream": "stdout",
    "chunk": "added 1 package in 1s",
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:16Z"
}
SSE frame
id: …
event: command_output
data: {…}
https://your-syte-host.com/api
SSE screenshot
Preview screenshot captured.
Preview screenshot captured.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 180,
  "event_type": "screenshot",
  "role": "system",
  "title": "Screenshot",
  "detail": "Homepage",
  "payload": {
    "screenshot_id": "ss_44",
    "url": "/api/agent_screenshots?uuid=my-site…",
    "preview_url": "https://previewk-mysite.example.com",
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:40Z"
}
SSE frame
id: …
event: screenshot
data: {…}
https://your-syte-host.com/api
SSE question
Agent asked the user a clarifying question.
Agent asked the user a clarifying question.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 190,
  "event_type": "question",
  "role": "assistant",
  "title": "Question",
  "detail": "Which pricing tiers should we show?",
  "payload": {
    "question_id": "q_7",
    "prompt": "Which pricing tiers should we show?",
    "options": ["Free / Pro / Enterprise", "Starter / Growth / Scale"],
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:20Z"
}
SSE frame
id: …
event: question
data: {…}
https://your-syte-host.com/api
SSE question_answered
User answered via agent_answer_question.
User answered via agent_answer_question.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 191,
  "event_type": "question_answered",
  "role": "user",
  "title": "Answer",
  "detail": "Free / Pro / Enterprise",
  "payload": {
    "question_id": "q_7",
    "answer": "Free / Pro / Enterprise",
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  },
  "source": "external_api",
  "created_at": "2026-07-25T21:00:45Z"
}
SSE frame
id: …
event: question_answered
data: {…}
https://your-syte-host.com/api
SSE request_completed
Turn finished successfully.
Turn finished successfully.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 230,
  "event_type": "request_completed",
  "role": "system",
  "title": "Completed",
  "detail": "Done — pricing section is live on /pricing.",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "turso_session_id": "sess_9c1e…",
    "status": "completed"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:01:21Z"
}
SSE frame
id: …
event: request_completed
data: {…}
https://your-syte-host.com/api
SSE request_failed
Turn failed.
Turn failed.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 231,
  "event_type": "request_failed",
  "role": "system",
  "title": "Failed",
  "detail": "provider_error",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "error": "provider_error",
    "message": "Upstream 429"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:01:21Z"
}
SSE frame
id: …
event: request_failed
data: {…}
https://your-syte-host.com/api
SSE session_stopped
Session stop marker recorded.
Session stop marker recorded.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 240,
  "event_type": "session_stopped",
  "role": "system",
  "title": "Session stopped",
  "detail": "User stopped session 3",
  "payload": {"session": 3, "reason": "user"},
  "source": "api",
  "created_at": "2026-07-25T22:00:00Z"
}
SSE frame
id: …
event: session_stopped
data: {…}
https://your-syte-host.com/api
SSE usage
Token/cost accounting for the turn.
Token/cost accounting for the turn.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 229,
  "event_type": "usage",
  "role": "system",
  "title": "Usage",
  "detail": "12.4k tokens · $0.042",
  "payload": {
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main",
    "input_tokens": 8200,
    "output_tokens": 3100,
    "thinking_tokens": 1100,
    "total_tokens": 12400,
    "cost_usd": 0.042,
    "cost_label": "$0.042"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:01:20Z"
}
SSE frame
id: …
event: usage
data: {…}
https://your-syte-host.com/api
SSE service_action
Preview/deploy/service side-effect.
Preview/deploy/service side-effect.
Cold event — full JSON; mirrored to Turso in background when a session is open.
JSON (data: payload)
{
  "id": 175,
  "event_type": "service_action",
  "role": "system",
  "title": "Preview started",
  "detail": "https://previewk-mysite.example.com",
  "payload": {
    "action": "start_preview",
    "preview_url": "https://previewk-mysite.example.com",
    "request_id": "req_8f2a",
    "session": 3,
    "agent": "main"
  },
  "source": "agent",
  "created_at": "2026-07-25T21:00:35Z"
}
SSE frame
id: …
event: service_action
data: {…}
https://your-syte-host.com/api
SSE error
Synthetic SSE error frame (connection/stream failure).
Synthetic SSE error frame (connection/stream failure).
Synthetic SSE error
event: error
data: {"event_type":"error","error":"stream_failed","message":"…"}
https://your-syte-host.com/api
SSE heartbeat
Comment heartbeat every ~15s while idle — keep connection alive.
Comment heartbeat every ~15s while idle — keep connection alive.
Comment line (not JSON)
: heartbeat

Turso persistence

Durable cross-host storage for sessions, events, messages, requests, and subagents. Hot stream deltas never write here.

Write sequence
  1. Open session On turn start Syte opens/reuses an agent_session and returns turso_session_id from agent_change / agent_communicate.
  2. record_request Inserts agent_request (status running, cost null).
  3. Cold events Background mirror into agent_session_event. Chat rows go to agent_message.
  4. Subagents record_subagent_task → activity lines → finalize_subagent_task.
  5. finalize_request Closes the request with reply, usage, cost, activity_count.
If Turso is unset, sessions still open locally on the deployer so clients always get a pollable id.
Tables
agent_sessionSession UUID, project_id, status, created/updated/ended
agent_session_eventCold activity trail (poll via agent_session)
agent_messageChat rows mirrored from local store (brain sync)
agent_requestPer-turn request + usage/cost
agent_subagent_taskDelegated task + file scope + cost
agent_subagent_activitySubagent-only activity lines
Config

Settings → AI: set turso_database_url and turso_auth_token. Without them, local fallback keeps sessions on the host disk.

// Settings → AI
turso_database_url = "libsql://your-db.turso.io"
turso_auth_token   = "eyJ…"
Brain indicator

GET /api/agent_turso_sync?uuid= (also nested in agent_status.agent_turso_sync).

all_saved: trueGreen — every local message for the session mirrored
all_saved: falseRed — at least one unsynced message
not configuredturso_configured: false and all_saved: true (local-only OK)
Debug with GET /api/agent_turso_debug?uuid=.
Poll durable trail
GET /api/agent_session/sess_9c1e…?since_id=0
X-API-Key: syte_…

# then
GET /api/agent_session/sess_9c1e…?since_id=42
Write examples
record_request (start of turn)
{
  "request_id": "req_8f2a",
  "session_id": "sess_9c1e…",
  "project_id": "my-site",
  "session_number": 3,
  "source": "sycord",
  "model_profile": "syra-nano",
  "request": "Build a pricing page",
  "status": "running",
  "started_at": "2026-07-25T21:00:00Z"
}
record_subagent_task
{
  "task_id": "sub_3",
  "session_id": "sess_9c1e…",
  "project_id": "my-site",
  "parent_request_id": "req_8f2a",
  "task": "Implement PricingCard",
  "mode": "build",
  "profile": "syra-nano",
  "files": ["app/components/PricingCard.tsx"],
  "status": "running"
}
finalize_request
{
  "request_id": "req_8f2a",
  "status": "completed",
  "reply": "Done — pricing section is live.",
  "activity_count": 28,
  "subagent_count": 1,
  "input_tokens": 8200,
  "output_tokens": 3100,
  "total_tokens": 12400,
  "cost_usd": 0.042,
  "ended_at": "2026-07-25T21:01:21Z"
}