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 (T1-T4 subscribers)

Human subscribers authenticate via Bearer JWT issued at login. Subscription tier (T1 Starter, T2 Professional, T3 Team, T4 Enterprise) determines included usage allowances and overage rates.

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

Eight verticals; five live on production; archetype taxonomy is per-vertical. See the home page vertical lineup for live status. 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.