API overview
# API overview
Everything in Homestead goes through one API. The web app, the phone app, the Firefox
companion and AI agents all call the same REST endpoints. There's no private back door for the
app.
## REST
- **Base path:** `/api/v1` on your Homestead, for example `http://localhost:8080/api/v1`.
- **Format:** JSON, except media uploads (`multipart/form-data`) and a few companion uploads.
- **Spec:** [`api/openapi.yaml`](https://github.com/aprajnaparamita/homestead/blob/main/api/openapi.yaml),
OpenAPI 3.1, title "Homestead API", version 1.0.0. It's the source of truth: the Go server,
the TypeScript client and the Dart client are generated from it.
- **Versioning:** within v1, changes are additive. Breaking changes would need `/api/v2`.
The spec groups operations under these tags: system, auth, household, platforms, people,
accounts, circles, shares, feed, media, agents, sources, extension and ai.
It also uses four vendor extensions:
| Extension | Meaning |
| --- | --- |
| `x-min-role` | Minimum member role: `viewer`, `member` or `owner` |
| `x-required-scopes` | Agent token scopes needed. Absent means agent tokens are refused. |
| `x-public` | No authentication needed |
| `x-capture-upload` | Accepts the short-lived `hsu_` upload token of one capture |
<Aside type="note">
Operations for the companion's captures and update runs, and for AI settings, are in the spec
but return `501 not_implemented` on `main` until their tasks land. The generated reference
marks them.
</Aside>
## MCP
Agents can also use the **MCP server** at `/mcp` (Streamable HTTP), with the same agent token in
an `Authorization` header. It has 19 tools, 3 resources and 3 prompts. Each tool maps to exactly
one REST operation and runs the same code, with inputs generated from the OpenAPI schemas so
they can't drift. MCP isn't part of the OpenAPI file; see the [MCP reference](/docs/api/mcp/).
For clients that only launch stdio servers, `homestead mcp-stdio --url URL --token hst_…`
bridges stdio to `/mcp`.
## Who uses what
| Client | Auth | Notes |
| --- | --- | --- |
| Web app (same origin) | Session cookie `hs_session` plus an `X-CSRF-Token` header on writes | Sign in with `POST /auth/login` and `"client": "web"` |
| Phone app | `Authorization: Bearer hsd_…` device token | From sign-in with `"client": "device"`, or QR pairing |
| Firefox companion | `hsd_…` device token of kind `extension` | Paired with `POST /auth/pair` and `"client": "extension"` |
| Homestead Helper | `hsu_…` capture upload token | One capture, 10 minutes, asset uploads only |
| Agents and scripts (REST) | `Authorization: Bearer hst_…` agent token with scopes | Created on the Agents screen or with `homestead token create` |
| Agents (MCP) | The same agent token, as a header to `/mcp` | Tools the token can't use aren't listed |
Details in [Authentication](/docs/api/authentication/).
## A first request
The health endpoint needs no authentication:
```bash
curl http://localhost:8080/api/v1/health
```
```json
{"status":"ok","version":"dev"}
```
## Read on
<CardGrid>
<LinkCard title="Authentication" description="Sessions and CSRF, device, agent and upload tokens, roles and scopes." href="/docs/api/authentication/" />
<LinkCard title="Conventions" description="IDs, time, unknown fields, pagination, idempotency, rate limits, media URLs, CORS." href="/docs/api/conventions/" />
<LinkCard title="Errors" description="Problem details and the stable error codes." href="/docs/api/errors/" />
<LinkCard title="Examples" description="curl for health, resolve, quick-add, feed and a full fetch round." href="/docs/api/examples/" />
<LinkCard title="MCP" description="Tools, resources and prompts for agents." href="/docs/api/mcp/" />
<LinkCard title="REST reference" description="Every operation and schema, generated from the OpenAPI file." href="/docs/api/reference/" />
</CardGrid>
Everything in Homestead goes through one API. The web app, the phone app, the Firefox companion and AI agents all call the same REST endpoints. There’s no private back door for the app.
- Base path:
/api/v1on your Homestead, for examplehttp://localhost:8080/api/v1. - Format: JSON, except media uploads (
multipart/form-data) and a few companion uploads. - Spec:
api/openapi.yaml, OpenAPI 3.1, title “Homestead API”, version 1.0.0. It’s the source of truth: the Go server, the TypeScript client and the Dart client are generated from it. - Versioning: within v1, changes are additive. Breaking changes would need
/api/v2.
The spec groups operations under these tags: system, auth, household, platforms, people, accounts, circles, shares, feed, media, agents, sources, extension and ai.
It also uses four vendor extensions:
| Extension | Meaning |
|---|---|
x-min-role | Minimum member role: viewer, member or owner |
x-required-scopes | Agent token scopes needed. Absent means agent tokens are refused. |
x-public | No authentication needed |
x-capture-upload | Accepts the short-lived hsu_ upload token of one capture |
Agents can also use the MCP server at /mcp (Streamable HTTP), with the same agent token in
an Authorization header. It has 19 tools, 3 resources and 3 prompts. Each tool maps to exactly
one REST operation and runs the same code, with inputs generated from the OpenAPI schemas so
they can’t drift. MCP isn’t part of the OpenAPI file; see the MCP reference.
For clients that only launch stdio servers, homestead mcp-stdio --url URL --token hst_…
bridges stdio to /mcp.
Who uses what
Section titled “Who uses what”| Client | Auth | Notes |
|---|---|---|
| Web app (same origin) | Session cookie hs_session plus an X-CSRF-Token header on writes | Sign in with POST /auth/login and "client": "web" |
| Phone app | Authorization: Bearer hsd_… device token | From sign-in with "client": "device", or QR pairing |
| Firefox companion | hsd_… device token of kind extension | Paired with POST /auth/pair and "client": "extension" |
| Homestead Helper | hsu_… capture upload token | One capture, 10 minutes, asset uploads only |
| Agents and scripts (REST) | Authorization: Bearer hst_… agent token with scopes | Created on the Agents screen or with homestead token create |
| Agents (MCP) | The same agent token, as a header to /mcp | Tools the token can’t use aren’t listed |
Details in Authentication.
A first request
Section titled “A first request”The health endpoint needs no authentication:
curl http://localhost:8080/api/v1/health{"status":"ok","version":"dev"}Read on
Section titled “Read on”AuthenticationSessions and CSRF, device, agent and upload tokens, roles and scopes.
ConventionsIDs, time, unknown fields, pagination, idempotency, rate limits, media URLs, CORS.
ErrorsProblem details and the stable error codes.
Examplescurl for health, resolve, quick-add, feed and a full fetch round.
MCPTools, resources and prompts for agents.
REST referenceEvery operation and schema, generated from the OpenAPI file.