Live · v1

API Reference

Every procurement decision the Sentinel dashboard runs is available over HTTPS at api.wyrm.ai/v1. API keys are issued from the dashboard on the Pro tier.

Quickstart OpenAPI spec Swagger explorer

Authentication

API keys, scoped per organisation

Every request must carry an API key. Generate one from your dashboard at sentinel.wyrm.ai/settings → API Keys. Treat keys like passwords — they grant the same tier access as your account.

X-API-Key header (recommended)

curl https://api.wyrm.ai/v1/account \
  -H "X-API-Key: wyrm_sk_live_•••"

Use this for server-to-server calls. The dashboard shows the full key once at creation; store it securely.

Bearer JWT (dashboard sessions)

Authorization: Bearer <supabase-jwt>

The Sentinel dashboard uses your Supabase session JWT automatically. You only need API keys for external integrations.

Quickstart

Run your first decision in 60 seconds

Sentinel's flagship endpoint is /v1/jormungandr/decide — submit a procurement intent (source, ship, pay, benchmark) and Sentinel returns a ranked decision with cost stack, CO₂, sanctions, route, and confidence breakdown.

cURL

curl -X POST https://api.wyrm.ai/v1/jormungandr/decide \
  -H "X-API-Key: $WYRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "source",
    "product": {
      "query": "1,200 kg primary aluminium ingots",
      "destination_country": "GB"
    }
  }'

Python

import os, requests

resp = requests.post(
    "https://api.wyrm.ai/v1/jormungandr/decide",
    headers={"X-API-Key": os.environ["WYRM_API_KEY"]},
    json={
        "intent": "source",
        "product": {
            "query": "1,200 kg primary aluminium ingots",
            "destination_country": "GB",
        },
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["recommendation"])

TypeScript / Node

const resp = await fetch("https://api.wyrm.ai/v1/jormungandr/decide", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.WYRM_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    intent: "source",
    product: {
      query: "1,200 kg primary aluminium ingots",
      destination_country: "GB",
    },
  }),
});
const decision = await resp.json();

Endpoints

Catalogue by domain

Full schema for every endpoint is in the OpenAPI spec. Below is the high-level map of what's available.

Decision engine

Starter+

POST/v1/jormungandr/decide
Run a procurement decision (counts toward monthly quota).
POST/v1/jormungandr/disambiguate
Resolve a vague query before deciding.

Supply-Root pipeline

Starter+

POST/v1/supply-root/search
Origin shortlist + landed-cost estimates.
POST/v1/supply-root/route
Route risk + freight ETA.
POST/v1/supply-root/fx
FX impact + recommended hedge.
POST/v1/supply-root/compliance
Sanctions + UFLPA + CBAM screen.
POST/v1/supply-root/benchmark
Price-trend benchmark vs market index.
POST/v1/supply-root/otc
OTC quote + execute.

Account & keys

Free+

GET/v1/account
Profile + tier + active subscription.
GET/v1/account/api-keys
List active keys.
POST/v1/account/api-keys
Create key (Pro+ only).
DELETE/v1/account/api-keys/{id}
Revoke a key.

Sanctions & threat

Starter+

POST/v1/sanctions/screen
Multi-list sanctions screen for an entity.
POST/v1/threat-intel/search
OSINT threat-intel lookup.
GET/v1/cyber/cve/{cve_id}
CVE detail + EPSS + KEV status.

Markets & feeds

Free+

GET/v1/markets/fx
Live FX rates.
GET/v1/markets/commodities
Commodity index points.
GET/v1/news
Filtered procurement news stream.
GET/v1/feeds/health
Status of all upstream data feeds.

RFQs & shipping

Pro+

POST/v1/rfqs
Issue an RFQ to a supplier (auto-negotiation enabled).
GET/v1/rfqs/{id}
RFQ status + counter-offer thread.
POST/v1/shipping/track
Track a Freightos / WebCargo booking.

Limits

Per-minute rate limits + monthly decision quotas

Two layers protect both your account and the platform: per-minute rate limits stop runaway clients, monthly decision quotas match what your subscription tier promises.

Tier	Rate limit	Monthly decisions	Headers returned
Free (no key)	20 / min	—	429 on overflow
Starter (£199/mo)	120 / min	5,000	X-Decision-Quota-*
Pro (£499/mo)	300 / min	25,000	X-Decision-Quota-*
Enterprise	600 / min	Unlimited	X-Decision-Quota-* (limit blank)

Decision quotas reset on the 1st of each month at 00:00 UTC. Light endpoints — markets, news, feed health, account — are rate-limited only and don't burn the monthly bucket. Every decision response carries X-Decision-Quota-Used, X-Decision-Quota-Limit, X-Decision-Quota-Remaining, and X-Decision-Quota-Reset (seconds until the next reset).

Error model

Predictable HTTP codes, structured error bodies

Every error returns a JSON body with a stable code, a human-readable message, and any context you need to recover.

{
  "detail": {
    "code": "quota_exceeded",
    "message": "Monthly decision quota of 5,000 exceeded for the Starter tier. Quota resets on the 1st of next month (UTC). Upgrade at https://wyrm.ai/pricing or wait for the reset.",
    "tier": "starter",
    "monthly_limit": 5000,
    "year_month": "2026-04"
  }
}

401

invalid_credentials

Missing / invalid API key or expired JWT.

403

tier_required

Your tier is below the endpoint's minimum.

429

rate_limit_exceeded

Per-minute rate limit hit. Backoff with Retry-After.

429

quota_exceeded

Monthly decision quota exhausted. Retry-After = seconds until 1st of next month.

400

validation_error

Pydantic schema rejection. Body lists offending fields.

502

upstream_unavailable

A required upstream feed (sanctions, FX, freight) is down. Safe to retry.

Integrations

MCP server + webhooks

Beyond REST, Sentinel ships a Model Context Protocol server for direct use from Claude Desktop, Cursor, and other MCP clients. Webhook delivery is on the Enterprise roadmap.

MCP server (Pro+)

Run the Sentinel MCP server locally and bind your API key — your AI assistant gets the same tools the dashboard uses, with native function-calling.

# Claude Desktop config
{
  "mcpServers": {
    "wyrm-sentinel": {
      "command": "python",
      "args": ["-m", "app.mcp_server"],
      "env": { "WYRM_API_KEY": "wyrm_sk_live_•••" }
    }
  }
}

Webhooks (Enterprise — Q3 2026)

Subscribe to RFQ updates, supplier-acceptance events, sanctions watchlist hits, and decision audit-log entries over signed HTTPS callbacks. Ships with Enterprise tier.

Talk to us about early access: contact sales.

Versioning

Stable v1 surface, no surprise breakage

The /v1 prefix is contractually stable. Breaking changes ship as /v2 with at least 90 days of overlap. Additive changes (new endpoints, new optional fields) ship at any time without a version bump.

Deprecation schedule and migration notes are posted to the changelog. New customers should treat the OpenAPI spec at api.wyrm.ai/openapi.json as the source of truth — it's auto-generated from the running service and always reflects what's live.

Get an API key in 60 seconds

Pro is free for 7 days or until your first accepted RFQ — whichever comes first. Sign up, log in, generate a key, paste it into X-API-Key, and you're live.

Start free trial Talk to engineering