Operational workflows should be callable, reusable, and auditable.

The current DistributionOps API surface supports protected routes for assets, holders, positions, cash-flow events, distribution runs, notices, exceptions, payment CSV exports, and demo seeding.

Pilot API note

These endpoints are currently available for MVP validation and protected console workflows. Production API access should add API keys, organization scopes, usage metering, rate limits, webhooks, versioning, and formal access controls.

Endpoints

Current operational routes

Assets

Create and manage asset records.

GET /api/assetsPOST /api/assetsPATCH /api/assets/{assetId}DELETE /api/assets/{assetId}

Holder Registry

Create holders manually or import by CSV.

GET /api/assets/{assetId}/holdersPOST /api/assets/{assetId}/holdersPOST /api/assets/{assetId}/holders/import-csv

Positions

Store holder-level ownership units.

GET /api/assets/{assetId}/positionsPOST /api/assets/{assetId}/positions

Cash-Flow Events

Create cash-flow events used for distribution calculations.

POST /api/assets/{assetId}/cash-flow-events

Distribution Runs

Calculate, approve, export, and operate distribution cycles.

POST /api/distributions/calculatePOST /api/distribution-runs/{runId}/approveGET /api/distribution-runs/{runId}/payment-filePOST /api/distribution-runs/{runId}/payment-file/mark-exported

Notices and Exceptions

Generate notices, mark notices sent, and detect operational exceptions.

POST /api/distribution-runs/{runId}/notices/generatePOST /api/distribution-runs/{runId}/notices/mark-sentPOST /api/distribution-runs/{runId}/exceptions/detect

Example

Calculate a distribution run

The calculation endpoint snapshots current positions, calculates holder-level distribution lines, stores the run, and creates an audit event.

POST /api/distributions/calculate

{
  "asset_id": "asset_uuid",
  "cash_flow_event_id": "cash_flow_event_uuid"
}

Response:
{
  "distribution_run": {
    "status": "calculated",
    "total_units": 5000,
    "total_amount": 45000
  },
  "distribution_lines": [
    {
      "holder_id": "holder_uuid",
      "ownership_percentage": 50,
      "amount": 22500
    }
  ]
}

Roadmap

Future API hardening

API keys and usage metering

Organization and workspace scopes

Webhook events

Reconciliation API

Lifecycle event API

Audit export API

CSV file upload API

Sandbox mode