API Documentation

Each call materializes a throwaway thread (source: "completions") so the run goes through the same multimodal / RAG / guardrails pipeline as the Threads API. system messages are extracted into orchestrator instructions, other roles preserved as-is.

curl https://omra.pro/v1/chat/completions \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }'

# Python — official openai SDK works unchanged
from openai import OpenAI
client = OpenAI(api_key="oag_...", base_url="https://omra.pro/v1")
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Привет"}],
)
print(resp.choices[0].message.content)

Multimodal: pass content as an array with image_url parts (HTTPS or data: URIs). Vision routing happens automatically.

Streaming: set stream: true; emits standard OpenAI chat.completion.chunk SSE frames, terminated by data: [DONE]. Add stream_options: {"include_usage": true} for a final usage frame.

List models available to your company (system catalog + per-company overrides). Use the returned id as the model field in completions.

curl https://omra.pro/v1/models \
  -H "Authorization: Bearer $OAG_KEY"

curl -X POST https://omra.pro/v1/threads \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"user": "alice"}}'

curl -X POST https://omra.pro/v1/threads/$TID/messages \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "Analyze my Ozon sales for last week"}'

Batch-add multiple messages in one request.

Execute a model run on the thread. Non-streaming returns a single RunResponse; stream: true opens an SSE channel.

curl -X POST https://omra.pro/v1/threads/$TID/runs \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "instructions": "Be concise.",
    "stream": false,
    "enable_multimodal": true,
    "profile_ids": ["a4d3...sales-agent"],
    "mentioned_file_ids": ["7c2f...invoice.pdf"],
    "use_kb": true,
    "use_tools": true,
    "tool_choice": "auto"
  }'

# SSE frames when stream=true
data: {"delta": "Hello", "model": "gpt-4o"}
data: {"delta": " world", "model": "gpt-4o"}
data: {"done": true, "usage": {"prompt_tokens": 42, "completion_tokens": 7, "total_tokens": 49}, "latency_ms": 812}
data: [DONE]

List active collections.

curl -X POST https://omra.pro/v1/knowledge \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales playbook", "description": "Internal scripts"}'

Soft delete (deactivates the collection; documents preserved for audit).

List up to 500 most recent documents with status (pending / ready / failed).

Returns 202 Accepted. Allowed MIME: application/pdf, text/plain, text/markdown, DOCX, XLSX, legacy DOC/XLS. Optional folder_path field for grouping.

curl -X POST https://omra.pro/v1/knowledge/$CID/documents \
  -H "Authorization: Bearer $OAG_KEY" \
  -F "file=@playbook.pdf" \
  -F "folder_path=/onboarding"

Idempotent by name — re-posting an existing active tool returns it unchanged.

curl -X POST https://omra.pro/v1/tools \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "save_contact",
    "description": "Persist visitor contact in CRM",
    "json_schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "phone": {"type": "string"}
      },
      "required": ["phone"]
    },
    "python_code": "def run(name, phone):\n    return httpx.post(WEBHOOK, json={...}).json()"
  }'

Partial update of name / description / schema / code / is_active.

Soft delete — historical run logs that reference the tool stay intact.

List active profiles. Pass full=true to include system_prompt, KB and tool bindings.

Always returns the full payload.

curl -X POST https://omra.pro/v1/profiles \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support v2",
    "system_prompt": "You are a polite support agent.",
    "model_slug": "gpt-4o",
    "knowledge_base_ids": ["d4e5f6..."],
    "allowed_tool_names": ["save_contact"],
    "use_kb": true,
    "use_tools": true,
    "is_default": false
  }'

Send only the fields you want to change. Setting is_default: true demotes the previous default.

Soft delete — references from agents (conductor_profile_id) keep resolving for audit.

Returns {"company_id": "…", "company_name": "…"}. Lets a Messenger / CRM auto-link to the conductor company without copy-pasting UUIDs.

Record a non-AI usage event. Rates: voice_call 1.0 O₮/sec (~$0.06/min), whisper 0.1 O₮/sec (~$0.006/min). 1 O₮ = $0.001.

curl -X POST https://omra.pro/v1/usage \
  -H "Authorization: Bearer $OAG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "voice_call",
    "duration_s": 73.4,
    "direction": "inbound",
    "metadata": {"call_id": "CA-42"}
  }'

Exchange long-lived SDK key for a short-lived JWT (5 min TTL).

Fetch SDUI view definition + data for the SDK renderer.

Execute a service action from view (e.g. update deal stage, create invoice).

Create a new SDK API key with scopes and rate limits.

Returns 202 Accepted immediately. Payload routed to Event Bus or a specific agent.

curl -X POST https://omra.pro/v1/public/triggers/$CID/$SECRET \
  -H "Content-Type: application/json" \
  -d '{"event_topic": "order.created", "payload": {"order_id": "ORD-42"}}'