API Contract Surface

Quick start

Three minutes from zero to your first minted forecast (assuming you've obtained a JWT from your principal):

curl -X POST https://api.phronesisintel.com/v1/decision/forecast \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PHRONESIS_JWT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @request.json   # structured-forecast body per the request schema in the canonical OpenAPI spec

The response includes the canonical FC-ID, the canonical-quantile estimates, the issue timestamp, and the cost-attestation in dollars-and-cents. Every value persisted to the Mnemosyne ledger; every value visible on the public scorecard.

Endpoints

POST /v1/decision/forecast Emit a canonical Decision-API forecast output. Idempotency-Key header required. JWT-gated.

GET /forecast/{fc_id}/audit Public per-forecast audit surface for a minted forecast (first-party records).

GET /scorecard.json Public calibration scorecard. All forecasts, all verticals, all-time.

POST /billing/charge Settle a per-call charge for the authenticated caller via Stripe meter event. AP2 mandate evidence: forward-state.

GET /health Service health probe (auth-gated). 200 OK with substrate version, 401 if unauthenticated.

Authentication

The authority model (normative — the one flow on every surface)

Authenticate the caller via JWT / workload credential — issuer, audience, expiry, and tenant validated at the gate.
Verify an AP2 mandate as delegated-authority evidence and bind it to that caller, principal, resource, budget, and action class.
Authorize in policy code — the model never grants or widens authority.
Store hashes and references, never reusable bearer material.
The receipt states what was authenticated, what authority was presented, which policy version ran, and what boundary resulted.

Claim state: step 1 is live at the gate today. Mandate verification-and-binding at the gate (steps 2 onward for AP2 material) is FORWARD-STATE — mandate material is consumed as evidence input today, not accepted as authentication. The example below documents the forward-state wire shape and is not yet accepted:

POST /v1/decision/forecast HTTP/1.1  (FORWARD-STATE example — not accepted today)
Host: api.phronesisintel.com
Content-Type: application/json
Idempotency-Key: 01HXYZA1B2C3D4E5F6G7H8J9K0
Authorization: AP2-Mandate <base64-encoded-VC-bundle>

{
  "vertical": "V1",
  "archetype": "E1",
  "subject": "ERCOT_summer_capacity_factor_2027",
  "horizon": "2027-Q3"
}

Agentic commerce (agents acting for humans) — FORWARD-STATE

The Stripe Agentic Commerce Suite flow (Shared Payment Token bound to an AP2 Cart Mandate at issuance) is a documented forward-state; per-call settlement today runs against the authenticated caller's tenant via Stripe meter events.

Path C — Direct human SaaS (Discovery / Inquiry / Practice / Practice+ / Enterprise subscribers)

Human subscribers authenticate via Bearer JWT issued at login. Subscription tier per Pricing_Strategy v1.2 canonical (Discovery Free / Inquiry $49 / Practice $499 / Practice+ $2,499 / Enterprise negotiated) determines included usage allowances and overage rates. Compute depth tiers (Standard / Deep / Strategic / Strategic Sync) handle per-inquiry depth-classification per Themis #117.6. See /pricing.

Idempotency

Every mutating endpoint requires the Idempotency-Key header. Keys are persisted to the Mnemosyne idempotency archive for a minimum of seventy-two hours. Repeat requests with the same key return the original response without side effects, regardless of whether the original was successful.

Recommended key shape: ULID or UUIDv7. Maximum length: 256 characters. Keys must be unique per principal-tenant; collisions across tenants do not interfere due to per-tenant isolation at the boundary publish layer.

Error semantics

Errors are structured with stable machine-recoverable codes. Sixteen-code enumeration covers the canonical failure modes:

{
  "error": {
    "code": "MANDATE_INVALID_SIGNATURE",
    "message": "AP2 mandate signature verification failed",
    "category": "auth",
    "retryable": false,
    "documentation_url": "https://phronesisintel.com/spec#errors",
    "request_id": "req_01HXYZA1B2C3D4E5F6G7H8J9K0"
  }
}

Code categories: auth (mandate or JWT failure) · validation (request shape error) · rate_limit (per-tenant or per-mandate limit hit) · circuit (downstream circuit-breaker tripped) · substrate (canonical-correctness violation) · billing (Plutus charge failure) · not_found · internal. Retryable errors include rate_limit and circuit; all others are non-retryable.

Meter events and pricing

Forecast minting fires a Stripe meter event at the moment of canonical persistence to the Mnemosyne ledger. Meter event amounts are reported with sub-cent precision (Decimal lift, no float). The published per-call price and the inference cost-attestation component are both in /pricing.json.

MCP server

The MCP server exposes task-verb tools with semantic parity to the REST surface — transport-appropriate projection, not endpoint mirroring. Tool outputs carry the same canonical records the REST responses carry.

// MCP tools (from tools/list)
{
  "tools": [
    { "name": "forecast_submit",        "description": "Submit a structured forecast for canonical persistence" },
    { "name": "bench_query",            "description": "Query the Decision Quality Bench" },
    { "name": "score_action_boundary",  "description": "Assess an action against the boundary matrix" },
    { "name": "health_check",           "description": "Service health" }
  ]
}
// plus operational/governance tools (memory_read, memory_write,
// killswitch_reset) — also visible in tools/list.

Verticals and archetypes

Twelve verticals; all twelve LIVE on production per 12-VERTICAL-COMPLETE substrate milestone; archetype taxonomy is per-vertical. See the verticals page for archetype detail. Themis canonical-rule catalog v1.10 carries 144 rules across 14 clusters (12 vertical clusters + 2 cross-cutting clusters #117 Agent-Surface-Discipline + #118 Data-Handling-Discipline). Canonical taxonomy is reflected in the OpenAPI spec.

Discovery surfaces

For agent crawlers: agents.txt · agentic-commerce.json · openapi.json · pricing.json · robots.txt

Versioning

The Hermes contract surface uses semantic versioning at the contract layer. Breaking changes go to a new major version with a six-month deprecation window for the prior major. Non-breaking additions (new endpoints, new optional fields) are added in minor versions and announced via the changelog.

SLA and limits

Production runtime is dedicated 24/7 (Reserved VM). Per-tenant rate limits and per-mandate burst limits documented at /spec#rate-limits (in development). Service credits available for 24+ hour continuous outage per the Refund Policy.

Support

Issues, integration questions, contract clarifications: write to the support email published on the Sustainable Finance Partners Contact page. Bug reports against the contract surface are triaged at the customer-relations substrate; critical contract violations — anything that bypasses or undermines the single boundary publish gate that every endpoint passes through — are escalated immediately.