API Reference

Base URL & Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer iio-dev-{your-api-key}
Content-Type: application/json
X-IIO-Tenant: {tenant-id}   // optional — for multi-tenant routing

Get your API key on the Developer Portal. Keys start with iio-dev-.

POST Chat Completions

Creates a model response for the given conversation. OpenAI-compatible.

REQUEST BODY

Parameter	Type	Required	Description
model	string	required	Model ID (see Model Catalog)
messages	array	required	Array of message objects with role and content
stream	boolean	optional	Stream tokens as SSE. Default: false
temperature	number	optional	0–2. Default: 1.0
max_tokens	integer	optional	Max tokens to generate
system	string	optional	System prompt (alternative to messages[0].role=system)

EXAMPLE REQUEST

copy

{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user",   "content": "Summarize AI governance in 3 sentences."}
  ],
  "stream": false,
  "temperature": 0.7
}

EXAMPLE RESPONSE

{
  "id": "chatcmpl-iio-abc123",
  "object": "chat.completion",
  "created": 1748390400,
  "model": "qwen2.5:7b",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "AI governance ensures responsible development..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 87,
    "total_tokens": 115
  }
}

GET List Models

Returns all available models for your API key tier.

{
  "object": "list",
  "data": [
    {"id": "qwen2.5:7b",   "object": "model", "owned_by": "iio"},
    {"id": "qwen2.5:72b",  "object": "model", "owned_by": "iio"},
    {"id": "nomic-embed-text", "object": "model", "owned_by": "iio"}
  ]
}

POST Embeddings

Parameter	Type	Required	Description
model	string	required	nomic-embed-text or qwen3-embedding:8b
input	string|array	required	Text or array of texts to embed

{
  "model": "nomic-embed-text",
  "input": "AI governance framework for SMBs"
}

GET Health

{"status": "ok", "cells": 4, "models": 8, "latency_ms": 12}

Error Codes

HTTP	Code	Cause	Fix
401	auth_required	Missing or invalid API key	Add Authorization: Bearer {key}
403	tier_exceeded	Monthly request limit reached	Upgrade tier or wait for reset
422	invalid_model	Model not available on your tier	Use GET /v1/models to list available models
429	rate_limited	Too many requests per minute	Respect Retry-After header
503	cell_unavailable	AI Hub cell temporarily down	Retry after 30s; check /v1/health

Rate Limits

Tier	Requests / min	Requests / month	Models
Free	10	1,000	qwen2.5:7b only
Pro	60	50,000	All models
Enterprise	unlimited	custom	All + dedicated cell

Rate limit headers on every response: X-RateLimit-Limit · X-RateLimit-Remaining · X-RateLimit-Reset