Dark Matter Docs

Endpoint reference for the energy vertical. Slots, demand, aggregation plans, pools, tranches, waterfalls, contracts, dispatch, jurisdictions, stage gates.

Authentication

All /v1/energy/* endpoints require Authorization: Bearer $DMTR_KEY headers per the standard API auth model.

Slots

Method	Path	Purpose
`GET`	`/v1/energy/slots`	List slot inventory
`POST`	`/v1/energy/slots`	Register a new slot
`GET`	`/v1/energy/slots/{slot_id}`	Fetch a slot
`PATCH`	`/v1/energy/slots/{slot_id}`	Update fields
`POST`	`/v1/energy/slots/{slot_id}/decompose`	Split into child blocks
`POST`	`/v1/energy/slots/{slot_id}/advance`	Advance the stage gate

Decompose request body

{
  "blocks": [
    { "slot_id": "slot-X-block-1", "capacity_mw": 50 },
    { "slot_id": "slot-X-block-2", "capacity_mw": 50 }
  ]
}

The total child MW must not exceed the parent's capacity_mw. Each child inherits the parent's site_class, jurisdiction, and interconnect topology by default; override fields via subsequent PATCH.

Advance request body

{ "gate": "permits", "status": "complete" }

Returns 409 if the transition is disallowed (prerequisite gates incomplete or regression attempted).

Demand

Method	Path	Purpose
`POST`	`/v1/energy/demand`	Submit a DemandSpec
`POST`	`/v1/energy/demand/{demand_id}/match`	Match against slot inventory
`POST`	`/v1/energy/demand/{demand_id}/allocation-plan`	Produce a non-binding multi-slot AllocationPlan

Match request body (optional)

{
  "tenantOfacScreenedAt": "2026-04-30",
  "estimatedProjectValueUsd": 800000000
}

Both are passed through to the rights engine for the OFAC and RIGI checks respectively.

Aggregation and pools

Method	Path	Purpose
`POST`	`/v1/energy/pools`	Create a CapacityPool
`GET`	`/v1/energy/pools/{pool_id}`	Fetch pool by id
`PATCH`	`/v1/energy/pools/{pool_id}`	Update pool fields
`POST`	`/v1/energy/pools/{pool_id}/sign`	Execute pool and issue component encumbrances
`POST`	`/v1/energy/pools/{pool_id}/dissolve`	Dissolve pool after precondition checks
`POST`	`/v1/energy/pools/{pool_id}/tranches`	Add pool tranche
`POST`	`/v1/energy/pools/{pool_id}/waterfall`	Execute deterministic period waterfall

Contracts

Method	Path	Purpose
`POST`	`/v1/energy/contracts`	Create a CapacityContract
`GET`	`/v1/energy/contracts/{contract_id}`	Fetch a contract
`POST`	`/v1/energy/contracts/{contract_id}/dispatch-notice`	Issue a dispatch notice
`GET`	`/v1/energy/contracts/{contract_id}/dispatch-notices`	List dispatch history

Reference endpoints

Method	Path	Purpose
`GET`	`/v1/energy/jurisdictions`	List distinct jurisdictions across slot inventory
`GET`	`/v1/energy/stage-gates`	Reference: stage-gate sequence + prerequisites

OpenAPI source

The full machine-readable specification lives at packages/openapi/openapi.yaml with schema components:

ComputeSlot → packages/openapi/schemas/compute-slot.json
CapacityContract → packages/openapi/schemas/capacity-contract.json
DemandSpec → packages/openapi/schemas/demand-spec.json
StageGateState → packages/openapi/schemas/stage-gate-state.json
AllocationPlan → packages/openapi/schemas/allocation-plan.json
CapacityPool → packages/openapi/schemas/capacity-pool.json
PoolTranche → packages/openapi/schemas/pool-tranche.json

A pnpm test:openapi-sync check enforces enum parity between the OpenAPI JSON Schemas and the Zod source-of-truth in @dmtr/core and @dmtr/energy so the spec cannot drift silently.

API reference — /v1/energy/*