API Contract Surface

Endpoints

POST /forecast/mint Mint a probabilistic forecast. Idempotency-Key header required.

GET /forecast/{fc_id} Retrieve a previously-minted forecast by canonical FC-ID.

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

POST /billing/charge Settle a per-call charge against an authorized AP2 mandate via Stripe meter event.

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

Authentication

Path A — Direct API (autonomous agents)

Autonomous agents authenticate by presenting an AP2 (Google Agent Payments Protocol) mandate at the Hermes contract-middleware authorization gate. The mandate must include both an Intent Mandate and a Cart Mandate Verifiable Credential signed by the principal. Mandate signature verification budget is approximately two to five seconds at the blocking gate.

POST /forecast/mint HTTP/1.1
Host: phronesis-jrstinehour.replit.app
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"
}

Path B — Agentic commerce (agents acting for humans)

Agents acting on behalf of human principals via the Stripe Agentic Commerce Suite (ACS) checkout flow present a Stripe Shared Payment Token (SPT) bound to an AP2 Cart Mandate at issuance time. The SPT replaces the AP2-direct authorization for the per-call settlement.

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.

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://sustainablefinancepartner.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). Cost-attestation per call is published at /pricing.json and includes the inference cost component plus the markup multiplier.

MCP server

The MCP server exposes tools that are one-to-one with REST endpoints. Tool names map to endpoint paths; tool parameters map to request bodies. Tool outputs match REST response shapes exactly. Use either surface; neither is privileged.

// MCP tool list (representative)
{
  "tools": [
    { "name": "forecast_mint", "description": "Mint a probabilistic forecast" },
    { "name": "forecast_get",  "description": "Retrieve forecast by FC-ID" },
    { "name": "scorecard_get", "description": "Read calibration scorecard" },
    { "name": "billing_charge","description": "Settle per-call meter event" }
  ]
}

Verticals and archetypes

Twelve verticals; all twelve LIVE on production per 12-VERTICAL-COMPLETE substrate milestone; archetype taxonomy is per-vertical. See the home page vertical lineup for live status. 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). Archetype references documented in vertical-specific scope addenda; 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 at /spec#changelog.

Support

Issues, integration questions, contract clarifications: contact via the Sustainable Finance Partners home page or write to the support email. Bug reports against the contract surface are triaged at the Iris ring (Phronesis customer relations substrate); critical contract violations are escalated immediately per Sacred Invariant #9 boundary-as-only-publish.