Documentation Index
Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt
Use this file to discover all available pages before exploring further.
Omnigent exposes a REST API under the /v1/ base path and a Server-Sent Events stream for real-time session output. Every resource — sessions, hosts, runners, policies, files, and terminals — is reachable through standard HTTP verbs. The Python client SDK (omnigent-client) wraps these endpoints with fully typed async methods, automatic SSE reconnection, and streaming helpers so you can build integrations without hand-rolling HTTP logic.
Base URL
| Environment | Base URL |
|---|
| Local server | http://localhost:6767 |
| Production | Your deployed server URL |
/v1/ prefix applies to every resource endpoint; the utility endpoints /api/version and /health are at the top level.
The full OpenAPI specification is available at /openapi.json on any running Omnigent server. You can import it into any OpenAPI-compatible tool (Postman, Insomnia, Scalar, etc.) for interactive exploration.
Python SDK
Install the Python client alongside the Omnigent package, or standalone:
# Standalone client only
pip install omnigent-client
# Full Omnigent package (includes the client)
pip install omnigent
OmnigentClient as an async context manager:
from omnigent_client import OmnigentClient
async with OmnigentClient(base_url="http://localhost:6767") as client:
sessions = await client.sessions.list()
for s in sessions:
print(s.id, s.status)
async with OmnigentClient(
base_url="http://localhost:6767",
headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."},
) as client:
...
One-shot query
For single-turn agent invocations you can use client.query() directly:
result = await client.query(model="my-agent", input="Summarize this PR")
print(result.text)
stream = await client.query(model="my-agent", input="Write a test", stream=True)
async for chunk in stream:
print(chunk, end="", flush=True)
SDK Namespaces
OmnigentClient organises endpoints into namespaces:
| Namespace | Class | Description |
|---|
client.sessions | SessionsNamespace | Create, list, stream, and manage sessions |
client.files | FilesNamespace | Upload and download session file resources |
client.responses | ResponsesNamespace | Low-level /v1/responses streaming (legacy) |
session() and sessions_chat() helpers on OmnigentClient are higher-level abstractions built on top of these namespaces.
API Endpoints at a Glance
| Group | Base Path | Page |
|---|
| Sessions | /v1/sessions | Sessions |
| Session Events | /v1/sessions/{id}/stream | Session Events |
| Session Policies | /v1/sessions/{id}/policies | Session Policies |
| Hosts | /v1/hosts | Hosts |
| Runners | /v1/runners | Runners |
| Resources | /v1/sessions/{id}/resources | Resources |
| Agents | /v1/agents | Agents & Registry |
| Server Policies | /v1/policies | Agents & Registry |
| Policy Registry | /v1/policy-registry | Agents & Registry |
Versioning
Two utility endpoints are available at the server root:
GET /api/version — Returns the installed Omnigent package version:
GET /health — Liveness check with optional per-session runner status:
# Bare liveness
curl http://localhost:6767/health
# With runner/host status for a session
curl "http://localhost:6767/health?session_id=conv_abc123"
# Batch lookup for multiple sessions
curl "http://localhost:6767/health?session_ids=conv_abc,conv_def,conv_ghi"
{
"status": "ok",
"session": {
"id": "conv_abc123",
"runner_online": true,
"host_online": true
}
}
Error Handling
The API returns standard HTTP status codes:
| Code | Meaning |
|---|
200 / 201 / 202 | Success |
400 | Invalid input — check request body |
401 | Unauthenticated |
403 | Forbidden — insufficient permissions |
404 | Resource not found |
409 | Conflict (e.g. duplicate name, host offline) |
422 | Validation error — see detail array |
504 | Timeout communicating with host or runner |
{
"detail": [
{
"loc": ["body", "handler"],
"msg": "Field required",
"type": "missing"
}
]
}
code and message fields:
{
"code": "not_found",
"message": "Session conv_abc123 does not exist"
}
OmnigentError on any non-2xx response. Access error.code and error.message to inspect the failure:
from omnigent_client import OmnigentClient, OmnigentError
try:
session = await client.sessions.get("conv_nonexistent")
except OmnigentError as e:
print(e.code, e.message)
