---
title: "Developers — Barestate"
description: "Developer portal: REST API, OpenAPI spec, MCP server, and every machine-readable resource on barestate.xyz."
canonical: https://barestate.xyz/developers
---

# Developers

Everything machine-readable on barestate.xyz, in one place.

## REST API

- **OpenAPI 3.1 spec:** `GET /openapi.json`
- **Health:** `GET /api/health` — classifier mode, provider availability, persistence status.
- **Preview:** `POST /api/preview` — inspect the exact request a model provider would receive before anything is sent. Guests welcome.
- **Send:** `POST /api/send` — dispatch an approved preview; Bearer-authed, payload-hash-checked.
- **Reset:** `POST /api/reset` — release a preview session.
- **Batch:** `POST /api/batch` — up to 10 operations in one request.
- **Async:** `Prefer: respond-async` on `POST /api/preview` → `202` + job at `GET /api/preview/jobs/{id}`.
- **Product MCP:** `POST /api/mcp` — JSON-RPC tools `api_health`, `create_preview`, `reset_session`.
- **Agent auth (declared):** `POST /api/agent/identity|claim|events` — reachable, report `enabled:false` until an agent-native grant ships.
- **Persistence:** `/api/keys`, `/api/devices`, `/api/device-transfers`, `/api/conversations`, `/api/projects`, `/api/files`, `/api/memories`, `/api/settings`, `/api/connections`, `/api/usage` — all `Authorization: Bearer <token>` from workspace sign-in.

## Conventions

- **Versioning:** `API-Version: 1` on every response; `/api/v1/*` path alias; deprecation announced via `Deprecation`/`Sunset` headers 6 months ahead.
- **Rate limits:** RFC `RateLimit-*` headers; `429` includes `Retry-After`. Policy: `5` sends/day for hosted, `20`/min burst.
- **Pagination:** cursor-based — `?cursor=&limit=` → `items` + `nextCursor`.
- **Idempotency:** `Idempotency-Key` header on `POST /api/send`; retries replay the stored response.
- **Errors:** JSON `{ok:false, reason:"<slug>"}` with a human note; protected routes answer `401` + `WWW-Authenticate: Bearer resource_metadata=…`.
- **Sandbox:** `route.provider: "mock"` — canned replies, no provider call, no quota cost.
- **NL search:** `GET|POST /ask?q=` — NLWeb JSON, or `Accept: text/event-stream` for SSE.

## Examples

```bash
curl -s https://barestate.xyz/api/health
curl -s -X POST https://barestate.xyz/api/preview \
  -H 'content-type: application/json' \
  -d '{"envelope":{"text":"hello"},"route":{"provider":"mock"}}'
curl -s https://barestate.xyz/ -H 'Accept: text/markdown'
curl -s -X POST https://barestate.xyz/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -s "https://barestate.xyz/ask?q=privacy+preview"
```

## Authentication

`GET /auth.md` — the auth guide for agents: which surfaces are public, which need a Bearer token, and how the token is issued. There is no self-serve API key yet; tokens come from signing in at `/app`.

## MCP server

`POST /mcp` — streamable-HTTP Model Context Protocol endpoint. Read-only tools: `list_pages`, `read_page`, `read_resource`, `api_health` (docs + product on one surface). The product-only surface is `POST /api/mcp` (`api_health`, `create_preview`, `reset_session`). Server card at `/.well-known/mcp/server-card.json`.

## Machine-readable resources

- `/llms.txt` — agent-facing site guide; `/developers/llms.txt` — this section scoped.
- `/markdown/<page>.md` and `/<page>.md` — every page as Markdown.
- `Accept: text/markdown` — negotiate Markdown on any page (with `Vary: Accept`).
- `?mode=agent` — JSON agent view of any page: endpoints, auth, capabilities.
- `/.well-known/ard.json` — ARD resource catalog.
- `/.well-known/api-catalog` — RFC 9727 linkset for the API.
- `/.well-known/agent-skills/index.json` — skills index; docs under `/skills/*.md`.
- `/sitemap.xml`, `/schemamap.xml`, `/feed.xml`, `/robots.txt`.

## Source

Site and API live in the open at [github.com/barestate-ai/barestate-lp](https://github.com/barestate-ai/barestate-lp).