API reference

Every public endpoint on api.apihub.io and proxy.apihub.io. Single page so you can grep.

Authentication

All authenticated endpoints expect an APIHub API key in the Authorization header. Both formats accepted:

Auth header

Authorization: Bearer ahk_your_key
Authorization: ahk_your_key

Keys begin with ahk_. See API keys for how to get one.

Base URLs

API: https://api.apihub.io (read-only, agent management, credit purchase, search)
MCP: https://mcp.apihub.io/mcp (Model Context Protocol JSON-RPC endpoint)
Proxy: https://proxy.apihub.io (paid API calls)

Response envelope

All API endpoints return a consistent envelope:

Success

{
  "ok": true,
  "data": { ... },
  "meta": { "request_id": "uuid", "latency_ms": 12 }
}

Error

{
  "ok": false,
  "error": { "code": "INSUFFICIENT_CREDITS", "message": "..." },
  "meta": { "request_id": "uuid" }
}

Common error codes

UNAUTHORIZED - 401, missing or invalid API key
RATE_LIMITED - 429, exceeded the per-minute or per-hour cap (Retry-After header set)
INVALID_INPUT - 400, request body or query parameter failed validation
INSUFFICIENT_CREDITS - 402, no credits and no PAYMENT-SIGNATURE header
SERVICE_NOT_FOUND - 404, the slug doesn't exist or is paused
DOMAIN_NOT_VERIFIED - 403, content gateway domain hasn't been verified
NO_CONTENT_RULE - 404, no pricing rule matches the requested URL path
UPSTREAM_ERROR - 502, the upstream API failed or timed out
CONFIG_ERROR - 500, server-side configuration issue

Rate limits

Proxy calls: 100/min free tier, 1000/min for accounts with credit balance (per-profile)
Credit purchase: 20/min per API key
Agent registration (public): 5/hour per IP
Magic-link emails: 3/hour per email

Registration

GET/v1/register/challenge

Returns the message your agent must sign to prove wallet ownership during autonomous registration.

Response200 OK

{
  "ok": true,
  "data": {
    "message": "I am registering for APIHub.io",
    "instructions": "Sign this message with your EVM wallet and POST it back to /v1/register with your wallet_address and signature."
  }
}

POST/v1/register

Verifies the signed challenge and creates an agent account. One account per wallet address. Subject to per-IP rate limit (5/hr).

Parameters

wallet_addressstringrequired

EVM address (0x prefix, 40 hex chars)

signaturestringrequired

Signed challenge message

labelstring

Optional label

Response200 OK

{
  "ok": true,
  "data": {
    "agent_id": "uuid",
    "api_key": "ahk_xxxxxxxxxxxxxx...",
    "api_key_prefix": "ahk_xxxxxxxx",
    "wallet_address": "0x...",
    "note": "Store this API key securely."
  }
}

Discovery

GET/v1/services

List active onboarded API services. Public, no auth required.

Parameters

limitnumber

Default 50, max 100

Response200 OK

{
  "ok": true,
  "data": {
    "services": [
      { "id": "...", "slug": "...", "name": "...", "description": "...", ... }
    ]
  }
}

GET/v1/services/:slug

Get full details for a service including endpoints and pricing. Public, no auth required.

Response200 OK

{
  "ok": true,
  "data": {
    "service": { ... },
    "endpoints": [
      { "method": "GET", "path": "/latest/USD", "price_per_request": 500, ... }
    ]
  }
}

POST/v1/search

Search services by query, category, price, or type.

Parameters

querystringrequired

Free-text search

categorystring

Filter by category

max_price_microdollarsnumber

Upper bound on price

typestring

'api' or 'content'

Request

curl -X POST https://api.apihub.io/v1/search \
  -H "Authorization: Bearer ahk_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "weather", "max_price_microdollars": 10000 }'

Response200 OK

{
  "ok": true,
  "data": { "results": [ ... ] }
}

GET/v1/external

List external x402 marketplace listings (services indexed from on-chain activity, not onboarded to APIHub). Public.

Response200 OK

{ "ok": true, "data": { "listings": [ ... ] } }

Wallet & credits

GET/v1/wallet/balance

Returns the agent's spending stats and current rate-limit status.

Response200 OK

{
  "ok": true,
  "data": {
    "agent_id": "uuid",
    "credit_balance_microdollars": 9870000,
    "total_spent_microdollars": 130000,
    "total_requests": 25,
    "rate_limit": { "limit_per_minute": 1000, "current_minute_count": 4 }
  }
}

GET/v1/credits/balance

Returns just the credit balance. Lightweight.

Response200 OK

{
  "ok": true,
  "data": {
    "credit_balance_microdollars": 9870000,
    "credit_balance_display": "$9.8700"
  }
}

GET/v1/credits/history

Recent credit transactions: purchases, refunds, external x402 debits. Newest first.

Parameters

limitnumber

Default 20, max 100

Response200 OK

{
  "ok": true,
  "data": {
    "transactions": [
      { "id": "...", "type": "purchase|refund|debit", "amount_microdollars": 10000000, "balance_after": ..., "created_at": "..." }
    ]
  }
}

POST/v1/credits/purchase

Purchase credits via x402. First call returns 402 challenge. Sign EIP-3009 transferWithAuthorization, re-post with PAYMENT-SIGNATURE header. Rate limited 20/min per key.

Parameters

amount_microdollarsnumberrequired

Min 5,000,000 ($5)

Response200 OK

{
  "ok": true,
  "data": {
    "balance_microdollars": 10000000,
    "credited_microdollars": 10000000,
    "tx_hash": "0xabc..."
  }
}

Proxy (paid calls)

ANY/:slug/:endpoint_path

Forwards request to an onboarded service's upstream. Method, body, query string preserved. Charges per-endpoint price from credits (or returns 402 with x402 challenge if no credits + no PAYMENT-SIGNATURE).

Response200 OK

/* Upstream response, with these added headers:
   x-apihub-payment-protocol: credit | free_tier | x402 | provider_test
   x-apihub-charged: <microdollars> | false
   x-apihub-credit-balance-remaining: <microdollars>
   x-apihub-latency-ms: <ms>
   x-apihub-receipt-hash: <sha256>
*/

POST/external

Call any x402-protected URL via the proxy. APIHub pays the upstream provider on-chain and debits your credits (price + markup). No wallet required on your side.

Parameters

urlstringrequired

Full URL to call

methodstring

Default POST

bodyobject | string

Forwarded verbatim

headersobject

Authorization and X-PAYMENT are stripped

Response200 OK

{
  "ok": true,
  "status": 200,
  "body": { /* upstream JSON */ },
  "credits_spent_microdollars": 5500,
  "credits_remaining_microdollars": 994500
}

GET/:slug/fetch?url=:target

Content gateway. Fetches the URL via headless browser, charges the matching content rule's price, returns clean structured text.

Parameters

slugstringrequired

Content service slug (in path)

urlstringrequired

Full URL to fetch (query parameter)

Response200 OK

{
  "ok": true,
  "data": {
    "source_url": "...",
    "title": "...",
    "text": "...",
    "headings": [ ... ],
    "word_count": 1200,
    "truncated": false
  }
}

MCP

GET/mcp

Returns server info. Useful for registries and sanity checks. No auth required.

Response200 OK

{
  "name": "apihub",
  "displayName": "APIHub",
  "publisher": "APIHub",
  "transport": "streamable-http",
  "protocolVersion": "2025-03-26",
  "tools": [ "apihub_search", "apihub_call", ... ]
}

POST/mcp

JSON-RPC handler. Methods: initialize, notifications/initialized, tools/list (no auth), tools/call (auth required).

Response200 OK

/* JSON-RPC 2.0 response per the MCP spec.
   See https://modelcontextprotocol.io for protocol details.
   Tool list and arg shapes documented at /docs/agents/mcp. */

Health & well-known

GET/v1/health

Liveness check. Always returns 200 if the worker is up.

Response200 OK

{ "ok": true, "data": { "status": "healthy" } }

Discovery files

/llms.txt - high-level platform description for LLM-aware crawlers
/.well-known/agent.json - A2A agent card
/.well-known/mcp.json - MCP server card with tool list