REST API reference
The Nebbos platform exposes 1,652 endpoints under a single versioned base URL: https://api.nebbos.ai/api/v1. Every write operation carries the same identity, tier, and audit-chain semantics as the MCP surface; the REST layer provides an ergonomic HTTP interface over the same substrate.
Base URL and versioning
Every endpoint is served under https://api.nebbos.ai/api/v1. Unprefixed paths are legacy-bootstrap only and are not part of the public API surface.
Versions are URI-prefixed (/api/v1/, /api/v2/, and so on). Two minor versions are supported concurrently. Deprecated versions remain in operation for a minimum of twelve months following deprecation announcement.
The machine-readable specification is served at https://api.nebbos.ai/api/v1/openapi.json. See OpenAPI spec for consumption paths (Postman, Insomnia, client generators).
Endpoint categories
The 1,652 endpoints are organised into eight functional surfaces. Each surface applies the same authentication, tier gating, and audit-chain semantics; the row shapes differ per category.
| Category | Purpose |
|---|---|
| Identity & authentication | Session lifecycle, WebAuthn ceremonies, delegation tokens, and enclave attestations. Identity resolution here precedes every other endpoint. |
| Operators, departments, workspaces | Read and write the organisational structure within which a Pearl operates. Workspace users, groups, and org-units are the identity fabric referenced by every audit event. |
| Projects, tasks, decisions | Operational-work tracking. Writes require an authored justification and a measurable verification criterion. |
| Pearls & knowledge graph | Department-scoped reasoning, memory registers, knowledge-graph queries and mutations, playbook selection, prediction retrieval. |
| Signals | Cross-domain risk signals produced by the Orchestrator. Acknowledgement carries the human-token attribution tuple. |
| Audit chain | Read the hash-chained audit log. List entries, retrieve entries with hash context, verify chain segments with a signed receipt. |
| Files & attachments | Upload, download, and index the operator-scoped file store. Every upload is row-level isolated and produces a chain entry. |
| Admin & substrate | Substrate mutation, organisation creation and dissolution, doctrine-cluster ratification. Architect-tier only; enclave-signed approval required. |
Error envelope
Every non-2xx response returns a JSON envelope with the following structure:
{
"code": "policy.refusal.tier_mismatch",
"message": "This operation requires Host tier; caller is Guest.",
"policy_id": "IDENT-POLICY-042",
"audit_event_id": "evt_01H8YMK7ZQV3D4XCJ9RM8W2N5T",
"correlation_id": "req_01H8YMK7ZQ..."
}| Field | Definition |
|---|---|
code | Stable machine-readable identifier. Suitable for programmatic branching in integration code. |
message | Human-readable description of the error condition. |
policy_id | Identifier of the substrate policy that produced the refusal, when applicable. |
audit_event_id | Identifier of the audit-chain entry recording the refusal. Retrieve for full context. |
correlation_id | Request-scoped identifier for tracing the failure across services. |
Every refusal is associated with a named policy. Every policy is documented. Integration code should branch on code and log policy_id and audit_event_id for downstream diagnostics.
Related references
- Authentication & tiers — the three-tier authentication model.
- Rate limits & quotas — per-tier request ceilings.
- Versioning & changelog — change semantics and version support commitments.
- MCP reference — the same substrate over the Model Context Protocol.