Core API
PATENT PENDING — Ma'atara Protocol. Source reviewed 21 September 2026.
Base URL: api.ma-atara.io. Use the deployed OpenAPI contract and capability response for endpoint details. Source changes can precede deployment.
Discovery
| Method and path | Auth | Purpose |
|---|---|---|
GET /health | none | Liveness and service identity |
GET /api/version | none | Build identity |
GET /api/capabilities | none | Algorithms and configured capabilities |
GET /api/meta | none | Metadata and endpoint summary |
GET /openapi.json | none | Public API schema |
Native algorithm labels are ml-dsa-65, ml-kem-768 and sha3-384. A health response does not prove full service readiness or external publication.
Protected integration
Send a fresh Authorization: MaataraAssertion <assertionB64u>.<signatureB64u> for each protected request. Use the exact route audience and current identity/device authority. See Authentication. App sign-in sessions do not replace this contract.
| Method and path | Auth | Purpose |
|---|---|---|
GET /api/anchors | none | List service anchor records |
POST /api/anchors | assertion | Submit an owner/policy-authorized anchor |
POST /api/anchors/publish-callback | service signature | Record publisher transaction metadata |
GET /api/sync/status | assertion | Encrypted backup status |
GET /api/notes/:did/storage | owner assertion | Storage usage |
POST /api/headers/prepare | assertion | Supported transport-header preparation |
POST /api/pqc/verify | none | Signature verification |
Storage usage returns { did, bytesUsed, objectCount, measuredAt }. A missing or rejected response must not be treated as an empty writable store.
Records and indexing
Current Core code includes native v4 reads and appends with configured acceptance/retirement gates. The former statement that Core is v3-only is obsolete. Preserve the declared record profile and use SDK validation; never relabel a stored record.
Chain reads may return indexing: { state, done, total } while rebuilding a projection. Display progress and poll until complete. Do not treat a partial indexed result as full history or use it to produce an anchor over an incomplete chain.
Encrypted Notes
New writes use encrypted Notes v2. Title, body, tags, attachment names/types and private display metadata remain inside endpoint-created ciphertext. Requests carry only the supported envelope and required public routing/evidence fields. Use the approved client integration; do not reconstruct the internal encryption or signing grammar.
Plaintext-bearing writes and non-native records are rejected. A 409 non_native_note_record is not permission to downgrade or submit plaintext. Temporary account healing is retired (HTTP 410), not a migration service.
Current-word recovery depends on the supported enrolled recovery state and surviving historical key material where required. It cannot recreate lost historical random keys. Whole-profile erasure can remove local rollback evidence; do not present it as a safe recovery procedure.
Device and rotation boundaries
Device verification is implemented and enabled in checked production source configuration. It verifies attestation, origin, capability, revocation and epoch. Delegation-aware root rotation has a separate gate and must not be inferred from device verification being enabled. Source configuration is not a live deployment receipt.
See Public API surface for endpoint-specific audiences, errors and origin requirements, and Anchors for publication limits.