API Documentation
Last updated: September 2026
1. Overview
The IteraCompute API is OpenAI-compatible: if your application
already talks to the OpenAI API, migrating is a change of
base_url and API key. Chat
completions, Responses, streaming and tool calling work the way you expect.
2. Base URL & Authentication
API requests go to https://api.iteracompute.com/v1.
Chat Completions and Responses requests authenticate with your API key in the
Authorization header.
export ITERACOMPUTE_API_KEY="your-api-key"
curl --fail-with-body https://api.iteracompute.com/v1/chat/completions \
-H "Authorization: Bearer $ITERACOMPUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v4.1-flash","messages":[{"role":"user","content":"Reply with exactly: Hello!"}],"temperature":0,"max_tokens":128}'
3. Model IDs
Use the exact provider/model ID returned by the
Models endpoint; do not add an iteracompute/ prefix.
List the models currently published by the gateway:
curl --fail-with-body https://api.iteracompute.com/v1/models
The Models endpoint is public and returns the current gateway catalog.
Use its id values exactly as returned.
Commercial access to a model is still controlled by your API key and agreement.
4. Chat Completions
POST /v1/chat/completions follows
the OpenAI request and response format:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
)
resp = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash",
messages=[{"role": "user", "content": "Reply with exactly: Hello!"}],
temperature=0,
max_tokens=128,
)
print(resp.choices[0].message.content)
print(resp.usage) # prompt_tokens / completion_tokens / total_tokens
5. Responses API
POST /v1/responses supports the OpenAI
Responses API used by clients such as Codex:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
)
response = client.responses.create(
model="deepseek/deepseek-v4.1-flash",
input="Reply with exactly: Hello!",
max_output_tokens=128,
)
print(response.output_text)
6. Streaming (SSE)
Set "stream": true to receive
server-sent events. Chunks arrive as generated; token usage is
included in the final chunk that carries
usage, before the terminal
[DONE] event. Treat the stream as
one logical request: once tokens have been emitted, the request is
not retried transparently.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
)
stream = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash",
messages=[{"role": "user", "content": "Reply with exactly: Hello!"}],
stream=True,
stream_options={"include_usage": True},
temperature=0,
max_tokens=128,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
if chunk.usage: # final chunk: token usage
print("\n", chunk.usage)
7. Tool Calling
Tools are declared in the tools
parameter, following the OpenAI function-calling format. When the
model decides to call a tool, the response contains
tool_calls; send tool results back
with role "tool" to continue the
conversation.
import json
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.iteracompute.com/v1",
api_key=os.environ["ITERACOMPUTE_API_KEY"],
)
messages = [{"role": "user", "content": "What is the weather in Singapore?"}]
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
resp = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash",
messages=messages,
tools=tools,
tool_choice={"type": "function", "function": {"name": "get_weather"}},
max_tokens=512,
)
assistant_message = resp.choices[0].message
messages.append(assistant_message)
for call in assistant_message.tool_calls or []:
arguments = json.loads(call.function.arguments)
result = {"city": arguments["city"], "temperature_c": 29}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
final = client.chat.completions.create(
model="deepseek/deepseek-v4.1-flash",
messages=messages,
tools=tools,
max_tokens=512,
)
print(final.choices[0].message.content)
8. Error Codes
Errors use the OpenAI error format with a JSON body of
{"error": {"message", "type", "code"}}:
| Status |
Meaning |
| 400 | Invalid request - malformed JSON or missing required parameters |
| 401 | Authentication failed - missing or invalid API key |
| 403 | Key not permitted for this model or action |
| 404 | Unknown model or endpoint |
| 429 | Rate limit exceeded - slow down and honor Retry-After |
| 500 | Internal error - safe to retry the request |
| 503 | Model temporarily unavailable - retry with backoff |
9. Rate Limits
Every key carries its own limits - requests per minute, tokens per
minute and concurrent streams. When a limit is reached the API
returns 429 promptly rather than
queueing the request; honor the
Retry-After header before
retrying. Your key's limits are communicated during onboarding and
can be adjusted per agreement.
