API

Syte API

v0.9.5 · Machine-readable spec at /api/ai.json · AI session API · Sycord integration: /sycord/api

Authentication

All endpoints require an API key except POST /api/tokens and GET /api/health.

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. Save it immediately. Create via GUI: key in navbar.
— All authenticated endpoints
Authorization x-api-key
X-API-Key In: header
API key authentication. Use your generated token.
Authorization In: header
Alternative: Bearer syte_your_token_here

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 UUID does not exist

Project

Create, read, update, and delete deployment projects.

https://your-syte-host.com/api
POST /create_project
Create project
Request Body application/json
name* string
Length 1 ≤ length
Display name for the project.
uuid? string
Custom project ID. Auto-generated if omitted.
git_url? string
Git repo URL. 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. Set true to deploy immediately (prefer issue_deploy).
{
  "ok": true,
  "uuid": "my-site-a1b2c3",
  "status": "created",
  "execute_command": {
    "body": {"uuid": "my-site-a1b2c3", "command": "npm run lint", "cwd": "app"}
  },
  "issue_deploy": {
    "method": "POST",
    "path": "/api/issue_deploy",
    "body": {"uuid": "my-site-a1b2c3"}
  }
}
https://your-syte-host.com/api
POST /delete_project
Delete project
Request Body application/json
uuid* string
Project UUID to delete. Stops container and removes workspace.
https://your-syte-host.com/api
GET /workspace_get?uuid=
Get project
Query Parameters
uuid* string
Project UUID. Returns URLs, env, git info, preview status, stream URLs.
https://your-syte-host.com/api
GET /workspace_list
List projects
Returns all projects with uuid, url, port, status, and running state.
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

Read, write, and manage files in the project workspace.

GET /list_files?uuid=&path=
List files
path is relative to workspace root (default: root).
POST /read_file
Request Body application/json
uuid*string
path*string
e.g. app/package.json. Returns UTF-8 content or base64 for binary.
POST /write_file
Request Body application/json
uuid*string
path*string
content*string
POST /upload_file
Multipart: uuid, path, file
POST /delete_file
Request Body application/json
uuid*string
path*string
POST /execute_command
Execute command
npm run build is blocked. Use issue_deploy for production builds.
Request Body application/json
uuid*string
command*string
Allowed: npm install, npm run lint, ls -la, scaffolding.
cwd?string
Default: app
timeout?integer
Default 300Max 1800
env?object
Extra env vars for this run only.
{"ok":true,"exit_code":0,"output":"...","command":"npm run lint"}
POST /execute_commands
Execute commands (batch)
Run multiple commands in sequence. Stops on first failure by default.
{"uuid":"...","commands":[
  {"command":"npm install","cwd":"app"},
  {"command":"npm run lint","cwd":"app","timeout":300}
]}

Start

Deploy and manage production services. Build only via issue_deploy.

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
POST /start_service
Start service
Request Body application/json
uuid*string
Start existing container without rebuilding.
POST /stop_service
Stop service
Request Body application/json
uuid*string
GET /get_logs?uuid=&lines=200
Get logs (snapshot)
Snapshot of build + runtime logs.
GET /projects/{uuid}/logs/stream?live=1
Deploy logs (SSE stream)
Server-Sent Events — live deploy log stream. Optional api_key query param.
{"type":"build","text":"Step 1/21 ..."}

Preview

Fast dev server with HMR. Returns HTTPS domain URL — not raw IP.

preview_url uses the domain, not the IP. When GUI domain is set (e.g. sycord.site), preview_url = preview_domain_url (e.g. https://previewk-mysite.sycord.site). preview_direct_url is included as fallback only — do not use it when domain is configured.
preview_urlPrimary — HTTPS domain via Caddy
preview_domainHostname e.g. previewk-mysite.sycord.site
preview_domain_urlSame as preview_url when domain is set
preview_direct_urlFallback http://IP:port — only when GUI domain unset
preview_readytrue when dev server accepts connections
https://your-syte-host.com/api
POST /start_preview
Start preview
Request Body application/json
uuid* string
Requires package.json with a dev script (next dev or vite).
{
  "ok": true,
  "uuid": "my-site-abc123",
  "preview_url": "https://previewk-mysite.sycord.site",
  "preview_domain": "previewk-mysite.sycord.site",
  "preview_domain_url": "https://previewk-mysite.sycord.site",
  "preview_direct_url": "http://152.89.245.113:4000",
  "preview_ready": true,
  "preview_running": true,
  "preview_port": 4000,
  "preview_stream_url": "/api/projects/my-site-abc123/preview/logs/stream?live=1"
}
GET /preview_status?uuid=
Preview status
Poll until preview_ready: true. Returns same URL fields as start — use preview_url (domain).
POST /stop_preview
Stop preview
Request Body application/json
uuid*string
Stops dev server and removes Caddy preview route.
GET /projects/{uuid}/preview/logs/stream?live=1
Preview logs (SSE)
Live dev server output. Requires dev script and npm install first.

Env

Manage project environment variables.

https://your-syte-host.com/api
POST /set_env
Set env
Request Body application/json
uuid* string
env_vars* object
Key-value pairs e.g. {"NODE_ENV":"production"}
merge? boolean
Default true — merge with existing vars. false replaces all.
{"uuid":"...","env_vars":{"NODE_ENV":"production"},"merge":true}

Validate design

GET /validate_design?uuid=
Runs Sycord Design Contract linter — shadcn/ui, Inter font, Lucide, dark mode, hero gradient, etc.
{"ok":true,"passed":7,"total":8,"checks":[...]}

Server info

GET /server_info
Server public IP, version, base URLs.

AI Session

Control per-project Continue cn serve agents for long-lived coding sessions. Independent from preview/deploy processes.

AI session usage. One Continue agent per project workspace. Use agent_proxy_url from status — not the raw localhost port. Model profiles: syra-nano (fast), syra-base (balanced), syra-havy (capable). Configure Verted + DeepSeek API keys per profile in Syte GUI → AI. Internal sycord.com routes: /api/internal/projects/{uuid}/agent/* with X-Syra-Internal-Secret.
https://your-syte-host.com/api
GET /agent_status?uuid=
Agent status
Returns running/stopped/starting/error, allocated port, agent_proxy_url, model profile, bridge target, workspace paths, and last error.
{
  "ok": true,
  "uuid": "my-site-a1b2c3",
  "agent_status": "running",
  "agent_running": true,
  "agent_port": 5201,
  "agent_proxy_url": "https://your-syte-host.com/api/internal/projects/my-site-a1b2c3/agent/proxy",
  "agent_model_profile": "syra-base",
  "agent_backend": { "ok": true, "profile": "syra-base", "url": "https://api.deepseek.com/v1/models" }
}
POST /agent_start
Start agent
Request Body application/json
uuid*string
Starts Continue cn serve in the project workspace if not already running.
{"uuid":"my-site-a1b2c3"}
POST /agent_stop
Stop agent
Request Body application/json
uuid*string
POST /agent_restart
Restart agent
Request Body application/json
uuid*string
POST /agent_settings
Update agent settings
Request Body application/json
uuid*string
model_profile?string
syra-nano, syra-base, or syra-havy
{"uuid":"my-site-a1b2c3","model_profile":"syra-havy"}
GET /agent_logs?uuid=&lines=200
Agent logs (snapshot)
Snapshot of Continue serve output. For live tail use GET /api/projects/{uuid}/agent/logs/stream?live=1 (SSE).
GET /agent_activity?uuid=&since_id=0
Agent activity feed (snapshot)
Cursor-like chat feed for sycord.com. Structured events: user messages, assistant replies, thinking, file create/edit/delete, commands run, request lifecycle.
Poll with since_id (last event id) for incremental updates. For real-time UI use SSE below.
{
  "ok": true,
  "uuid": "my-site-a1b2c3",
  "since_id": 0,
  "stream_url": "/api/projects/my-site-a1b2c3/agent/activity/stream?live=1",
  "events": [
    {
      "id": 12,
      "event_type": "user_message",
      "role": "user",
      "title": "User",
      "detail": "Add dark mode toggle",
      "source": "sycord",
      "created_at": "2026-07-09T17:00:00+00:00"
    },
    {
      "id": 13,
      "event_type": "thinking",
      "role": "assistant",
      "title": "Thinking",
      "detail": "Planning component changes…",
      "source": "agent"
    },
    {
      "id": 14,
      "event_type": "file_modified",
      "role": "assistant",
      "title": "Modified file",
      "detail": "src/components/ThemeToggle.tsx",
      "payload": {"path": "src/components/ThemeToggle.tsx"}
    },
    {
      "id": 15,
      "event_type": "request_completed",
      "role": "assistant",
      "title": "Completed",
      "detail": "Added ThemeToggle component"
    }
  ]
}
GET /projects/{uuid}/agent/activity/stream?live=1&since_id=0
Agent activity (SSE stream)
Server-Sent Events — replays history then streams new activity in real time. Optional api_key query param.
data: {"type":"activity","event":{"id":16,"event_type":"command_run","title":"Ran command","detail":"npm run lint"}}

data: {"type":"processing","event":{"event_type":"processing","title":"Working","detail":"Agent is processing…"}}

data: {"type":"ping","since_id":16}
Full catalog: GET /api/agent_activity_catalog — every event type with Continue.dev mapping.
event_type values: session_started, session_finished, processing, request_started, request_completed, request_failed, user_message, assistant_message, thinking, plan, asking_user, tool_call, tool_result, mcp_tool_call, skill_invoked, command_run, file_created, file_modified, file_deleted, file_read, agent_started, agent_stopped, agent_restarted
GET /agent_activity_catalog
Activity event catalog
Machine-readable list of all activity events, SSE envelope types, and Continue.dev alignment. Use when building sycord.com chat UIs.
PUT /settings
MCP servers & skills (Continue CLI)
Continue.dev — cn serve loads mcpServers from config.yaml and SKILL.md files from .continue/skills/. Syte merges global MCP JSON from settings into each project config.
continue_mcp_servers — JSON array, e.g. [{"name":"sqlite","command":"npx","args":["-y","mcp-sqlite"]}]
continue_rules — one rule path or inline string per line (passed to config.yaml rules:)
agent_max_count — max concurrent AI agents (MNOA), default 50
Per-project skills: workspaces/{uuid}/app/.continue/skills/SKILL.md
Per-project MCP YAML: workspaces/{uuid}/app/.continue/mcpServers/*.yaml
Docs: MCP reference · CLI guide
POST /agent_test
Test agent
Starts agent if needed, verifies provider API + CLI, sends probe message expecting ok in reply.
{"uuid":"my-site-a1b2c3"}
{"ok":true,"checks":{"cli":true,"backend":true,"agent":true,"communicate":true},"reply":"ok"}
POST /agent_communicate
Communicate with agent
Request Body application/json
uuid*string
message*string
Sent to Continue CLI POST /message on the project workspace.
model_profile?string
{"uuid":"my-site-a1b2c3","message":"Add a dark mode toggle","model_profile":"syra-base"}
{"ok":true,"reply":"...","model":"deepseek-chat","provider":"openai","model_profile":"syra-base"}
POST /agent_change
Request code change (sycord.com)
sycord.com flow. User asks for a change on sycord.com → sycord sends UUID + model + message → Syte VM routes to matching workspace Continue CLI.
{"uuid":"my-site-a1b2c3","model_name":"syra-havy","message":"Refactor the navbar to use shadcn tabs"}
{"ok":true,"change_applied":true,"reply":"..."}
GET /agent_dashboard
Agent dashboard metrics
Returns agents online, 30-day request counts, DPFA (CPU load), MNOA (agent capacity), onboarding checklist state.

Authentication types

API tokenX-API-Key: syte_… or Authorization: Bearer syte_… — external routes /api/agent_*
Internal secretX-Syra-Internal-Secret — sycord.com → /api/internal/projects/{uuid}/agent/*
GUI (local)/api/projects/{uuid}/agent/* and /api/agent_dashboard — no auth on trusted local GUI

Internal API (sycord.com ↔ Syte)

Base: /api/internal · Auth: X-Syra-Internal-Secret header (configure in AI tab → Agent configuration)

GET/projects/{uuid}/agent — status
POST/projects/{uuid}/agent/start|stop|restart
POST/projects/{uuid}/agent/change — {message, model_name}
POST/projects/{uuid}/agent/communicate — raw message to CLI
POST/projects/{uuid}/agent/test — health + probe chat
GET/projects/{uuid}/agent/logs?lines=200
GET/projects/{uuid}/agent/activity?since_id=0 — Cursor-like activity snapshot
GET/projects/{uuid}/agent/activity/stream?live=1 — SSE real-time activity
ANY/projects/{uuid}/agent/proxy[/{path}] — forward to cn serve HTTP API
Continue CLI HTTP (via proxy or localhost): POST /message, GET /state, POST /pause, GET /diff, POST /exit

Agent errors

401Missing or invalid API key / internal secret
503 internal_secret_not_configuredSet internal secret in Syte AI tab → Agent configuration
400 agent_start_failedContinue CLI missing — npm install -g @continuedev/cli
400 backend_unreachableProvider API unreachable — check AI tab → model API keys
503 agent not runningProxy called while agent stopped — POST /agent/start first
404 not_foundUUID does not match any workspace

sycord.com change request flow

1User edits project on sycord.com and sends a change message
2sycord.com → POST /api/internal/projects/{uuid}/agent/change with model_name + message
3Syte starts cn serve for UUID workspace if needed
4Syte forwards message to Continue CLI — agent edits files in workspace
5Response reply returned to sycord.com (provider name included in agent metadata, not echoed to end user by default)
6POST /agent_stop when session ends
Metrics: DPFA = Dedicated Performance For Agents (CPU). MNOA = Maximum Number Of Agents (concurrent cn serve instances).