Skip to content
infraiDocs
Console

Conventions

The shared rules every capability follows over raw HTTP: the request envelope, response metadata, the wire contract, idempotency and BYOK. No SDK required.

Request & response envelope

Every call is a POST (or GET) to https://api.infrai.cc/v1/… with a Bearer key and a JSON body. Every response uses the same envelope:

json
{
  "ok": true,
  "data": { /* capability-specific result */ },
  "error": null,
  "metadata": {
    "cost_usd": 0.00012,
    "latency_ms": 412,
    "vendor": "deepseek",
    "cache_hit": false,
    "request_id": "01HXY..."   // UUID v7
  }
}

Result metadata

Every call returns its data plus a metadata block, so an agent can read cost and latency without a vendor round-trip.

  • cost_usd · USD cost of this call, reconcilable with your bill.
  • latency_ms · End-to-end latency in milliseconds.
  • vendor · The upstream vendor that served the call.
  • cache_hit · Whether the response was served from cache.
  • request_id · Globally unique id (UUID v7) for support and reconciliation.

Wire contract

Call the API directly from any language over HTTPS. The shared wire rules:

AuthenticationAuthorization: Bearer <infrai_project_key>
Request bodyCanonical JSON: sorted keys, no spaces, trailing newline, UTF-8.
Idempotency headerIdempotency-Key
Request idmetadata.request_id (UUID v7)

Idempotency

Idempotency keeps retries safe — the same key never double-charges or duplicates a resource within the dedup window.

  • Read (GET) calls are idempotent by default — no key needed.
  • Cost-incurring calls derive a key server-side; passing your own is recommended.
  • Resource-creation calls require an explicit idempotency_key.
bash
# Cost-incurring calls: send an Idempotency-Key header so retries never double-charge.
curl -X POST https://api.infrai.cc/v1/email/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmed-123" \
  -d '{"to": "customer@x.com", "subject": "Order #123 confirmed", "html": "<p>Thanks!</p>"}'

When you omit a key on a cost-incurring call, the server derives one deterministically:

text
idempotency_key = sha256(account_id + request_id + capability + content_hash)

The default dedup window is 24 hours (minimum 1 hour, maximum 7 days). A repeat within the window returns the original result without re-charging.

BYOK (Bring Your Own Key)

Register your own vendor credentials so calls dispatch through your key instead of the shared pool.

bash
# Register your own vendor key; calls then dispatch through it.
curl -X POST https://api.infrai.cc/v1/byok \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "alias": "prod-gpt4o", "credentials": {"api_key": "sk-..."}}'

Credentials are write-only: the API never returns the plaintext key, only a short fingerprint you can recognize.