AIRA API Documentation

Every request carries your issued key in the header:

Authorization: Bearer aira_live_<43 characters>

Key format: aira_live_ followed by 43 random characters (letters and digits, 256 bits of entropy). The key is shown once at issuance and stored on our side only as a hash — it cannot be recovered, only reissued. An organization can hold several keys (rotation: get a new one issued, switch, ask us to revoke the old one).

A wrong, revoked or missing key always gets the same 401 {"code":"invalid_api_key"}, with no detail. A suspended client gets 403 {"code":"client_suspended"}.

The API is server-to-server. CORS is not enabled: browser calls will not work, and should not — the key must never reach a client side.

Prepaid accounting: 1 credit = 1 audit. Credits are granted by your AIRA manager.

• A credit is charged atomically when the audit is queued (POST /audits → 202).
• Zero balance → 402 {"code":"insufficient_credits"}, nothing is created.
• If an audit ends up failed, the credit is returned automatically, exactly once. You do not pay for our failure.
• Submitting the same address while its previous audit is still in progress → 409 {"code":"audit_already_running","auditId":"…"}, no charge.
• The remaining balance is in every create response (creditsRemaining) and in GET /account.

queued → running → completed or failed.

An audit typically takes 1–5 minutes. On an internal retry the status may briefly go back from running to queued — that is normal; wait for a terminal state. Only completed audits have a report; for failed ones the report endpoint answers 410 with a failure code, and the credit is already back.

Recommended polling: GET /audits/{auditId} no more often than every 15 seconds.

• General limit: 60 requests per minute per key.
• Audit creation: 10 requests per minute per key (a separate, stricter limit on POST /audits).
• Exceeding a limit → 429 {"code":"rate_limited"} with a Retry-After header (seconds).

Body: websiteUrl (required), reportLevel — "basic" or "full", never above your contract level; omitted means the contract level.

curl -X POST https://engine.aisearchtune.com/api/v1/audits \
  -H "Authorization: Bearer aira_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"websiteUrl": "https://example.com", "reportLevel": "basic"}'

Response 202 Accepted:

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","status":"queued","creditsCharged":1,"creditsRemaining":41}

The address is normalized (one site, however spelled); a malformed one → 400 {"code":"invalid_url","reason":"…"}. URL validation and internal-network (SSRF) protections are the same as on aisearchtune.com itself.

curl https://engine.aisearchtune.com/api/v1/audits/aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c \
  -H "Authorization: Bearer aira_live_YOUR_KEY"

Response 200 (in progress; progress is present only while running):

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","status":"running","progress":45,"createdAt":"2026-08-27T10:15:00+00:00"}

Response 200 (finished):

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","status":"completed","createdAt":"2026-08-27T10:15:00+00:00","completedAt":"2026-08-27T10:18:12+00:00"}

A foreign or unknown id is always 404 {"code":"not_found"}.

curl https://engine.aisearchtune.com/api/v1/audits/aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c/report \
  -H "Authorization: Bearer aira_live_YOUR_KEY"

Response 200 — an envelope with the full report JSON at the level the audit was created with:

{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","websiteUrl":"https://example.com/","reportLevel":"basic","completedAt":"2026-08-27T10:18:12+00:00","report":{ …report… }}

Not finished yet → 409 {"code":"audit_not_completed"}. Failed → 410 {"code":"audit_failed","failureCode":"…"} (the credit is already refunded).

Parameters: limit (1–100, default 20), offset (default 0). Newest first.

curl "https://engine.aisearchtune.com/api/v1/audits?limit=20&offset=0" \
  -H "Authorization: Bearer aira_live_YOUR_KEY"

Response 200 (score only on completed audits):

{"items":[{"auditId":"aud_4f1c2b7a9d8e4f0a8c6b5d4e3f2a1b0c","websiteUrl":"https://example.com/","status":"completed","score":62,"createdAt":"2026-08-27T10:15:00+00:00"}],"total":1,"limit":20,"offset":0}

curl https://engine.aisearchtune.com/api/v1/account \
  -H "Authorization: Bearer aira_live_YOUR_KEY"

Response 200:

{"organization":"Example LLC","reportLevel":"full","creditsRemaining":41,"keysActive":2}