Reference
HTTP API
How clients reach the SEIF engine REST surface — OpenAPI is the contract; this page orients integrators and Hub proxy users.
Canonical contract: the engine OpenAPI document at
/v1/spec/openapi.json. This page is an orientation, not an endpoint encyclopedia — verify paths and schemas against OpenAPI before coding.
Surfaces that call the engine
| Client | How |
|---|---|
| seif-web Hub | Browser → /api/engine/* (session cookie) → engine with healed engineSessionToken |
| CLI / MCP | Bearer API key or login session against the engine base URL |
| seif-log | Separate transparency service; web uses /api/log/* and /explore |
Auth patterns (summary)
| Pattern | Use |
|---|---|
| OAuth + session exchange | Humans on seif-web (Auth.js → POST /v1/auth/session/exchange) |
| API keys | Automation / CLI (POST /v1/auth/api-keys after session) |
| Workspace membership grants | Access tab → POST …/grants (read|contribute|maintain|admin) |
See Access and roles.
Common Hub-facing groups
Exact paths and schemas live in OpenAPI. Conceptually:
| Group | Purpose |
|---|---|
| Auth / session | Login exchange, API keys |
| Workspaces / pods | Registry, sync HEAD (CAS-first) |
| Membership / grants | Access tab roles |
| Artifacts / propose | Envelope create after human approve |
| Sign / evidence | Provenance URLs |
| Verify / log proofs | Transparency chain |
Example shapes (illustrative — verify against OpenAPI before coding):
| Method | Path | Purpose |
|---|---|---|
POST | /v1/auth/session/exchange | Web ↔ engine session |
POST | /v1/sign | Sign content → Evidence URL |
GET | /v1/verify/:hash | Verify by hash |
GET | /v1/evidence/:id | Fetch evidence record |
POST | /v1/classify | Classification gate |
CAS-first note
Governance source of truth for Hub + CLI is the CAS HEAD on the engine. Integrators should treat sync HEAD / blob reads as the store of truth for workspace artifacts.
See also
- Reference overview
- Web first touch — human path
- MCP tools — agent tool catalog