{ "openapi": "3.1.0", "info": { "title": "Ma'atara Core API", "version": "1.5.2", "description": "Core discovery, sync, deterministic header prep, governance, anchors. Stateless auth only: Authorization: MaataraAssertion ." }, "externalDocs": { "url": "https://docs.ma-atara.io/developer", "description": "Ma'atara Protocol overview" }, "servers": [ { "url": "https://api.ma-atara.io" } ], "components": { "securitySchemes": { "maataraAssertion": { "type": "http", "scheme": "bearer", "bearerFormat": "MaataraAssertion" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "rate_limited", "unsupported_alg", "internal_error" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} }, "retryAfter": { "type": "number" } }, "required": [ "code", "message" ] }, "ApiResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": {}, "error": { "type": "string" }, "timestamp": { "type": "number" } }, "required": [ "success" ] }, "VeritasBlock": { "type": "object", "properties": { "index": { "type": "string" }, "timestamp": { "type": "string" }, "previousHash": { "type": "string" }, "dataHash": { "type": "string" }, "metadataHash": { "type": "string" }, "signature": { "type": "string" }, "signatureAlg": { "type": "string", "enum": [ "ml-dsa-65" ] }, "ownerPublicKey": { "type": "string", "description": "ML-DSA-65 public key (base64url)." }, "contentType": { "type": "string" }, "version": { "type": "number", "enum": [ 2, 3 ] } }, "required": [ "index", "timestamp", "previousHash", "dataHash", "metadataHash", "signatureAlg", "ownerPublicKey", "version" ], "description": "Native Core chain block using the version-3 ML-DSA-65 profile." }, "HealthData": { "type": "object", "properties": { "service": { "type": "string" }, "version": { "type": "string" }, "timestamp": { "type": "number" }, "environment": { "type": "string" } }, "required": [ "service", "version", "timestamp" ] }, "SyncStatusData": { "type": "object", "properties": { "hasBackup": { "type": "boolean" }, "lastSync": { "type": [ "number", "null" ] }, "userId": { "type": "string" } }, "required": [ "hasBackup" ] }, "ApiMetaData": { "type": "object", "properties": { "openapi": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } }, "required": [ "openapi", "docs" ] }, "CapabilitiesData": { "type": "object", "properties": { "version": { "type": "string" }, "commit": { "type": "string" }, "authSchemes": { "type": "array", "items": { "type": "string" } }, "features": { "type": "object", "properties": { "headerPrepare": { "type": "boolean" }, "pqc": { "type": "object", "properties": { "mlKem": { "type": "array", "items": { "type": "string", "enum": [ "ml-kem-768" ] } }, "mlDsa": { "type": "array", "items": { "type": "string", "enum": [ "ml-dsa-65" ] } } }, "required": [ "mlKem", "mlDsa" ] } }, "required": [ "headerPrepare", "pqc" ] }, "storage": { "type": "object", "properties": { "default": { "type": "string", "enum": [ "ipfs" ] }, "gateway": { "type": "string" }, "pinning": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "r2", "external-http" ] }, "providers": { "type": "array", "items": { "type": "string", "enum": [ "r2", "external-http" ] } } }, "required": [ "default" ] }, "policy": { "type": "object", "properties": { "headerCanonicalization": { "type": "string", "enum": [ "v2" ] }, "aadHashAlg": { "type": "string" }, "anchorHashAlg": { "type": "string" }, "anchorHashAlgs": { "type": "array", "items": { "type": "string", "enum": [ "sha3-384" ] } }, "dekWrap": { "type": "object", "properties": { "hkdf": { "type": "object", "properties": { "kdf": { "type": "string" }, "salt": { "type": "string" }, "info": { "type": "string" }, "L": { "type": "number" } }, "required": [ "kdf", "salt", "info", "L" ] }, "supported": { "type": "array", "items": { "type": "string" } }, "recommended": { "type": "string" } }, "required": [ "hkdf", "recommended" ] } }, "required": [ "headerCanonicalization", "aadHashAlg", "dekWrap" ] } }, "required": [ "version", "features", "policy" ] }, "IpfsPinRequest": { "type": "object", "properties": { "cid": { "type": "string" }, "name": { "type": "string" } }, "required": [ "cid" ] }, "IpfsPinResponse": { "type": "object", "additionalProperties": {} }, "VersionData": { "type": "object", "properties": { "version": { "type": "string" }, "commit": { "type": "string" }, "buildAt": { "type": "string" } }, "required": [ "version", "buildAt" ] }, "HeadersPrepareRequest": { "type": "object", "properties": { "header": { "type": "object", "properties": { "userId": { "type": "string" }, "noteId": { "type": "string" }, "deviceId": { "type": "string" }, "operation": { "type": "string", "enum": [ "create", "update", "delete", "attach" ] }, "contentType": { "type": "string" }, "contentLength": { "type": "number" }, "timestamp": { "type": "string", "description": "RFC3339 UTC Z" }, "app": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version" ] }, "ext": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "userId", "noteId", "deviceId", "operation", "contentType", "contentLength", "timestamp", "app" ] } }, "required": [ "header" ] }, "HeadersPrepareResponseData": { "type": "object", "properties": { "header": { "type": "object" }, "aadB64u": { "type": "string" }, "policyVersion": { "type": "string" }, "aadHashAlg": { "type": "string" } }, "required": [ "policyVersion", "aadHashAlg", "aadB64u", "header" ] }, "PQCVerifyRequest": { "type": "object", "oneOf": [ { "properties": { "alg": { "type": "string", "enum": [ "ml-dsa-65" ] }, "messageB64u": { "type": "string" }, "signatureB64u": { "type": "string" }, "publicKeyB64u": { "type": "string" } }, "required": [ "alg", "messageB64u", "signatureB64u", "publicKeyB64u" ] }, { "properties": { "alg": { "type": "string", "enum": [ "ml-dsa-65" ] }, "hashAlg": { "type": "string", "enum": [ "sha3-384" ] }, "hashB64u": { "type": "string" }, "signatureB64u": { "type": "string" }, "publicKeyB64u": { "type": "string" } }, "required": [ "alg", "hashAlg", "hashB64u", "signatureB64u", "publicKeyB64u" ] } ] }, "PQCVerifyResponse": { "type": "object", "properties": { "valid": { "type": "boolean" } }, "required": [ "valid" ] }, "GovernancePolicy": { "type": "object", "properties": { "version": { "type": "string", "enum": [ "v1" ] }, "threshold": { "type": "number" }, "signers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "publicKeyB64u": { "type": "string" }, "role": { "type": "string" } }, "required": [ "id", "publicKeyB64u" ] } }, "meta": { "type": "object", "additionalProperties": {} } }, "required": [ "version", "threshold", "signers" ] }, "GovernanceAttestation": { "type": "object", "additionalProperties": false, "properties": { "alg": { "type": "string", "enum": [ "ml-dsa-65" ] }, "publicKeyB64u": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^[A-Za-z0-9_-]+$" }, "signatureB64u": { "type": "string", "minLength": 1, "maxLength": 8192, "pattern": "^[A-Za-z0-9_-]+$" }, "signedAt": { "type": "string", "maxLength": 64, "format": "date-time" } }, "required": [ "alg", "publicKeyB64u", "signatureB64u" ], "description": "Governance attestations use ML-DSA-65." }, "AssetMintHeader": { "type": "object", "additionalProperties": false, "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 1024 }, "action": { "type": "string", "enum": [ "asset/mint" ] }, "assetId": { "type": "string", "minLength": 112, "maxLength": 112, "pattern": "^asset:sha3-384:[0-9a-f]{96}$" }, "timestamp": { "type": "string", "maxLength": 64, "format": "date-time" }, "app": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-z][a-z0-9-]{0,31}$" }, "version": { "type": "string", "minLength": 5, "maxLength": 64, "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$" } }, "required": [ "name", "version" ] } }, "required": [ "userId", "action", "assetId", "timestamp", "app" ] }, "AssetTransferHeader": { "type": "object", "additionalProperties": false, "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 1024 }, "action": { "type": "string", "enum": [ "asset/transfer" ] }, "assetId": { "type": "string", "minLength": 112, "maxLength": 112, "pattern": "^asset:sha3-384:[0-9a-f]{96}$" }, "to": { "type": "string", "pattern": "^did:maatara:[A-Za-z0-9_-]{32}$" }, "timestamp": { "type": "string", "maxLength": 64, "format": "date-time" }, "app": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-z][a-z0-9-]{0,31}$" }, "version": { "type": "string", "minLength": 5, "maxLength": 64, "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$" } }, "required": [ "name", "version" ] } }, "required": [ "userId", "action", "assetId", "to", "timestamp", "app" ] }, "GovernancePolicyRecord": { "type": "object", "properties": { "policyId": { "type": "string" }, "policy": { "$ref": "#/components/schemas/GovernancePolicy" }, "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/GovernanceAttestation" } }, "activatedAt": { "type": "string" }, "activatedBy": { "type": "string" }, "previousPolicyId": { "type": "string" } }, "required": [ "policyId", "policy", "attestations", "activatedAt", "activatedBy" ] }, "AssetCore": { "type": "object", "additionalProperties": false, "properties": { "assetId": { "type": "string", "minLength": 112, "maxLength": 112, "pattern": "^asset:sha3-384:[0-9a-f]{96}$" }, "media": { "type": "object", "additionalProperties": false, "properties": { "mime": { "type": "string", "minLength": 3, "maxLength": 255, "pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$" }, "bytes": { "type": "integer", "minimum": 0 }, "cid": { "type": "string", "minLength": 12, "maxLength": 1024, "pattern": "^(?:Qm[1-9A-HJ-NP-Za-km-z]{44}|baf[a-z2-7]{10,})$" } }, "required": [ "mime" ] }, "royalty": { "type": "object", "additionalProperties": false, "description": "ERC-2981-like. bps 0..10000.", "properties": { "receiver": { "type": "string", "pattern": "^(?:0x[0-9a-f]{40}|did:maatara:[A-Za-z0-9_-]{32})$" }, "bps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "receiver", "bps" ] }, "perceptual": { "type": "object", "additionalProperties": false, "properties": { "algo": { "type": "string", "enum": [ "phash", "dhash", "pdq", "tmk-pdqf-v1" ] }, "hashes": { "type": "array", "maxItems": 64, "items": { "type": "string", "pattern": "^[0-9a-f]+$" } } }, "required": [ "algo", "hashes" ] }, "metadataHash": { "type": "string", "pattern": "^[0-9a-f]{96}$", "description": "Lowercase hexadecimal SHA3-384 commitment to user-held metadata; plaintext metadata is not accepted or returned." } }, "required": [ "assetId", "media" ] }, "AssetRecord": { "type": "object", "additionalProperties": false, "properties": { "header": { "$ref": "#/components/schemas/AssetMintHeader" }, "asset": { "$ref": "#/components/schemas/AssetCore" }, "attestations": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/GovernanceAttestation" } }, "owner": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "transfers": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/AssetTransferEvent" } }, "receipts": { "type": "array", "maxItems": 128, "items": { "$ref": "#/components/schemas/AssetERCReceipt" } } }, "required": [ "header", "asset", "attestations", "owner", "createdAt", "updatedAt" ] }, "AnchorRecord": { "type": "object", "properties": { "anchorId": { "type": "string" }, "root": { "type": "string" }, "epoch": { "type": "string" }, "hashAlg": { "type": "string", "enum": [ "sha3-384" ] }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string" }, "tx": { "type": "string" } }, "required": [ "chain" ] } }, "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/GovernanceAttestation" } }, "createdAt": { "type": "string" } }, "required": [ "anchorId", "root", "epoch", "attestations", "createdAt" ] }, "AssetERCReceipt": { "type": "object", "additionalProperties": false, "properties": { "standard": { "type": "string", "enum": [ "erc721", "erc1155" ] }, "contract": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" }, "tokenId": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "chainId": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "txHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "mappedAt": { "type": "string", "maxLength": 64, "format": "date-time" } }, "required": [ "standard", "contract", "tokenId", "mappedAt" ] }, "AssetTransferEvent": { "type": "object", "additionalProperties": false, "properties": { "header": { "$ref": "#/components/schemas/AssetTransferHeader" }, "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/GovernanceAttestation" } }, "previousOwner": { "type": "string", "minLength": 1, "maxLength": 1024 }, "newOwner": { "type": "string", "minLength": 1, "maxLength": 1024 }, "occurredAt": { "type": "string", "maxLength": 64, "format": "date-time" } }, "required": [ "header", "attestations", "previousOwner", "newOwner", "occurredAt" ] } } }, "security": [], "paths": { "/": { "get": { "summary": "Service banner and entry points.", "tags": [ "meta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } } }, "/health": { "get": { "summary": "Service health", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } }, "head": { "summary": "Liveness probe, headers only.", "tags": [ "meta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } } }, "/openapi.json": { "head": { "summary": "Spec availability probe, headers only.", "tags": [ "meta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } }, "get": { "summary": "This OpenAPI document.", "tags": [ "meta" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } } }, "/api/meta": { "get": { "summary": "API meta/build information", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/version": { "get": { "summary": "Version and protocol info", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionData" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/capabilities": { "get": { "summary": "Capability discovery (algorithms, policies, endpoints)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesData" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/chain/append": { "post": { "summary": "Append a signed native-profile transition block to the user Veritas Chain", "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VeritasBlock" } } } }, "responses": { "201": { "description": "Block appended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "403": { "description": "Invalid signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/chain/head": { "get": { "summary": "Current head block index and hash.", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/chain/blocks": { "get": { "summary": "List blocks in a range.", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/chain/payload/{blockId}": { "get": { "summary": "Fetch a block payload by id.", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "blockId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/chain/rotation/activate": { "post": { "summary": "Activate a pending key rotation on the chain.", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/chain/rotation/current": { "get": { "summary": "Current active key-rotation record.", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/chain/rotation/freeze": { "post": { "summary": "Veto a pending root-key rotation. Device- or root-signed; the freeze payload’s own signature is the credential (PORTAL_DEVICE_KEYS_V1 §2.6).", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/chain/rotation/cosign": { "post": { "summary": "Detached device co-signature on a pending key-rotation.v2 proposal. The co-signature’s own signature is the credential; §6.2 eligibility is checked before the append (PORTAL_DEVICE_KEYS_V1 §6.1/§6.2). Gated by ROTATION_V2.", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/chain/rotation/v2/activate": { "post": { "summary": "Activate a key-rotation.v2 proposal once its 24h broadcast window has elapsed unfrozen/uncancelled, with a co-signer when §6.2 requires one. No admin approval, unlike v1 (PORTAL_DEVICE_KEYS_V1 §6.1/§6.3). Gated by ROTATION_V2.", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/chain/root/{did}": { "get": { "summary": "The DID’s current root public key and epoch. Unauthenticated by design (PORTAL_DEVICE_KEYS_V1 §3.3/§4.5).", "tags": [ "chain" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/security/hold": { "get": { "summary": "Read the security hold state for the caller.", "tags": [ "security" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." }, "post": { "summary": "Place a security hold, freezing chain writes.", "tags": [ "security" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/security/hold/lift": { "post": { "summary": "Lift a security hold.", "tags": [ "security" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/notes/{did}": { "post": { "summary": "Append an encrypted note.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." }, "get": { "summary": "List the caller’s notes.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/export": { "get": { "summary": "Read a bounded cursor page of native note records for export.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/storage": { "get": { "summary": "Storage usage for the caller.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/{noteId}": { "get": { "summary": "Fetch one note.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." }, "delete": { "summary": "Delete one note.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/notes/{did}/{noteId}/versions": { "get": { "summary": "List versions of a note.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/{noteId}/versions/{version}": { "get": { "summary": "Fetch one version of a note.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/cas/{cipherHash}": { "put": { "summary": "Upload an authenticated content-addressed attachment ciphertext before note append.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cipherHash", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." }, "head": { "summary": "Authenticated existence probe for a content-addressed blob.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cipherHash", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/notes/{did}/{noteId}/attachments/{attachmentId}": { "put": { "summary": "Upload an encrypted attachment ciphertext for an existing note.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." }, "get": { "summary": "Fetch an encrypted attachment.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attachmentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/cas/refs": { "get": { "summary": "Reference counts for content-addressed blobs.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/cas/gc": { "post": { "summary": "Garbage-collect unreferenced blobs. Detached owner-key signature over a timestamp within a 5-minute skew, not a bearer assertion.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/notes/{did}/cas/rebuild": { "post": { "summary": "Rebuild the reference index from chain state. Detached owner-key signature over a timestamp, not a bearer assertion.", "tags": [ "notes" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/archive/{did}/inventory": { "get": { "summary": "Enumerate a frozen, DID-scoped archive inventory with bounded pagination.", "tags": [ "archive" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/archive/{did}/objects/{objectId}": { "get": { "summary": "Download one object previously identified by the archive inventory.", "tags": [ "archive" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/inbox/contact-request": { "post": { "summary": "Send a contact request to a DID owner. Rate-limited, OTP-verified.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } } }, "/api/inbox/verify-otp": { "post": { "summary": "Verify the one-time code for a contact request.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } } }, "/api/inbox/{did}": { "get": { "summary": "List inbox messages.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/inbox/{did}/{messageId}": { "delete": { "summary": "Delete an inbox message.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/inbox/{did}/{messageId}/read": { "post": { "summary": "Mark an inbox message read.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/inbox/{did}/{messageId}/reply": { "post": { "summary": "Retired: clients must reply through their own mail client.", "tags": [ "inbox" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/genesis/init": { "post": { "summary": "Create the genesis block for a new identity.", "tags": [ "genesis" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/genesis/{did}": { "get": { "summary": "Fetch a published genesis record.", "tags": [ "genesis" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/identity/speaks-for": { "post": { "summary": "Check whether a public signing key is associated with a supplied DID.", "tags": [ "identity" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } } }, "/api/inception/head": { "post": { "summary": "Read or create the authenticated assertion owner’s inception head.", "tags": [ "inception" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/inception/device": { "post": { "summary": "Incept a device identity under an owner.", "tags": [ "inception" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/inception/device-event": { "post": { "summary": "Record a device lifecycle event.", "tags": [ "inception" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/inception/device-batch": { "post": { "summary": "Incept a batch of device identities.", "tags": [ "inception" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/inception/org": { "post": { "summary": "Incept an organisation identity.", "tags": [ "inception" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/inception/org-officers": { "post": { "summary": "Rotate organisation officers without changing the org DID. No bearer token: authority is an outgoing-officer quorum of PQC attestations, incoming officer acceptances, and an org-key continuity signature (inception.ts:519-591).", "tags": [ "inception" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/anchors": { "get": { "summary": "List recorded anchors", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AnchorRecord" } }, "count": { "type": "number" } } } } } } } }, "post": { "summary": "Record a Merkle super-root with attestations", "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "root": { "type": "string" }, "epoch": { "type": "string" }, "hashAlg": { "type": "string", "enum": [ "sha3-384" ] }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string" }, "tx": { "type": "string" } }, "required": [ "chain" ] } }, "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/GovernanceAttestation" } } }, "required": [ "root", "epoch", "attestations" ] } } } }, "responses": { "200": { "description": "Recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/anchors/eligibility": { "get": { "summary": "Whether this owner should be offered an anchor for their chain (asked at login).", "tags": [ "anchors" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/anchors/state-proof": { "get": { "summary": "Rolling state-proof over last N anchors", "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2048 } }, { "name": "hashAlg", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sha3-384" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "window": { "type": "number" }, "count": { "type": "number" }, "root": { "type": "string" }, "leaves": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "hashAlg": { "type": "string" }, "anchors": { "type": "array", "items": { "type": "object", "properties": { "anchorId": { "type": "string" }, "epoch": { "type": "string" }, "createdAt": { "type": "string" } } } } } } } } } } } }, "/api/anchors/{id}": { "get": { "summary": "Get anchor by id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorRecord" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/assets/mint": { "post": { "summary": "Mint/register an asset in Veritas", "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "header": { "$ref": "#/components/schemas/AssetMintHeader" }, "asset": { "$ref": "#/components/schemas/AssetCore" }, "attestations": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/GovernanceAttestation" } }, "issuedAt": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ] }, "expiresAt": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ] } }, "required": [ "header", "asset", "attestations", "issuedAt", "expiresAt" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/assets/{id}": { "get": { "summary": "Get asset record", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "maataraAssertion": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRecord" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/assets/transfer": { "post": { "summary": "Transfer asset ownership", "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "header": { "$ref": "#/components/schemas/AssetTransferHeader" }, "attestations": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/GovernanceAttestation" } }, "issuedAt": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ] }, "expiresAt": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ] } }, "required": [ "header", "attestations", "issuedAt", "expiresAt" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "404": { "description": "Asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/assets/{id}/export": { "post": { "summary": "Record ERC-721/1155 export receipt for asset", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "standard": { "type": "string", "enum": [ "erc721", "erc1155" ] }, "contract": { "type": "string", "pattern": "^0x[0-9a-f]{40}$" }, "tokenId": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "chainId": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" }, "txHash": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "attestations": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/GovernanceAttestation" } }, "issuedAt": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ] }, "expiresAt": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string", "format": "date-time" } ] } }, "required": [ "standard", "contract", "tokenId", "attestations", "issuedAt", "expiresAt" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "404": { "description": "Asset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/assets/{id}/receipts": { "get": { "summary": "List export receipts for an asset", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "maataraAssertion": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/AssetERCReceipt" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/governance/policy": { "get": { "summary": "Get active governance policy", "security": [ { "maataraAssertion": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernancePolicyRecord" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "404": { "description": "No active policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } }, "post": { "summary": "Publish/activate governance policy", "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/GovernancePolicy" }, "attestations": { "type": "array", "items": { "$ref": "#/components/schemas/GovernanceAttestation" } } }, "required": [ "policy", "attestations" ] } } } }, "responses": { "200": { "description": "Activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernancePolicyRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/governance/audit": { "get": { "summary": "List governance policy versions", "security": [ { "maataraAssertion": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GovernancePolicyRecord" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/sync/status": { "get": { "summary": "Get encrypted chain backup status", "security": [ { "maataraAssertion": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/ipfs/{cid}": { "get": { "summary": "Proxy read from IPFS gateway", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not found" } } } }, "/api/ipfs/pin": { "post": { "summary": "Pin a CID via Cloudflare IPFS Pinning API", "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpfsPinRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpfsPinResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "501": { "description": "Pinning not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/pqc/verify": { "post": { "summary": "Remote ML-DSA-65 signature verification", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PQCVerifyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PQCVerifyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/headers/prepare": { "post": { "summary": "Prepare canonical header and AAD hash", "description": "JCS (RFC 8785) canonicalization. AAD = base64url(SHA3-384(canonical JSON)).", "security": [ { "maataraAssertion": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadersPrepareRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeadersPrepareResponseData" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/pair/offer": { "post": { "summary": "Create an owner-authenticated pairing offer and one-time token.", "tags": [ "pair" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/pair/offer/{code}/join": { "post": { "summary": "Bind a joining device key using the high-entropy pairing token.", "tags": [ "pair" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/pair/offer/{code}": { "get": { "summary": "Retrieve an owned pairing offer with a fresh assertion.", "tags": [ "pair" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." }, "delete": { "summary": "Cancel using a fresh owner assertion or the high-entropy pairing token.", "tags": [ "pair" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/pair/seal": { "post": { "summary": "Seal a pairing exchange as its authenticated identity owner.", "tags": [ "pair" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/pair/seal/{code}": { "get": { "summary": "Atomically consume a sealed result using the high-entropy pairing token.", "tags": [ "pair" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/authorize/offer": { "post": { "summary": "Root mints a cross-device authorization offer code and one-time token.", "tags": [ "authorize" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/authorize/offer/{code}/join": { "post": { "summary": "Joining device binds its DeviceAuthorizationRequest using the offer token.", "tags": [ "authorize" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/authorize/offer/{code}": { "get": { "summary": "Root reads the joined DeviceAuthorizationRequest with a fresh assertion.", "tags": [ "authorize" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." }, "delete": { "summary": "Cancel an authorization offer using the offer token or a fresh root assertion.", "tags": [ "authorize" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/authorize/grant": { "post": { "summary": "Root posts the DeviceGrant (attestation + wrapped MNK) for a joined offer.", "tags": [ "authorize" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/api/authorize/grant/{code}": { "get": { "summary": "Joining device atomically consumes its DeviceGrant using the offer token.", "tags": [ "authorize" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/activation/redeem": { "post": { "summary": "Redeem an activation code for an entitlement.", "tags": [ "licensing" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion bearer token." } }, "/api/user/verify": { "post": { "summary": "Verify the authenticated user account against the licensing store.", "tags": [ "licensing" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } }, "security": [ { "MaataraAssertion": [] } ], "description": "Requires a MaataraAssertion carrying a single-use nonce. Each assertion may be used exactly once — mint a fresh one per request." } }, "/invite-request": { "post": { "summary": "Submit an invite request.", "tags": [ "licensing" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Bad request" }, "500": { "description": "Internal server error" } } } } } }