Docs
Quick start
Go 1.27+. Everything below runs against the single binary with embedded SQLite — no external services.
1 · Build & run
# one static binary, embedded SQLite CGO_ENABLED=0 go build -o purplesparrow ./cmd/purplesparrow PS_ADMIN_API_KEY=ps_sk_dev ./purplesparrow # → 127.0.0.1:8787
2 · Create a table
id (uuid) and created_at are added automatically. Types: text, integer, real, boolean, timestamp, uuid, json.
curl -H "Authorization: Bearer ps_sk_dev" localhost:8787/v1/tables -d '{
"name": "todos",
"columns": [{"name":"title","type":"text"},
{"name":"owner_id","type":"text"}] }'
3 · Grant access (deny-by-default)
Nothing is readable until a policy says so. Policies compile to parameterized SQL and support using (which rows) and check (allowed new values).
curl -H "Authorization: Bearer ps_sk_dev" localhost:8787/v1/policies -d '{
"table": "todos", "action": "select",
"roles": ["authenticated"],
"using": "auth.uid() = owner_id" }'
4 · Records
POST /v1/tables/todos/records # insert (object or array)
GET /v1/tables/todos/records?done=eq.false&order=created_at.desc&limit=20
GET /v1/tables/todos/records/{id}
PATCH /v1/tables/todos/records/{id}
DELETE /v1/tables/todos/records/{id}
Filters are ?column=op.value with op in eq, ne, lt, lte, gt, gte, like, in.
API surface
| Area | Endpoints |
|---|---|
| Tables | POST /v1/tables · GET /v1/tables · GET/DELETE /v1/tables/{t} |
| Records | POST/GET /v1/tables/{t}/records · GET/PATCH/DELETE …/{id} |
| Policies | POST /v1/policies · GET /v1/tables/{t}/policies |
| Auth | /v1/auth/signup · login · refresh · me · api-keys · /.well-known/jwks.json |
| Agent | GET /meta · GET /docs · GET /advisor · /v1/memory/{ns}/{key} |
| Ops | GET /healthz · GET /readyz · GET /v1 |
CLI
purplesparrow # serve (default) purplesparrow mcp # MCP stdio server for coding agents purplesparrow mcp-config # print an MCP client config snippet purplesparrow version
Connect an agent (MCP)
Run purplesparrow mcp-config and drop the snippet into your agent's MCP config (Cursor, Claude, …). It launches purplesparrow mcp, which exposes the backend as tools: fetch_docs, get_meta, list_tables, create_table, query_records, insert_record, create_policy, run_advisor.
Configuration
| Variable | Default | Meaning |
|---|---|---|
PS_ADDR | 127.0.0.1:8787 | listen address (use 0.0.0.0:8787 in containers) |
PS_ADMIN_API_KEY | (solo: generated) | admin key; required for non-solo tiers |
PS_DATABASE_URL | (unset → SQLite) | Postgres DSN for the scale tier |
PS_DATA_DIR | ./.purplesparrow | data directory (DB file is 0600) |
Errors are an agent affordance: every non-2xx carries
code, message, remediation, next_actions, and a doc_ref. Read them — they tell you (or your agent) how to recover.