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

AreaEndpoints
TablesPOST /v1/tables · GET /v1/tables · GET/DELETE /v1/tables/{t}
RecordsPOST/GET /v1/tables/{t}/records · GET/PATCH/DELETE …/{id}
PoliciesPOST /v1/policies · GET /v1/tables/{t}/policies
Auth/v1/auth/signup · login · refresh · me · api-keys · /.well-known/jwks.json
AgentGET /meta · GET /docs · GET /advisor · /v1/memory/{ns}/{key}
OpsGET /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

VariableDefaultMeaning
PS_ADDR127.0.0.1:8787listen 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./.purplesparrowdata 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.