> ## Documentation Index
> Fetch the complete documentation index at: https://familyco.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/modules/auth).

### API key

Send your key in the `Authorization` header:

```http theme={null}
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](/guides/configuration).

### JWT

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

```http theme={null}
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:

```json theme={null}
{
  "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](/modules/chat) 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.