Quickstart

1 · Get a key and make your first call

Create a key in the dashboard at /app/connect. Keys look like ahel_… and are shown once at creation — store the full value securely. Send it as a bearer token (or an X-API-Key header) on every request. New accounts start with free credits, so this works out of the box.

curl https://api.ahel.ai/v1/search/email \
  -H "Authorization: Bearer ahel_…" \
  -H "Content-Type: application/json" \
  -d '{ "query": "satoshi@example.com" }'

Search returns a { meta, payload: { findings: [] } } envelope. Each finding is one source’s record, carrying its source, a confidence (0–1), a match_quality, an optional evidence url, and its data.

{
  "meta": { "count": 3, "duration_ms": 1840 },
  "payload": {
    "findings": [
      {
        "platform": "companies register",
        "source": "ee business register",
        "confidence": 0.97,
        "match_quality": "exact",
        "url": "https://ariregister.rik.ee/…",
        "anchors": { "email": "satoshi@example.com" },
        "data": { "name": "…", "reg_code": "…" }
      }
    ]
  }
}

Three ways in

{
  "mcpServers": {
    "ahel": { "url": "https://mcp.ahel.ai" }
  }
}

import { createClient } from "@ahel-technologies/arkenstone-sdk";

const ahel = createClient({ apiKey: process.env.AHEL_API_KEY }); // ahel_…

const { payload } = await ahel.search("company", "Wise", { country: "GB" });

2 · Endpoint reference

Every path below is relative to https://api.ahel.ai/v1 and authenticated by your ahel_ key. POST bodies are JSON.

resolve, verify, verify/company and graph/expand return their own purpose-built envelope rather than the findings shape. A verify response, for example:

{
  "claim": "The James Webb Space Telescope launched in December 2021",
  "verdict": "supported",
  "agreement": 1.0,
  "answer": "Yes, JWST launched on December 25, 2021.",
  "sources_checked": 9,
  "receipts": [
    { "provider": "live web",  "stance": "supports", "confidence": 0.92,
      "url": "https://…" },
    { "provider": "wikipedia", "stance": "supports", "confidence": 0.85,
      "url": "https://en.wikipedia.org/wiki/James_Webb_Space_Telescope" }
  ]
}

3 · Authentication

Every REST call needs your ahel_ key, sent either as a bearer token or an X-API-Key header. The full secret is shown once at creation and stored only as a hash — if you lose it, mint a new one. Revoking a key takes effect immediately.

-H "Authorization: Bearer ahel_…"
# or
-H "X-API-Key: ahel_…"

• 401 invalid_api_key — the key is missing, malformed, revoked, or unknown (or the account is suspended).
• 402 insufficient_credits — authenticated, but out of credits; the body carries your balance.
• 429 rate_limited — too many requests for your plan; respect the Retry-After header.

MCP clients skip all of this — they authorize through the OAuth handshake at https://mcp.ahel.ai instead of carrying a key.

4 · Credits and metering

Calls are metered in prepaid credits, debited up front and automatically refunded if the call fails (reserve- then-settle). A type fan-out or a cold resolve is 1 credit; a single source invoked through one of your own connected keys is free. Read-only metadata (/providers, /credits, /openapi) never costs anything.

• Search / resolve — 1 credit each.
• Provider invoke — 0 with your own connected key, 1 when Ahel hosts the source.
• Graph expand — 2 credits.
• Company check — 5 credits (registries + sanctions in one call).
• Claim verification — 10 credits (one claim across several live sources, verdict + receipts).

Check a balance any time, and top up or see the full breakdown on the pricing page.

{ "payload": { "balance": 187, "plan": "free" } }

5 · Errors

Errors come back as JSON with an error code (and often a detail or balance) at the matching HTTP status.

{ "error": "insufficient_credits", "balance": 0 }

{
  "error": "rate_limited",
  "detail": "Rate limit exceeded for the Free plan (30 requests/min). Retry in ~2s or upgrade your plan.",
  "limit": 30,
  "plan": "free",
  "retry_after_seconds": 2
}