API reference

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 · SDKs · 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.

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.

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": [ ... ]
}

POST /v1/portfolio API key

Submit or replace your portfolio for personal metrics. Body: {"positions": [{"symbol": "BTC", "qty": 0.5}, ...]} (1-100 positions, positive qty). Stored under an opaque hash of your API key and forwarded positions-only to the engine. See the Personal metrics guide.

GET /v1/metrics/personal API key

Your personal metric values, computed hourly from your latest submitted portfolio. Visible only to the submitting key.

GET /v1/catalog API key

The metric catalog: id, name, category, access (public/personal), classification, computation methods, freshness, and whether your plan can access each metric.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.madjik.io/v1/catalog?include_stale=true"

GET /v1/data public

How much data the engine holds and when each part was last refreshed (no key). sources: raw input datasets with rows, size, data range, last refresh and status; metrics: published values per metric (total, live, backfilled), history range and last refresh. Rebuilt hourly. Counts only, never data values. Shown at madjik.io/data.

GET /v1/subscription API key

Your current plan, its limits (speed, daily calls, portfolio size, history, export, webhooks, support) and the list of metric ids your key can access (all of them).

Webhooks

Register HTTPS endpoints (Pro and Enterprise) and receive metric.updated events instead of polling. Only public metric events are delivered, as a JSON POST.

Headers

Reliability

• Answer 2xx quickly and process afterwards. A non-2xx answer, timeout (5 s) or network error is retried up to 3 times (immediately, +2 s, +6 s). Other 4xx answers are not retried.
• After 20 consecutive failed events the webhook is disabled (disabled_reason in GET /v1/webhooks). Fix your endpoint, then call POST /v1/webhooks/{id}/test: a 2xx answer re-enables it.
• Endpoints must be public https hosts. Private, loopback and link-local addresses are refused at registration and at every delivery. Redirects are not followed.
• There is no replay of missed events: after an outage, read the gap from GET /v1/metrics/{id}/timeseries.

# verify (Python, no SDK)
import hmac, hashlib, time
ts = headers["X-Madjik-Timestamp"]
ok = abs(time.time() - int(ts)) < 300 and hmac.compare_digest(
    headers["X-Madjik-Signature-V2"],
    "sha256=" + hmac.new(SECRET.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest())

POST /v1/webhooks API key

Register a webhook (Pro and Enterprise; 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 with their health (active, consecutive_failures, last_status, disabled_reason); secrets are never returned again.

POST /v1/webhooks/{webhook_id}/test API key

Send one signed sample event to the webhook now (event id starts with test_). A 2xx answer re-enables a webhook that was disabled after repeated failures and resets its failure count.

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.