API spec.

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 ledger; every value visible on the public scorecard.

Endpoints

Authentication

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

1. Authenticate the caller via JWT / workload credential — issuer, audience, expiry, and tenant validated at the gate.
2. Verify an AP2 mandate as delegated-authority evidence and bind it to that caller, principal, resource, budget, and action class.
3. Authorize in policy code — the model never grants or widens authority.
4. Store hashes and references, never reusable bearer material.
5. 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-request settlement is in build. When it is live, agents will pay per request through Stripe — cards via Shared Payment Tokens, or USDC over x402 or Stripe's Machine Payments Protocol. Until then, per-request purchases are not available.

Path C — Direct human SaaS (Discovery / Record / Practice subscribers)

Human subscribers authenticate with a bearer token issued at OAuth consent (PKCE) or by the post-checkout signup claim. Subscription tier (Discovery Free / Record $49 / Practice $499) determines included usage allowances and overage rates. Compute depth tiers (Standard / Deep / Strategic / Strategic Sync) handle per-inquiry depth-classification. See /pricing.

Idempotency

Every mutating endpoint requires the Idempotency-Key header. Keys are persisted to the 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 (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 ledger (in build). 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 applied verticals are catalogued on one substrate; the calibration substance concentrates where decisions resolve first — today, grid-compute. The breadth is one motion accumulating a cross-archetype record, not twelve finished products. See the verticals page for archetype detail. 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 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. 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.