Docs

Current HTTP API for the running Synergos XIV kernel. This reflects what’s actually implemented today — all 14 XIV agents are real, LLM-backed, and callable through the endpoints below.

Endpoints

GET / POST/api/projects

List your project workspaces or create a new one. Requires the x-phillomena-session-id header; projects are scoped to your account or guest session.

Body

{ "name": "string (required, 1-80 characters)" }

Response

GET: { "projects": [ { "id", "name", "conversationCount" } ] }
POST: { "project": { "id", "name", "conversationCount": 0 } }

GET/api/artifacts

List code files generated in your conversations. Files are saved when Phillomena emits named file blocks and are scoped to your account or guest session.

Response

{ "artifacts": [ { "id", "conversationId", "path", "content", "createdAt" } ] }

POST/api/task

Submit a task to the orchestrator. Routes the task to the appropriate agent(s) and returns the result.

Body

{
  "task": "string (required)",
  "context": "any (optional)"
}

Response

{
  ...orchestrator result
}

GET/api/telemetry?limit=50

Fetch recent telemetry events from the orchestrator. `limit` defaults to 50.

Response

[
  { ...telemetry event }
]

GET/api/telemetry-stream

Server-sent events stream of telemetry, pushed once per second.

Response

event stream:
data: [ { ...telemetry event }, ... ]

POST/api/kernel/route

Intent classification only, no execution. Returns which agent would be routed to without running anything.

Body

{
  "text": "string (required)"
}

Response

{
  "primaryAgent": "phillomena",
  "supportingAgents": ["helix", "forge", "beacon"]
}

POST/api/kernel/execute

Routes and runs the full multi-agent collaboration, same engine as /api/task, reshaped as a step-by-step execution trace.

Body

{
  "text": "string (required)",
  "context": "any (optional)",
  "taskId": "string (optional)"
}

Response

{
  "trace": [ { "agent", "input", "output", "timestamp" } ],
  "finalOutput": "string"
}

GET/api/kernel/context

Returns the current memory graph — every node and edge written so far.

Response

{
  "nodes": [ { "id", "type", "data" } ],
  "edges": [ { "from", "to", "type" } ]
}

POST/api/kernel/memory

Writes nodes and/or edges into the shared memory graph.

Body

{
  "nodes": [ { "id", "type", "data" } ],
  "edges": [ { "from", "to", "type" } ]
}

Response

{
  "nodes": [ ... ],
  "edges": [ ... ]
}

Founders Code API

The versioned endpoint is a stateless code-generation API. It forces a selected team of real XIV agents (Sage, Atlas, Helix, Forge — toggleable per request) through the same kernel that powers everything else, with the integration step instructed to return a summary plus delimited file blocks. File extraction is best-effort parsing of the model’s output, not a guaranteed schema — malformed blocks are simply left out of files rather than failing the request. Note: versioned as documented here at /api/v1/..., consistent with every other endpoint on this page, rather than a bare /v1/... path.

POST/api/v1/founders-code

Generates code for a task using a forced multi-agent team (Sage, Atlas, Helix, Forge by default).

Body

{
  "task": "string (required)",
  "language": "string (optional)",
  "framework": "string (optional)",
  "context": "string (optional)",
  "files": [ { "path": "string", "content": "string" } ],
  "agents": {
    "useAtlas": true,
    "useHelix": true,
    "useSage": true,
    "useForge": true
  }
}

Response

{
  "result": "string",
  "files": [ { "path": "string", "content": "string" } ],
  "analysis": { "atlas": "string", "helix": "string", "sage": "string" },
  "workflow": {
    "steps": [ { "agent", "action", "output" } ]
  }
}

Authenticated workbench

The workbench requires a Phillomena account. It supports code generation, debugging, refactoring, architecture design, framework adaptation, API integration, DevOps configuration, defensive source review, performance analysis, and coordinated agent workflows. Attachments are limited to 12 text files (24 KB each, 100 KB total) and are used only for that run. Generated files are downloadable for manual review and application; the workbench does not edit a connected repository or deploy generated applications. Optional feedback stores only the account, capability, and 1–5 rating. It never stores the prompt or source files for learning; ratings are account-scoped and can be deleted.

POST/api/founders-code/run

Requires a Phillomena session cookie. Runs the chosen capability through the selected specialist team and returns generated files plus an execution trace.

Body

{
  "capability": "code-generation | debugging | refactoring | architecture | framework-adaptation | api-integration | devops | security-review | performance | multi-agent-workflow",
  "task": "string (required, max 12,000 characters)",
  "language": "string (optional)",
  "framework": "string (optional)",
  "context": "string (optional, max 4,000 characters)",
  "files": [ { "path": "string", "content": "string" } ],
  "agents": [ "atlas", "helix", "sage", "forge" ]
}

Response

{
  "requestId": "uuid",
  "result": "string",
  "files": [ { "path": "string", "content": "string" } ],
  "analysis": { "atlas": "string", "helix": "string", "sage": "string" },
  "workflow": { "steps": [ { "agent", "action", "output" } ] }
}

POST/api/founders-code/feedback

Requires a Phillomena session cookie. Saves an explicit 1–5 rating for one completed request; it does not accept or store prompt or source text.

Body

{
  "requestId": "uuid",
  "capability": "one supported capability",
  "rating": 1
}

Response

{ "ok": true }

Founders Code CLI

The installable command-line tool: design, generate, refactor, and explain each call the endpoint below, authenticated with the same account system used everywhere else on Phillomena.

npm install --global founders-code-cli
founders-code login
founders-code init
founders-code design "plan a multi-tenant billing system"
founders-code generate "add a health check endpoint"
founders-code refactor src/server.ts
founders-code explain src/server.ts

Install the CLI globally from npm (Node.js 20+), then sign in once. It uses https://phillomena.com by default, reads only explicitly selected files, and asks before writing generated changes. The npm package is prepared but not yet published, so the global install command will work after its public npm release.

Use Founders Code in your IDE

VS Code has a native extension in the repository; VS Code, Zed, and JetBrains IDEs can also connect through the CLI's MCP server. After installing and signing in, run the setup command for your IDE and add its output to the IDE's MCP configuration. MCP results are returned for review and are never applied automatically.

founders-code mcp setup vscode
founders-code mcp setup zed
founders-code mcp setup jetbrains

POST/api/founders-code/execute

Requires login (the same session cookie as the rest of the app). Runs the given mode through Synergos XIV and returns a plan, generated files, an explanation, and suggested next actions.

Body

{
  "mode": "generate | design | refactor | explain | scaffold",
  "input": "string (required)",
  "repo_state": {
    "files": [ { "path": "string", "content": "string" } ],
    "dependencies": [ "string" ],
    "agents": [ "string" ],
    "orchestrator": {}
  },
  "context": {
    "user_goals": [ "string" ],
    "venture": "string (optional)",
    "domain": "restaurant | finance | health | general (optional)",
    "skill_level": "non-technical | vibe-coder | developer | founder"
  }
}

Response

{
  "plan": "string",
  "code": [ { "path": "string", "content": "string" } ],
  "explanation": "string",
  "actions": [ "apply_diff", "open_file", "visualize_flow" ]
}

Provider status

Each XIV agent is assigned an LLM provider (Anthropic, OpenAI, Gemini, or xAI). When a provider’s API key isn’t configured, that agent returns an honest “provider unavailable” message instead of a fabricated answer — the system degrades gracefully rather than pretending.