Madjik API documentation

API reference

Every Madjik API endpoint: REST metrics, webhooks, MCP and A2A.

The complete surface of the Madjik Metrics API (v1). Generated from the API source; the API also serves interactive OpenAPI docs at api.madjik.io/docs.

Jump to: Metrics · Webhooks · MCP · A2A · Public endpoints

Basics

  • Base URL: https://api.madjik.io (REST endpoints under /v1/)
  • Auth: X-API-Key: YOUR_API_KEY header (or Authorization: Bearer YOUR_API_KEY) — see Authentication
  • All responses are JSON; timestamps are ISO 8601 UTC
  • Interactive OpenAPI docs: /docs and /redoc
  • Metric ids are case-insensitive in requests (m10004 works)

Metrics

GET /v1/metrics API key

Latest values. With no parameters, returns every metric your plan can access.

Query paramDescription
metric_idsComma-separated ids, e.g. M10004,M50014
categoriesComma-separated categories, e.g. tether,derivatives
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.madjik.io/v1/metrics?metric_ids=M10004,M50014"

Response shape: see Response format.

GET /v1/metrics/{id} API key

Latest value for one metric.

curl -H "X-API-Key: YOUR_API_KEY" "https://api.madjik.io/v1/metrics/M10004"

GET /v1/metrics/{id}/timeseries API key

Historical time series with per-point provenance and normalized values.

Query paramDescription
start, endISO timestamps; default is the last 7 days (clamped to your plan's history window)
interval1m, 5m, 15m, 1h (default), 4h, 1d, 1w
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.madjik.io/v1/metrics/M10004/timeseries?interval=1d&start=2026-08-01T00:00:00Z"

GET /v1/metrics/{id}/variants API key

The precomputed variant grid (change variants × time variants) for one metric. Pure pass-through from the Black Belt Labs engine.

{
  "success": true,
  "engine": "Black Belt Labs",
  "metric_id": "M10004",
  "variants": { "absval": { "now": ..., "past24h": ... }, "relchg": { ... } },
  "computed_at": "2026-09-10T08:00:00Z"
}

GET /v1/metrics/{id}/methods API key

Every computation method's current result side by side (progr = classical, learn = AI, quantum = quantum simulator).

{
  "success": true,
  "engine": "Black Belt Labs",
  "metric_id": "M50031",
  "methods_used": ["progr", "learn"],
  "computations": [ ... ]
}

GET /v1/catalog API key

The metric catalog: id, name, category, tier, classification, computation methods, freshness, and whether your plan can access each metric.

Query paramDescription
include_staletrue to include metrics currently outside their freshness SLA (e.g. dormant metrics whose data baselines are still maturing). Default false.
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.madjik.io/v1/catalog?include_stale=true"

GET /v1/subscription API key

Your current plan, rate limit, and the list of metric ids your key can access.

Webhooks

Register HTTPS endpoints and receive metric.updated events instead of polling. Deliveries are POSTs signed with HMAC-SHA256: the hex digest of the raw body, keyed with your webhook secret, is sent as X-Madjik-Signature: sha256=<digest>; the event name is in X-Madjik-Event. Verify the signature before trusting a delivery.

POST /v1/webhooks API key

Register a webhook (max 10 per key; URL must be https://). The signing secret is returned once — store it.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/madjik", "metric_ids": ["M10004", "M50014"]}' \
  "https://api.madjik.io/v1/webhooks"

{
  "success": true,
  "webhook_id": "aB3dEf...",
  "url": "https://example.com/hooks/madjik",
  "metric_ids": ["M10004", "M50014"],
  "secret": "whsec_...",
  "note": "Store the secret now; it is not retrievable later. Payloads are signed with HMAC-SHA256 in X-Madjik-Signature."
}

GET /v1/webhooks API key

List your registered webhooks (secrets are never returned again).

DELETE /v1/webhooks/{webhook_id} API key

Delete one of your webhooks.

MCP (Model Context Protocol)

Give AI assistants tool access to Madjik data. See the MCP integration guide.

GET /mcp/tools public

Tool definitions following the MCP specification: madjik_get_metrics, madjik_get_timeseries, madjik_market_summary, madjik_list_metrics.

POST /mcp/call API key

Execute one MCP tool.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "madjik_get_metrics", "arguments": {"metric_ids": ["M10004"]}}' \
  "https://api.madjik.io/mcp/call"

A2A (Agent-to-Agent)

Agent-facing interface following Google's A2A specification. See the A2A integration guide.

GET /a2a/agent.json public

The agent card: capability manifest (get_metrics, get_timeseries, analyze_market) and auth requirements.

POST /a2a/execute API key

Execute an A2A capability.

curl -X POST -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"capability": "get_metrics", "parameters": {"metric_ids": ["M10004"]}}' \
  "https://api.madjik.io/a2a/execute"

Public endpoints (no auth)

GET /health public

Service health check.

GET /v1/status public

Per-metric freshness status as JSON (no values). Human-readable version at /status.

GET /methodology public

Public methodology reference for every metric — classification, computation methods, cadence, and (for classic metrics) a methodology description. Proprietary metric methodology is a trade secret and is not published.

POST /v1/checkout public

Create a Stripe Checkout session for a plan (self-serve signup); your API key is provisioned automatically on completion.