Materra Compliance Programs API — OpenAPI 1.0.0

Scope: The published reference for Materra Compliance Programs API. 13 paths — the measured spec-vs-implementation coverage lives in the complete API inventory. Status: rendered 2026-11-09 from the OpenAPI source for Materra Compliance Programs API — regenerate with node scripts/render-platform-map-api-docs.mjs. See also: the OpenAPI spec index.

Servers

URL	Notes
http://127.0.0.1:3030	Local Agent BFF
https://api.sovereign.exchange	Production

Tag	Summary
Programs	Compliance program registry
Enrollment	Member enrollment voyages
Certificates	Authority / derived mint, revoke, unlock
Seal	Batch seal + provenance passport (optional BBS+)
Hub	Multi-org hub queue, casting, service directory
Playbooks	KV playbooks + voyage play/advance

Paths — 13 paths / 14 operations

Method	Path	Operation ID	Summary
GET	/v1/materra/compliance/programs	listCompliancePrograms	List compliance programs for org
POST	/v1/materra/compliance/programs	createComplianceProgram	Create / register compliance program claim
POST	/v1/materra/compliance/programs/{programId}/enroll	startEnrollment	Start enrollment voyage (affiliation + play)
POST	/v1/materra/compliance/programs/{programId}/enrollments/{enrollmentId}/advance	advanceEnrollment	Advance enrollment voyage (strict_hooks)
POST	/v1/materra/compliance/programs/{programId}/mint-authority	mintAuthorityCertificate	Mint chamber authority certificate claim
POST	/v1/materra/compliance/programs/{programId}/batches/{batchId}/seal	sealBatch	Seal batch; optional LIVE BBS+ when vault_id / require_bbs_plus
GET	/v1/materra/compliance/programs/{programId}/batches/{batchId}/passport	getBatchPassport	Provenance passport chain + seal presentations
GET	/v1/materra/compliance/hub-queue	listHubMultiOrgQueue	Hub multi-org enrollment queue
GET	/v1/materra/compliance/casting-candidates	listCastingCandidates	Org-first casting candidates (optional include=service)
GET	/v1/materra/compliance/service-directory	listServiceDirectory	Lab / packhouse / haulier affiliations
GET	/v1/materra/playbooks	listPlaybooks	List playbooks from NATS KV (+ T1 s369 merge)
PUT	/v1/materra/playbooks/{id}	putPlaybook	Compile Studio → journey-spec → KV; T1 dual-write s369
POST	/v1/materra/playbooks/{id}/play	playPlaybook	Start playbook voyage claim
POST	/v1/materra/playbooks/voyages/{claimId}/advance	advancePlaybookVoyage	Advance voyage with strict_hooks

Operations

GET /v1/materra/compliance/programs

Summary: List compliance programs for org

Tags: Programs Operation ID: listCompliancePrograms

Parameters:

Name	In	Required	Type	Notes
organization_id	query	yes	string

Responses:

Status	Meaning
200	Program list (honest empty when none)
400	Missing org
503	Infra invent_refuse

POST /v1/materra/compliance/programs

Summary: Create / register compliance program claim

Tags: Programs Operation ID: createComplianceProgram Responses:

Status	Meaning
200	Program created
422	Validation failed

POST /v1/materra/compliance/programs/{programId}/enroll

Summary: Start enrollment voyage (affiliation + play)

Tags: Enrollment Operation ID: startEnrollment

Parameters:

Name	In	Required	Type	Notes
programId	path	yes	string

Responses:

Status	Meaning
200	Enrollment started
422	Missing hub/journey or invalid fields
503	Voyage invent_refuse after affiliation

POST /v1/materra/compliance/programs/{programId}/enrollments/{enrollmentId}/advance

Summary: Advance enrollment voyage (strict_hooks)

Tags: Enrollment Operation ID: advanceEnrollment

Parameters:

Name	In	Required	Type	Notes
programId	path	yes	string
enrollmentId	path	yes	string

Responses:

Status	Meaning
200	Advanced
403	Missing drive_mandate / owner org
422	Gate invent_refuse (docs/payment/s350)

POST /v1/materra/compliance/programs/{programId}/mint-authority

Summary: Mint chamber authority certificate claim

Tags: Certificates Operation ID: mintAuthorityCertificate Responses:

Status	Meaning
200	Authority cert minted
404	Program missing — invent_refuse (no Soft cert)

POST /v1/materra/compliance/programs/{programId}/batches/{batchId}/seal

Summary: Seal batch; optional LIVE BBS+ when vault_id / require_bbs_plus

Tags: Seal Operation ID: sealBatch Responses:

Status	Meaning
200	Seal claim (+ optional BBS+ presentation bind)
422	Missing hash / revoked issuer / BBS+ require failed

GET /v1/materra/compliance/programs/{programId}/batches/{batchId}/passport

Summary: Provenance passport chain + seal presentations

Tags: Seal Operation ID: getBatchPassport Responses:

Status	Meaning
200	Passport (honest empty when unsealed)

GET /v1/materra/compliance/hub-queue

Summary: Hub multi-org enrollment queue

Tags: Hub Operation ID: listHubMultiOrgQueue Responses:

Status	Meaning
200	Queue rows

GET /v1/materra/compliance/casting-candidates

Summary: Org-first casting candidates (optional include=service)

Tags: Hub Operation ID: listCastingCandidates Responses:

Status	Meaning
200	Candidates

GET /v1/materra/compliance/service-directory

Summary: Lab / packhouse / haulier affiliations

Tags: Hub Operation ID: listServiceDirectory Responses:

Status	Meaning
200	Service directory

GET /v1/materra/playbooks

Summary: List playbooks from NATS KV (+ T1 s369 merge)

Tags: Playbooks Operation ID: listPlaybooks

Parameters:

Name	In	Required	Type	Notes
domain	query	no	string

Responses:

Status	Meaning
200	Playbooks with source tags
503	NATS unavailable

PUT /v1/materra/playbooks/{id}

Summary: Compile Studio → journey-spec → KV; T1 dual-write s369

Tags: Playbooks Operation ID: putPlaybook

Parameters:

Name	In	Required	Type	Notes
id	path	yes	string

Responses:

Status	Meaning
200	Stored (invent_refuse_live on catalog write)
422	Compile / domain lock
503	KV or s369 dual-write failed

POST /v1/materra/playbooks/{id}/play

Summary: Start playbook voyage claim

Tags: Playbooks Operation ID: playPlaybook Responses:

Status	Meaning
200	Voyage claim
422	Participants / unlock invent_refuse

POST /v1/materra/playbooks/voyages/{claimId}/advance

Summary: Advance voyage with strict_hooks

Tags: Playbooks Operation ID: advancePlaybookVoyage Responses:

Status	Meaning
200	Advanced
403	Owner org / drive_mandate
422	Gate invent_refuse

Full specification — verbatim source of truth

{
  "openapi": "3.0.3",
  "info": {
    "title": "Materra Compliance Programs API",
    "description": "Chamber / co-op compliance programs — enroll, mint, review, seal, passport, hub-queue, casting, playbooks. Soft≠LIVE invent_refuse on LIVE-gated ops. Agent BFF :3030.",
    "version": "1.0.0",
    "contact": {
      "name": "Sovereign OS Platform",
      "url": "https://sovereign.exchange"
    }
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3030",
      "description": "Local Agent BFF"
    },
    {
      "url": "https://api.sovereign.exchange",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Programs",
      "description": "Compliance program registry"
    },
    {
      "name": "Enrollment",
      "description": "Member enrollment voyages"
    },
    {
      "name": "Certificates",
      "description": "Authority / derived mint, revoke, unlock"
    },
    {
      "name": "Seal",
      "description": "Batch seal + provenance passport (optional BBS+)"
    },
    {
      "name": "Hub",
      "description": "Multi-org hub queue, casting, service directory"
    },
    {
      "name": "Playbooks",
      "description": "KV playbooks + voyage play/advance"
    }
  ],
  "paths": {
    "/v1/materra/compliance/programs": {
      "get": {
        "tags": [
          "Programs"
        ],
        "operationId": "listCompliancePrograms",
        "summary": "List compliance programs for org",
        "parameters": [
          {
            "name": "organization_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Program list (honest empty when none)"
          },
          "400": {
            "description": "Missing org"
          },
          "503": {
            "description": "Infra invent_refuse"
          }
        }
      },
      "post": {
        "tags": [
          "Programs"
        ],
        "operationId": "createComplianceProgram",
        "summary": "Create / register compliance program claim",
        "responses": {
          "200": {
            "description": "Program created"
          },
          "422": {
            "description": "Validation failed"
          }
        }
      }
    },
    "/v1/materra/compliance/programs/{programId}/enroll": {
      "post": {
        "tags": [
          "Enrollment"
        ],
        "operationId": "startEnrollment",
        "summary": "Start enrollment voyage (affiliation + play)",
        "parameters": [
          {
            "name": "programId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Enrollment started"
          },
          "422": {
            "description": "Missing hub/journey or invalid fields"
          },
          "503": {
            "description": "Voyage invent_refuse after affiliation"
          }
        }
      }
    },
    "/v1/materra/compliance/programs/{programId}/enrollments/{enrollmentId}/advance": {
      "post": {
        "tags": [
          "Enrollment"
        ],
        "operationId": "advanceEnrollment",
        "summary": "Advance enrollment voyage (strict_hooks)",
        "parameters": [
          {
            "name": "programId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "enrollmentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Advanced"
          },
          "403": {
            "description": "Missing drive_mandate / owner org"
          },
          "422": {
            "description": "Gate invent_refuse (docs/payment/s350)"
          }
        }
      }
    },
    "/v1/materra/compliance/programs/{programId}/mint-authority": {
      "post": {
        "tags": [
          "Certificates"
        ],
        "operationId": "mintAuthorityCertificate",
        "summary": "Mint chamber authority certificate claim",
        "responses": {
          "200": {
            "description": "Authority cert minted"
          },
          "404": {
            "description": "Program missing — invent_refuse (no Soft cert)"
          }
        }
      }
    },
    "/v1/materra/compliance/programs/{programId}/batches/{batchId}/seal": {
      "post": {
        "tags": [
          "Seal"
        ],
        "operationId": "sealBatch",
        "summary": "Seal batch; optional LIVE BBS+ when vault_id / require_bbs_plus",
        "responses": {
          "200": {
            "description": "Seal claim (+ optional BBS+ presentation bind)"
          },
          "422": {
            "description": "Missing hash / revoked issuer / BBS+ require failed"
          }
        }
      }
    },
    "/v1/materra/compliance/programs/{programId}/batches/{batchId}/passport": {
      "get": {
        "tags": [
          "Seal"
        ],
        "operationId": "getBatchPassport",
        "summary": "Provenance passport chain + seal presentations",
        "responses": {
          "200": {
            "description": "Passport (honest empty when unsealed)"
          }
        }
      }
    },
    "/v1/materra/compliance/hub-queue": {
      "get": {
        "tags": [
          "Hub"
        ],
        "operationId": "listHubMultiOrgQueue",
        "summary": "Hub multi-org enrollment queue",
        "responses": {
          "200": {
            "description": "Queue rows"
          }
        }
      }
    },
    "/v1/materra/compliance/casting-candidates": {
      "get": {
        "tags": [
          "Hub"
        ],
        "operationId": "listCastingCandidates",
        "summary": "Org-first casting candidates (optional include=service)",
        "responses": {
          "200": {
            "description": "Candidates"
          }
        }
      }
    },
    "/v1/materra/compliance/service-directory": {
      "get": {
        "tags": [
          "Hub"
        ],
        "operationId": "listServiceDirectory",
        "summary": "Lab / packhouse / haulier affiliations",
        "responses": {
          "200": {
            "description": "Service directory"
          }
        }
      }
    },
    "/v1/materra/playbooks": {
      "get": {
        "tags": [
          "Playbooks"
        ],
        "operationId": "listPlaybooks",
        "summary": "List playbooks from NATS KV (+ T1 s369 merge)",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "agriculture"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Playbooks with source tags"
          },
          "503": {
            "description": "NATS unavailable"
          }
        }
      }
    },
    "/v1/materra/playbooks/{id}": {
      "put": {
        "tags": [
          "Playbooks"
        ],
        "operationId": "putPlaybook",
        "summary": "Compile Studio → journey-spec → KV; T1 dual-write s369",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stored (invent_refuse_live on catalog write)"
          },
          "422": {
            "description": "Compile / domain lock"
          },
          "503": {
            "description": "KV or s369 dual-write failed"
          }
        }
      }
    },
    "/v1/materra/playbooks/{id}/play": {
      "post": {
        "tags": [
          "Playbooks"
        ],
        "operationId": "playPlaybook",
        "summary": "Start playbook voyage claim",
        "responses": {
          "200": {
            "description": "Voyage claim"
          },
          "422": {
            "description": "Participants / unlock invent_refuse"
          }
        }
      }
    },
    "/v1/materra/playbooks/voyages/{claimId}/advance": {
      "post": {
        "tags": [
          "Playbooks"
        ],
        "operationId": "advancePlaybookVoyage",
        "summary": "Advance voyage with strict_hooks",
        "responses": {
          "200": {
            "description": "Advanced"
          },
          "403": {
            "description": "Owner org / drive_mandate"
          },
          "422": {
            "description": "Gate invent_refuse"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "InventRefuseEnvelope": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "live": {
            "type": "boolean",
            "description": "Always false for Soft≠LIVE catalog ops"
          },
          "invent_refuse_live": {
            "type": "boolean"
          },
          "soft": {
            "type": "boolean",
            "description": "Always false — never Soft invent success"
          },
          "error": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        }
      }
    }
  }
}