API Reference

Every endpoint, documented.

Every endpoint exposed by the orchestrator backend, gateway, and voice agent.

Orchestrator API

Self-hosted

http://localhost:8400/api

Cloud

https://api.frontal.codes/api

Model Gateway

OpenAI-compatible

http://localhost:8400/gw/v1

Voice Agent

Separate service

http://localhost:8500

Authentication

Context	Method	Example
Self-hosted (localhost)	No auth	Trust loopback
Cloud API	Bearer	Authorization: Bearer <token>
Gateway (project-scoped)	Header	x-frontal-project: <project-id>

Health

GET /api/health

Backend health check

Response

{"status": "ok", "version": "0.1.0"}

GET /api/reconcile-report

Returns last reconciliation report

Workspaces & Projects

GET /api/workspaces

List workspaces

POST /api/workspaces

Create workspace

Param	Type	Description
name	string	Workspace name
description	string	Optional description

GET /api/projects ?workspace_id=

List projects

POST /api/projects

Create project

Param	Type	Description
name	string	Project name
workspace_id	string	Parent workspace ID
root_path	string	Absolute path to project root
trunk_branch	string	Main branch (e.g. main)
toolchain	string	Language/framework (python, node, rust, etc.)

GET /api/projects/{id}

Get project details

DELETE /api/projects/{id}

Delete project (drops DB, preserves event log)

GET /api/projects/{id}/events

Stream project events (SSE)

Intake & Planning

POST /api/projects/{id}/intake

Submit goal for a project

Param	Type	Description
goal	string	Natural language goal description
locale	string	User locale (e.g. tr, en)

POST /api/intakes/{id}/answers

Submit clarifying answers

Param	Type	Description
answers	array	Array of {question_id, answer} objects

POST /api/intakes/{id}/plan

Generate plan from completed intake

GET /api/plans/{id}

Get plan with task cards

POST /api/plans/{id}/decision

Approve or reject plan

Param	Type	Description
decision	string	"approve" or "reject"

PATCH /api/plans/{id}/tasks/{tid}

Edit task card before approval

DELETE /api/plans/{id}/tasks/{tid}

Remove task card

Sessions & Tasks

POST /api/sessions

Start session for task

Param	Type	Description
task_id	string	Task to execute
engine	string	Optional engine override

GET /api/sessions

List active sessions

POST /api/sessions/{id}/prompt

Send prompt to running session

POST /api/sessions/{id}/abort

Abort session

DELETE /api/sessions/{id}

End session cleanly

GET /api/sessions/{id}/events

Stream session events (SSE)

POST /api/sessions/{id}/retry-from-point

Retry from snapshot

POST /api/sessions/{id}/rollback-from-point

Rollback to snapshot

POST /api/projects/{id}/tasks

Create task manually

GET /api/tasks/{id}

Get task status

PATCH /api/tasks/{id}

Update task (e.g., move column)

POST /api/tasks/{id}/run

Start task execution

POST /api/tasks/{id}/trash

Move to trash + cleanup worktree

POST /api/tasks/{id}/rollback

Rollback a merged task

GET /api/tasks/{id}/diff

Get worktree diff

Files & Git

GET /api/projects/{id}/files ?path=

List files

GET /api/projects/{id}/files/content ?path=

Read file content

PUT /api/projects/{id}/files/content

Write file content

GET /api/projects/{id}/files/diff

Get uncommitted diff

GET /api/projects/{id}/git

Git status

POST /api/projects/{id}/git/stage

Stage files

POST /api/projects/{id}/git/unstage

Unstage files

POST /api/projects/{id}/git/commit

Commit changes

Param	Type	Description
message	string	Commit message

Memory & Context

POST /api/projects/{id}/memory/rebuild

Rebuild ArangoDB from event log

POST /api/projects/{id}/memory/context-pack

Generate context pack for task

GET /api/projects/{id}/memory/search ?q=

BM25 search

POST /api/projects/{id}/memory/contracts

Discovery & Vault

GET /api/discovery/search ?intent=

Search MCP servers

POST /api/discovery/provision

Provision MCP server into sandbox

GET /api/attention

List Needs-Attention items

POST /api/vault/secrets

Store secret

Param	Type	Description
key	string	Secret key name
value	string	Secret value (encrypted at rest)

GET /api/vault/secrets

List secret keys (values never returned)

Stats

POST /api/stats/presence

Heartbeat

GET /api/stats/overview

Project stats overview

GET /api/stats/daily ?days=30

Per-day stats

GET /api/stats/agents

Per-agent stats

GET /api/stats/today

Today's activity

Gateway OpenAI-compatible · port 8400

POST /gw/v1/chat/completions

Chat completion (OpenAI format)

Note	Value
Model parameter	frontal/heavy \| frontal/standard \| frontal/utility
Project header	x-frontal-project: <id>

POST /gw/v1/audio/transcriptions

Whisper transcription (multipart/form-data)

GET /gw/v1/models

List available models

GET /api/gateway/health

Gateway health + provider circuit states

GET /api/gateway/metering/summary

Token usage summary

GET /api/gateway/metering/by-tier

Usage broken down by tier

GET /api/gateway/metering/by-agent

Usage broken down by agent

Voice Agent port 8500

GET /health

Voice service health

POST /transcribe

Audio transcription

WS /chat

WebSocket voice chat loop (STT → LLM → TTS)

GET /sessions

List voice sessions

Example Request

Create a new project — the most common starting point:

curl

curl -X POST http://localhost:8400/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-backend",
    "workspace_id": "ws_default",
    "root_path": "/code/my-backend",
    "trunk_branch": "main",
    "toolchain": "python"
  }'

Full request/response schemas are available in the OpenAPI spec at http://localhost:8400/docs (self-hosted) when the backend is running.