HTTP API reference

Authenticate with a session cookie (browser) or Authorization: Bearer icm_xxx (CLI / MCP). All data endpoints return 401 if unauthenticated; data is scoped to the requesting user.

Auth

POST   /auth/signup         Body: { email, password, displayName? }
POST   /auth/login          Body: { email, password }
POST   /auth/logout
GET    /auth/me             Returns { user, via: "session" | "api_key" }

API keys

GET    /api-keys
POST   /api-keys            Body: { name, expiresInDays? }
                            Returns the bearer token ONCE in the response.
DELETE /api-keys/:id

Objects (encrypted content envelopes)

PUT    /objects/:hash       Body: application/octet-stream
                            Server verifies sha256(body) === :hash.
GET    /objects/:hash       → application/octet-stream
HEAD   /objects/:hash       Existence check

Wraps (encrypted CEK envelopes)

PUT    /wraps/:hash         Body: 66 bytes (the wrap envelope).
                            The matching object must already exist.
GET    /wraps/:hash
DELETE /wraps/:hash

Refs (CAS-protected pointers)

GET    /refs/:name
PUT    /refs/:name          Body: { hash, expect: string | null }
                            "expect" is the etag CAS — null to create.
                            Also accepts If-Match header.
DELETE /refs/:name          Requires If-Match header.

Commits (parent-link index)

PUT    /commits/:hash       Body: { parent: hash | null }
                            The commit object must already exist.
GET    /commits?from=hash&limit=N
                            Walks the parent chain.
GET    /commits/:hash       Single commit metadata.

Health

GET    /health              Public, no auth.