Skip to content
infraiDocs
Console

Discovery — the API that describes itself

infrai is the standard library for AI-built apps, and it describes itself: instead of reading docs, an agent can ask infrai what it can do. The discovery API returns the full capability set, each one's live availability, parameters, errors and current price — over plain HTTP, no SDK.

Capability index

GET /v1/discovery returns every capability with its live availability (is a vendor key healthy right now?). Public, no auth required.

bash
# Enumerate every capability + its live availability:
curl https://api.infrai.cc/v1/discovery

Each entry carries the capability id, HTTP method and path, a one-line summary and the current availability state — so a caller knows what to call and whether it will work before sending a request.

Response

json
{
  "version": "v1",
  "generated_at": "2026-06-03T12:00:00Z",
  "capabilities": [
    {
      "id": "email.send",
      "method": "POST",
      "path": "/v1/email/send",
      "available": true,
      "regions": ["western", "china"],
      "vendors": ["resend", "ses", "tencent"],
      "billing": {
        "is_billable": true,
        "free": false,
        "unit": "per_request",
        "price_usd": 0.0004,
        "currency": "USD",
        "new_account_trial_uses": 5000
      }
    }
    // … one object per capability.
    // NOTE: AI inference (chat/embeddings/images/audio/moderations/models) is
    // served OpenAI-API-compatible at /v1/chat/completions etc. — a parallel
    // standard surface, NOT listed in this discovery manifest.
  ]
}

Per-capability detail

docs.discovery.detail_intro

bash
# Full detail for one capability — params, errors, runnable
# examples and the live billing block (free/paid, unit, current price):
curl https://api.infrai.cc/v1/discovery/email.send

Parameters, error codes (with retryable flags), runnable curl / Python / JavaScript / TypeScript examples, and the live billing block — whether it is free or paid, the unit, and the current price. The same data powers the OpenAPI spec and this docs site.

Response

json
{
  "id": "email.send",
  "method": "POST",
  "path": "/v1/email/send",
  "available": true,
  "vendors": ["resend", "ses", "tencent"],
  "regions": ["western", "china"],
  "idempotent": true,
  "params": { "title": "EmailSendRequest", "required": ["to", "subject"], "...": "full JSON Schema" },
  "errors": ["RATE_LIMIT_VENDOR", "INSUFFICIENT_CREDIT", "VENDOR_DOWN", "..."],
  "examples": { "curl": "…", "python": "…", "javascript": "…", "typescript": "…" },
  "billing": {
    "is_billable": true,
    "free": false,
    "unit": "per_request",
    "price_usd": 0.0004,
    "currency": "USD",
    "approximate": false,
    "new_account_trial_uses": 5000
  }
}

Live pricing, not baked in

Pricing is served at runtime, never hard-coded into a client. The detail response includes a billing block per capability and, for a key with a balance, a hint of how many calls the current credit affords — so an agent can reason about cost before spending.

Machine descriptors (.well-known)

For tools and AI crawlers there are static, no-auth descriptors: the full OpenAPI 3.1 spec, the MCP server descriptor, and an llms.txt index. Point Cursor, Claude, an OpenAPI client or a search crawler at these.

bash
# Static machine descriptors (no auth) for tools + AI crawlers:
curl https://api.infrai.cc/.well-known/openapi.json    # full OpenAPI 3.1
curl https://api.infrai.cc/.well-known/mcp.json         # MCP server descriptor
curl https://api.infrai.cc/llms.txt                     # AI-reading index

Next