API introduction

Authentication, base URL, and scope of the current FamilyCo API reference.

The FamilyCo server exposes a Fastify HTTP API. Every workflow surface — chat, agents, projects, tasks, inbox, audit, budget, skills, tools, plugins, automation, providers — has a corresponding controller under apps/server/src/modules/<module>.

Base URL

Mode	Base URL
Local server	http://127.0.0.1:4000
Electron desktop	The embedded server picks a free port at startup.

Most routes live under the API_PREFIX (default /api/v1). The health endpoint is served at /health.

Authentication

The API supports two auth modes. Both are described in detail in Auth and access control.

API key

Send your key in the Authorization header:

Authorization: Bearer <FAMILYCO_API_KEY>

API keys are stored as ApiKeyRecord rows. Only the hash is persisted; the raw value is returned exactly once at creation. The API_KEY_SALT env var is used for hashing — see Configuration.

JWT

Mint a short-lived JWT from an API key, then use it like a bearer token:

Authorization: Bearer <jwt>

JWTs are signed with JWT_SECRET.

Authorization

• All non-token routes require API key or JWT authentication.
• Route access enforces a minimum agent level: L0 (executive), L1 (manager), or L2 (worker).
• API key lifecycle operations (create / revoke / rotate) are auditable.

Read-only mode

If startup migration safety fails, the server enters read-only mode. Mutation requests return:

{
  "statusCode": 503,
  "code": "READ_ONLY_MODE",
  "message": "Application is in read-only mode because database migration failed"
}

The health endpoint reports queue stats, migration status, and read-only mode.

Module layout

The server registers controllers per module. The current set:

• auth — API keys, JWT issuance.
• agent — agent management and chat.
• approval — approvals and resolutions.
• audit — audit log queries.
• budget — usage and caps.
• cron — recurring automation.
• dashboard — aggregated views.
• engine — queue and run inspection.
• inbox — Founder queue.
• knowledge — knowledge artifacts.
• plugins — plugin discovery and enablement.
• project — project CRUD.
• provider — provider connections.
• settings — settings store.
• setup — first-run setup.
• skills — skill discovery and toggling.
• task — task CRUD and execution.
• tools — tool policy and custom fields.

For per-module behavior, contracts, and constraints, see the Modules section.

Current reference scope

The API reference pages in this docs site currently cover:

• Core endpoints used during setup and runtime checks:
  • GET /health
  • POST /api/v1/auth/token
• Knowledge endpoints:
  • GET /api/v1/knowledge/commands
  • GET /api/v1/knowledge/converter/status
  • GET /api/v1/knowledge/documents
  • POST /api/v1/knowledge/documents/upload
  • POST /api/v1/knowledge/documents/{id}/index
  • GET /api/v1/knowledge/documents/{id}/chunks
  • DELETE /api/v1/knowledge/documents/{id}
  • POST /api/v1/knowledge/retrieve

Additional module endpoints already exist in the server and shared UI contracts and can be added to this API reference incrementally.