docs / integration

API Surface

RESTful API through the gateway service at api.matterforma.com. Provides programmatic access to artifacts, runs, signals, policies, and decision outputs for integration teams and agent operators building against FORMA workflows.

Authentication

All API requests require a bearer token issued through the platform's authentication service. Tokens are scoped to organizational context and carry consequence tier permissions. A token with T1 permissions cannot submit T3 run requests.

curl -H "Authorization: Bearer mf_tok_01HQ..." \
     -H "Content-Type: application/json" \
     https://api.matterforma.com/v1/matter.artifact

Core object families

The API is organized around two namespaces -- matter.* for programmable artifacts and material.* for execution substrate -- plus supporting object families:

Matter: Artifacts

Create, retrieve, list, and version Molebytes. Upload compiled PEPs, attach simulation evidence, and query lineage chains. Matter endpoints manage programmable artifacts -- the designed intent.

GET /v1/matter.artifactPOST /v1/matter.artifactGET /v1/matter.artifact/:idPOST /v1/matter.compile

Material: Runs

Submit run requests, query run status, retrieve run history, and cancel pending or executing runs. Material endpoints manage execution on substrate -- the physical environment.

POST /v1/material.runGET /v1/material.run/:idGET /v1/material.run?artifact_id=...DELETE /v1/material.run/:id

Material: Simulation

Run Matter through the Material Twin. Submit simulation requests, retrieve results, and attach evidence to artifacts.

POST /v1/material.simulateGET /v1/material.simulate/:idGET /v1/material.facility

Signals

Retrieve execution outcomes with distributions, confidence, and economics. Filter by artifact, run, pool, or time range. Subscribe to real-time streams via SSE.

GET /v1/signals/:idGET /v1/signals?run_id=...GET /v1/signals/stream

Policies

Query active policies, evaluate policy against a Molebyte before submission, and retrieve policy decision history for audit.

GET /v1/policiesPOST /v1/policies/evaluateGET /v1/policies/decisions

Diffs & Judgments

Retrieve comparison results between signals and baselines, and decision outcomes from orchestration. Includes variance metrics, threshold evaluations, and routing decisions.

GET /v1/diffs/:idPOST /v1/diffs/compareGET /v1/judgments/:idPOST /v1/judgments/:id/approve

Example: submit a run

POST /v1/material.run
Content-Type: application/json
Authorization: Bearer mf_tok_01HQ...

{
  "artifact_id": "mb_01HQ3X7K9NFAA2RPWDG5B8VCMT",
  "artifact_version": "0.1.0",
  "pool_preference": "pool_molecular_01",
  "profile": "standard",
  "metadata": {
    "purpose": "baseline-establishment",
    "requested_by": "material-team"
  }
}

// Response: 201 Created
{
  "run_id": "run_01HQ4A8M2KPBB3SQXEG6C9WDNR",
  "state": "pending",
  "artifact_id": "mb_01HQ3X7K9NFAA2RPWDG5B8VCMT",
  "policy_evaluation": "in_progress",
  "created_at": "2026-02-20T14:34:50Z"
}

Response conventions

Pattern	Description
OX attribution	Every response includes decision attribution: what decided, why, and what policy context applied.
Pagination	List endpoints use cursor-based pagination with limit and after parameters.
Error structure	Errors return a structured body with code, message, details, and remediation suggestions.
Idempotency	Write operations accept an Idempotency-Key header for safe retries.
Rate limiting	Rate limits are scoped by token tier. Headers include remaining quota and reset time.