API Reference

Flit exposes an OpenAI-compatible HTTP interface over TLS or reverse proxy. Existing OpenAI client libraries, LangChain, and LlamaIndex agents can connect directly by updating the base URL.

1. Authentication

Inference requests authenticate using a virtual key passed in the standard HTTP Authorization header:

Authorization: Bearer <flit-virtual-key>

2. POST /v1/chat/completions

Generates chat completions for conversation messages with optional streaming.

Request Body Parameters

cURL Example

curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-virtual-key" \
  -d '{
    "model": "aquila",
    "messages": [
      {"role": "user", "content": "Extract customer sentiment from this feedback..."}
    ]
  }'

3. POST /v1/responses

Native OpenAI-compatible responses endpoint supporting batch requests and file inputs directly to the gateway.

curl -X POST http://localhost:4000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-virtual-key" \
  -d '{
    "model": "aquila-smart",
    "input": "Summarize quarterly compliance obligations."
  }'

4. GET /v1/models

Returns a catalog of models and tiers accessible to the authenticated virtual key. Unlike raw upstream proxies, Flit scopes this list according to the caller's team role and model permissions:

{
  "object": "list",
  "data": [
    {
      "id": "aquila",
      "object": "model",
      "owned_by": "aquila",
      "kind": "virtual"
    },
    {
      "id": "aquila-fast",
      "object": "model",
      "owned_by": "aquila",
      "kind": "virtual"
    },
    {
      "id": "aquila-smart",
      "object": "model",
      "owned_by": "aquila",
      "kind": "virtual"
    },
    {
      "id": "aquila-power",
      "object": "model",
      "owned_by": "aquila",
      "kind": "virtual"
    }
  ]
}

5. Native Model Context Protocol (MCP) Data Plane

External MCP client applications (such as Cursor, VS Code, or custom agent runtimes) connect directly to Flit's high-speed MCP data plane over Streamable HTTP or SSE:

POST http://localhost:4000/mcp
x-litellm-api-key: Bearer your-virtual-key
Content-Type: application/json

Flit validates the virtual key, enforces Team-assigned tool permissions (default-deny until explicitly allowed in the Admin UI), and streams protocol responses directly from registered upstream servers.

6. Agent-to-Agent (A2A) Protocol Endpoints

Flit acts as an enterprise gateway for external A2A autonomous agents:

• GET /v1/agents: Discover registered A2A agents permitted for the caller's virtual key.
• GET /a2a/{agent_id}/.well-known/agent-card.json: Retrieve standard agent capability cards.
• POST /a2a/{agent_id}/message/send: Dispatch JSON-RPC A2A message payloads.

7. Flit Control Plane API & Swagger Documentation

Interactive API documentation is hosted on the control plane at http://localhost:4000/docs (Swagger UI) and /openapi.json. State-mutating administrative endpoints require:

• An authenticated, encrypted aquila_session cookie.
• A valid anti-forgery token sent in the X-Aquila-CSRF header (retrieved from GET /api/me).

8. Error Codes & Diagnostics