REST API Contract

REST API Contract

AifApi provides transport-neutral handlers for inference, embedding, and moderation. Host frameworks own the HTTP route, authentication, trusted context source, and response status while keeping the AIF envelope stable.

Response Envelope

{
  "ok": true,
  "data": {
    "request_uid": "provider_request_id",
    "output": "Generated response",
    "provider": "mock",
    "model": "mock-text",
    "usage": {},
    "metadata": {}
  },
  "error": null
}

For errors:

{
  "ok": false,
  "data": null,
  "error": {
    "code": "policy_denied",
    "message": "The request was denied by policy.",
    "http_status": 403
  }
}

Public error codes include validation, policy denial, review required, invalid approval, prompt errors, unavailable provider capability, provider failure, governance configuration, evaluation failure, audit failure, cancellation, and circuit-open states. Internal exception details remain in protected audit evidence.

Request Shape

{
  "input": "Summarize this ticket",
  "prompt_code": "summarize_ticket",
  "prompt_version": "1.0.0",
  "provider": "openai",
  "model": "approved-model",
  "variables": {},
  "metadata": {}
}

Embedding and moderation use the same envelope pattern with operation-specific response data. The exact route structure belongs to the host application. Keep permissions, workspace context, provider secrets, and audit persistence on the backend.