{ "openapi": "3.1.0", "info": { "title": "Oqim API", "version": "0.1.0", "summary": "Authorized Telegram communications: accounts your organization owns, consented recipients, scheduled campaigns and webhooks.", "description": "The REST API behind the Oqim console, generated from the [API reference](/docs/api). The [documentation](/docs) has the guides, every [error code](/docs/errors) and the [rate limits](/docs/rate-limits).\n\n- Paths are relative to `/api/v1` on your Oqim host.\n- Authenticate with `Authorization: Bearer `. Each operation's description says whether API keys can call it; `x-oqim-permission` names the permission it needs.\n- Lists take `limit` (at most 500) and `offset`, and answer `{data, total, limit, offset}`.\n- Every response carries `X-Request-Id`. Rate-limited responses also carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`.\n- Examples are abbreviated, and schemas are inferred from them: fields that appear in only some responses aren't marked, so nothing is listed as required." }, "externalDocs": { "description": "Oqim documentation", "url": "/docs" }, "servers": [ { "url": "/api/v1", "description": "The Oqim host that serves this document." } ], "tags": [ { "name": "Authentication", "description": "Sign-up, sign-in and the API-key token exchange. These public endpoints are limited to 30 requests per minute per IP address." }, { "name": "Profile", "description": "The signed-in user or API key. The two-factor endpoints are for people; API keys get not_applicable." }, { "name": "Organization", "description": "The active organization, its policy acceptance, usage and dashboard data." }, { "name": "Team", "description": "Members, their roles and invitations. Owners can only be changed by owners." }, { "name": "Telegram accounts", "description": "Accounts your organization owns. Connecting is a three-step sign-in that a person completes; API keys can read accounts but not connect them. See Telegram accounts for states and pacing." }, { "name": "Channels: Instagram and Facebook", "description": "Instagram professional accounts (Instagram Login, no Facebook Page needed) and Facebook Pages (Facebook Login for Business) the organization connects, so their direct messages land in the same inbox as Telegram's (GET /ai/conversations?channel=INSTAGRAM|FACEBOOK) and the same AI Seller answers them under Meta's rules: automated replies only within 24 hours of the customer's last message, people up to 7 days with the HUMAN_AGENT tag where the platform has that permission, and never a message to someone who didn't write first. Tokens are encrypted and never returned. An Instagram account or Page is live in one organization at a time. Events: channels.account.updated (connected, status change, disconnected) and channels.history.imported (once, when a history import ends). Until Meta's App Review is done (review_pending), only people with a role on the platform's Meta app can connect. The webhook and the OAuth, deauthorize and data-deletion callbacks are public: Meta and the browser call them, and each verifies what it gets (the signed single-use state, X-Hub-Signature-256, the signed_request)." }, { "name": "Proxies", "description": "Network routes your organization controls, pinned to at most one account each. Oqim checks reachability; it never rotates proxies." }, { "name": "Recipients", "description": "People you may message and your basis for doing so. See Recipients for consent states and the CSV format." }, { "name": "Lists", "description": "Named groups of recipients. Deleting a list keeps its recipients." }, { "name": "Suppression list", "description": "Telegram IDs and usernames your organization must never message. Opt-outs land here automatically." }, { "name": "Templates and attachments", "description": "Reusable message bodies, files to attach, and previews rendered for real recipients." }, { "name": "Campaigns", "description": "Create a draft, validate it, launch it, then pause, resume or cancel it. Which fields can change depends on the status; see Campaigns. A repeating campaign runs as a series of campaigns that Oqim adds and launches one at a time; see Scheduling." }, { "name": "Jobs and events", "description": "Individual send jobs, the organization's event history, and a live stream of the same events." }, { "name": "API keys", "description": "Keys act as the API_CLIENT role in one organization. The full key appears once, in the create and rotate responses." }, { "name": "Webhooks", "description": "HTTPS endpoints that receive signed events. See Webhooks for payloads and signature verification." }, { "name": "AI Seller: configuration", "description": "Configure the AI Seller: the business the AI represents, its offer catalog, sales pipeline, persona, communication style, and runtime settings. Reads require ai:read; writes require ai:manage." }, { "name": "AI", "description": "Model providers for the writing assistant, and the assistant itself. Keys are encrypted and never returned. Only the brief or the message text you submit goes to a provider, never recipient data. See AI writing assistant." }, { "name": "AI engine", "description": "The AI Seller's engine: which provider and model each agent uses (with fallbacks), the model registry and its prices, versioned prompts, execution traces, costs and budgets. Model calls go through a router that tries the agent's chain in order, moves on after timeouts, 5xx answers, rate limits and unreachable endpoints (never after a rejected key or a bad request), and skips a provider that keeps failing for a short cool-off. Costs are in US dollars, over UTC days. Every change is written to the audit log." }, { "name": "AI Seller: conversations", "description": "The private Telegram chats of accounts with inbound turned on (PATCH /accounts/{id}, inbound_enabled), and the Instagram Direct and Facebook Messenger threads of connected accounts (see Channels: Instagram and Facebook), in one inbox: channel says which. A worker keeps one connection per such ACTIVE account and records every chat with a person, in both directions: author CUSTOMER, AI, HUMAN (from the console or the API) or OWNER_PHONE (typed in the account's own Telegram app). Groups, channels and bots are left out. Message text is encrypted at rest. People who write in become recipients with consent UNKNOWN (source INBOUND) until the plan's recipient limit. Oqim replies only inside a conversation the customer started, within the reply window (24 hours by default); outside it, only on recorded consent. A stop request (\"stop\", \"стоп\", \"toʻxtating\", \"kerak emas\", …) opts the person out and suppresses them for good. Live changes arrive on the event stream as ai.conversation.* and ai.handoff.* events. When an account serves a business whose Seller is active (seller-settings active), the AI takes a turn a few seconds after the customer writes: it reads the conversation, what it remembers and the business's knowledge, judges the message (JEV), picks the funnel stage, writes a reply and validates it (honesty, disclosure, facts only from the offers and knowledge, language, length, stage rules, no requests for secrets), then the business's autonomy level decides: 0 analytics only, 1 a recommendation, 2 a draft a person approves, 3 automatic only for the approved scenarios, 4 automatic, 5 automatic with approved tools. A customer who asks for a person or complains is handed to a person (a handoff) instead, and so is one who wants a booking unless the organization connected a Google calendar (then the Calendar agent handles it before the reply: see AI Seller: calendar); one who asks to stop is opted out. Every turn is an execution (GET /ai/executions/{id}) and emits ai.turn.completed; replies emit ai.reply.drafted, ai.reply.blocked and, when delivered, ai.reply.sent; stage moves ai.stage.changed; leads ai.lead.updated; drafts ai.draft.updated. Personal chats (personal true) are never the AI's: the account's Telegram contacts become personal by themselves (personal_source CONTACT) and an owner marks any chat personal or not (OWNER, never overridden automatically). The AI never answers or analyses a personal chat, what it had worked out about one is removed, and the list hides them unless asked; people still read and answer them. Messages imported from a chat's past (POST /accounts/{id}/history/import on Telegram, POST /channels/accounts/{id}/history/import on Instagram and Facebook) have imported true and keep the platform's time: they never start a turn, a draft or an analysis, open no reply window, don't count as unread and fire no event; the AI reads only live messages." }, { "name": "AI Seller: knowledge and memory", "description": "What the AI Seller knows about a business and remembers about its customers. Knowledge sources are text, FAQ entries, offers (synced from offers), files and web pages; each change is ingested in the background into a new version (extracted, split into chunks, embedded when an embedding provider is configured), and the Seller only ever reads a source's published version. Memories are sealed customer data. Reading needs ai:read; changes need ai:manage and are audited." }, { "name": "AI Seller: decisions", "description": "The AI Seller's decision layer. For each customer message, TypeSafe's System One model (JEV) answers one batch of typed questions: intent, sales stage, whether to advance it, next action, interest, lead quality, objection, and whether to hand off, book a time, look up knowledge, stop messaging or say it's an AI. It returns probabilities and a confidence per field; it never writes the reply. Fields below their confidence threshold, or all of them when JEV is off, has no key or fails, go to your AI model with the same questions, and each field records its source (JEV or LLM). JEV is opt-in: with it on, each customer message (card numbers, phone numbers and e-mail addresses masked), a short conversation summary, the sales stage and funnel objectives, known needs and objections, offer names and the language go to TypeSafe. Never the conversation history, customer profiles, Telegram ids or keys. Decisions store the questions, answers, probabilities, confidence, thresholds and sources, not the message and no reasoning." }, { "name": "AI Seller: quality", "description": "Feedback, evaluation datasets and items, evaluation runs, and A/B experiments for the AI Seller. Feedback captures human annotations on AI replies (labels, rating, optional corrected text), with optional review requests. Datasets hold replay items; evaluations run those items through the current or a candidate config and score each reply with JEV or an LLM judge; experiments compare variants. Reading needs ai:read; adding feedback and items needs ai:operate; everything else needs ai:manage." }, { "name": "AI Seller: calendar", "description": "Google Calendar for the AI Seller. An organization connects one Google calendar through Google's consent screen (the platform's OAuth client; minimal scopes: the calendar's events, its free/busy times, and the account's e-mail address). The tokens are encrypted at rest and never returned. When a customer asks about a meeting, the Calendar agent (its own run, with the calendar prompt) turns the conversation into one action: CREATE, UPDATE, CANCEL, FIND or CHECK_AVAILABILITY. Before anything reaches Google it's validated: a start in the future in a known time zone, at least the business's notice ahead and within its booking horizon (calendar_config), inside its opening hours (business_hours), an allowed length, and no double booking (Google's free/busy and Oqim's own bookings). Then the gate decides: the customer confirms the exact time first (unless the business sets require_customer_confirmation false, at autonomy 5); the change runs by itself only at autonomy 5 with the tool granted to the Calendar agent (PATCH /ai/agents/CALENDAR/config, tool_permissions: calendar.create_event, calendar.update_event, calendar.cancel_event are off until granted); otherwise it waits for a person here. An ambiguous request hands the conversation to a person (CALENDAR_AMBIGUITY). Each action keeps its provenance: the conversation, the customer message, the Seller turn (execution_id), the Calendar agent's run (agent_execution_id), the JEV decision, the confidence, what the agent extracted (encrypted at rest), the model, the prompt version and the event. A change reaches Google once: the event's id derives from the action. Events: ai.calendar.connected, ai.calendar.disconnected, ai.calendar.action_created, ai.calendar.action_updated; the metric ai_calendar_actions counts actions by type and status." }, { "name": "AI Seller: case analysis and insights", "description": "Every conversation in scope (private chats of accounts with Conversation Intelligence on, never ones marked personal, whether or not the AI Seller answered them) is analysed into its business's cases across five dimensions (PURCHASE_OUTCOME, LOST_REASON, DISSATISFACTION, DEMAND, SERVICE_QUALITY), with five scores (satisfaction 1–5, sentiment 1–5, purchase_intent 0–4, urgency 0–3, trust 0–3) and five flags (probabilities; true from 0.6). JEV decides, the LLM writes: your model writes each business's case catalog once (built-in templates without a model); JEV classifies a conversation in one request: LIVE 3 minutes after the customer's last message (at most every 15 minutes), FINAL when it ends (opt-out, lead won or lost, handoff resolved) or has been quiet 12 hours, when your model answers the dimensions JEV left unclear. Without JEV (off, or no key) conversations get FINAL analyses from your model only (analysis_mode LLM); with Conversation Intelligence off for the platform or the organization, nothing is analysed (OFF). JEV gets the masked recent transcript and a short business context, never ids. Your model writes only the per-conversation explanation and the board narratives, lazily per locale, grounded in the conversation or the board's numbers, sealed at rest. Updates arrive on the event stream: ai.analysis.updated, ai.insights.narrative_ready, ai.cases.generated and ai.insights.backfill. A business's catalog also holds two topic dimensions, CONTENT_TOPIC and COMMENT_TOPIC (what its posts and videos and its audience's comments are about), which conversations are never classified on: they are what the social boards group content and comments by (see Social content)." }, { "name": "Social content", "description": "What a business publishes on Instagram, Facebook and YouTube, and how people react to it. Oqim reads each account's posts and videos of the last 90 days with their metrics, their comments (newest first, down to the ones it has) and the account's daily metrics: every 6 hours for Instagram and Facebook, every 24 hours for YouTube (its quota is shared by the whole platform), and on request. Instagram and Facebook accounts come from connecting them (Channels); YouTube channels are added by their link and read with the platform's key, and a channel its owner connects (POST /channels/youtube/connect) also gives Oqim its private Analytics: watch time, average view duration, subscribers gained and lost, traffic sources, and the audience's age, gender and country. JEV judges each comment (intent, sentiment, whether it needs a reply, shows a wish to buy, names a competitor or is abusive, and which of the business's comment topics it is about) and each caption (a clear call to action, an offer or price, the strength of its opening, and which of the business's content topics it is about), in one request each, masked and without ids; without JEV the organization's AI model classifies intents and captions, in batches of 50 within a daily cap taken from its AI budget. A choice below 0.5 confidence is UNCLEAR; a flag counts when its probability is at least 0.6. The business's topics are written by the AI model from its profile, offers and recent captions (POST /ai/businesses/{id}/cases/generate with dimensions CONTENT_TOPIC and COMMENT_TOPIC), with a built-in fallback; a sync asks for them the first time it needs them, and posts or comments judged before the topics existed are judged on them once. The numbers are computed from the platforms' own metrics; the narratives are written by the AI model from the board's numbers only, and one that states a number the board doesn't have is withheld. Captions and comments are sealed at rest." }, { "name": "Audit log and notifications", "description": "The organization's append-only audit trail and its in-console notifications." }, { "name": "Public", "description": "Endpoints without authentication: the opt-out page, the console's sign-in screens and the OpenAPI document." }, { "name": "Administration API", "description": "Platform-wide endpoints under /api/v1/admin, used by the admin console. They need a console session of a platform administrator with two-factor authentication on and verified in that session; API keys are refused. Every change is written to the audit log with the actor type PLATFORM_ADMIN." } ], "x-tagGroups": [ { "name": "API", "tags": [ "Authentication", "Profile", "Organization", "Team", "Telegram accounts", "Channels: Instagram and Facebook", "Proxies", "Recipients", "Lists", "Suppression list", "Templates and attachments", "Campaigns", "Jobs and events", "API keys", "Webhooks", "AI Seller: configuration", "AI", "AI engine", "AI Seller: conversations", "AI Seller: knowledge and memory", "AI Seller: decisions", "AI Seller: quality", "AI Seller: calendar", "AI Seller: case analysis and insights", "Social content", "Audit log and notifications", "Public" ] }, { "name": "Platform administration", "tags": [ "Administration API" ] } ], "paths": { "/auth/signup": { "post": { "operationId": "postAuthSignup", "summary": "Create a user and their organization, then start a console session", "description": "Create a user and their organization, then start a console session. Refused with signups_closed when sign-ups are off.\n\nNo authentication.", "tags": [ "Authentication" ], "x-oqim-permission": "Public", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "password": { "type": "string" }, "organization_name": { "type": "string" }, "timezone": { "type": "string" } } }, "example": { "name": "Dilnoza Yusupova", "email": "dilnoza@silkroad.example", "password": "at-least-10-characters", "organization_name": "Silk Road Events", "timezone": "Asia/Tashkent" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/login": { "post": { "operationId": "postAuthLogin", "summary": "Start a console session and set the oqim_session cookie", "description": "Start a console session and set the oqim_session cookie. With two-factor authentication on, the session is limited until POST /auth/mfa/verify.\n\nNo authentication.", "tags": [ "Authentication" ], "x-oqim-permission": "Public", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } } }, "example": { "email": "dilnoza@silkroad.example", "password": "at-least-10-characters" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "mfa_required": { "type": "boolean" } } }, "example": { "mfa_required": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/token": { "post": { "operationId": "postAuthToken", "summary": "Exchange an API key for a one-hour access token (oqat_…)", "description": "Exchange an API key for a one-hour access token (oqat_…). Use it as a bearer token exactly like the key.\n\nNo authentication.", "tags": [ "Authentication" ], "x-oqim-permission": "Public", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string" }, "api_key": { "type": "string" } } }, "example": { "grant_type": "api_key", "api_key": "oqk_n4v8t2kq7wzc_yR3fT9qLm2Vx8KpZc6WnB4sHd1JgQ7eU0aXoN5tYiEw" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "access_token": "oqat_eyJrIjoia2V5XzAxajlyOGExYzNlNWc3ajltMXAzcjV0N3c5IiwibyI6Im9yZ18wMWo5cjJtNmsi.Hq2vX8bN3mK5pL7rT9wY1zA4cE6gJ0sU", "token_type": "Bearer", "expires_in": 3600, "expires_at": "2026-09-26T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/mfa/verify": { "post": { "operationId": "postAuthMfaVerify", "summary": "Complete sign-in with a 6-digit TOTP code", "description": "Complete sign-in with a 6-digit TOTP code. One 30-second step of clock drift is accepted.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Authentication" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } }, "example": { "code": "492039" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/auth/logout": { "post": { "operationId": "postAuthLogout", "summary": "End the console session and clear the cookie", "description": "End the console session and clear the cookie.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Authentication" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me": { "get": { "operationId": "getMe", "summary": "Who is calling: the user or API key, the active organization, role, permissions and the current policy version", "description": "Who is calling: the user or API key, the active organization, role, permissions and the current policy version.\n\nAny signed-in person or API key.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchMe", "summary": "Change your name or password", "description": "Change your name or password. A new password needs the current one and at least 10 characters.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "current_password": { "type": "string" }, "new_password": { "type": "string" } } }, "example": { "name": "Dilnoza Yusupova", "current_password": "…", "new_password": "a-new-long-password" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me/switch-organization": { "post": { "operationId": "postMeSwitchOrganization", "summary": "Make another of your organizations the session's active one", "description": "Make another of your organizations the session's active one.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": [ "string", "null" ] } } }, "example": { "organization_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me/support/end": { "post": { "operationId": "postMeSupportEnd", "summary": "End your own support session: the record closes, the organization is told, and the cookie is cleared", "description": "End your own support session: the record closes, the organization is told, and the cookie is cleared. 409 not_in_support_session for any other session. Signing out does the same. While in a support session this and sign-out are the only writes allowed; everything else is 403 support_read_only.\n\nAny signed-in person or API key.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me/organizations": { "post": { "operationId": "postMeOrganizations", "summary": "Create an organization with you as its owner and switch to it", "description": "Create an organization with you as its owner and switch to it.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "timezone": { "type": "string" } } }, "example": { "name": "Silk Road Tours", "timezone": "Asia/Samarkand" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me/mfa/setup": { "post": { "operationId": "postMeMfaSetup", "summary": "Start two-factor enrollment", "description": "Start two-factor enrollment. Returns the TOTP secret and an otpauth:// URL for a QR code; nothing changes until you enable it.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "otpauth_url": { "type": "string" } } }, "example": { "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP", "otpauth_url": "otpauth://totp/Oqim:dilnoza@silkroad.example?algorithm=SHA1&digits=6&issuer=Oqim&period=30&secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me/mfa/enable": { "post": { "operationId": "postMeMfaEnable", "summary": "Turn two-factor authentication on by confirming a code from the authenticator", "description": "Turn two-factor authentication on by confirming a code from the authenticator. The current session counts as verified.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } }, "example": { "code": "492039" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/me/mfa/disable": { "post": { "operationId": "postMeMfaDisable", "summary": "Turn two-factor authentication off", "description": "Turn two-factor authentication off. Needs a current code. Platform administrators can't open the admin console without it.\n\nFor signed-in people. API keys get `not_applicable`.", "tags": [ "Profile" ], "x-oqim-permission": "Signed in", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } }, "example": { "code": "118305" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OWNER", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/organization": { "get": { "operationId": "getOrganization", "summary": "The active organization", "description": "The active organization.\n\nNeeds `org:read`, which API keys have.", "tags": [ "Organization" ], "x-oqim-permission": "org:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "timezone": "Asia/Tashkent", "suspended_reason": null, "suspended_at": null, "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchOrganization", "summary": "Rename the organization, change its default time zone, or turn its Conversation Intelligence (summaries, memory and the case analysis of conversations) off and on with conversation_intelligence_enabled", "description": "Rename the organization, change its default time zone, or turn its Conversation Intelligence (summaries, memory and the case analysis of conversations) off and on with conversation_intelligence_enabled.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Organization" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "conversation_intelligence_enabled": { "type": "boolean" } } }, "example": { "name": "Silk Road Events", "timezone": "Asia/Tashkent", "conversation_intelligence_enabled": true } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "timezone": "Asia/Tashkent", "suspended_reason": null, "suspended_at": null, "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/organization/accept-policy": { "post": { "operationId": "postOrganizationAcceptPolicy", "summary": "Accept the acceptable-use policy", "description": "Accept the acceptable-use policy. version must be the current one (policy_version in GET /me); anything else is a 422. Required before connecting accounts, launching or resuming.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Organization" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" } } }, "example": { "version": "2026-09" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "timezone": "Asia/Tashkent", "suspended_reason": null, "suspended_at": null, "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/organization/usage": { "get": { "operationId": "getOrganizationUsage", "summary": "The plan's limits, current usage, and 30 days of metered usage (messages sent, API requests, and AI requests and tokens when used) per UTC day", "description": "The plan's limits, current usage, and 30 days of metered usage (messages sent, API requests, and AI requests and tokens when used) per UTC day. A limit of 0 means unlimited.\n\nNeeds `billing:read`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Organization" ], "x-oqim-permission": "billing:read", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "plan": { "type": "string" }, "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "team_members": { "type": "integer" }, "webhooks": { "type": "integer" }, "api_access": { "type": "boolean" }, "analytics": { "type": "string" }, "price_monthly_usd": { "type": "integer" } } }, "current": { "type": "object", "properties": { "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "members": { "type": "integer" }, "webhooks": { "type": "integer" } } }, "daily": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "messages_sent": { "type": "integer" }, "api_requests": { "type": "integer" } } } } } }, "example": { "plan": { "plan": "PRO", "accounts": 10, "active_campaigns": 10, "recipients": 50000, "team_members": 5, "webhooks": 5, "api_access": true, "analytics": "basic", "price_monthly_usd": 49 }, "current": { "accounts": 3, "active_campaigns": 1, "recipients": 4210, "members": 4, "webhooks": 1 }, "daily": [ { "date": "2026-09-25", "messages_sent": 1204, "api_requests": 311 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/dashboard": { "get": { "operationId": "getDashboard", "summary": "Overview numbers, running campaigns, account health, queue state and 14 days of delivery outcomes", "description": "Overview numbers, running campaigns, account health, queue state and 14 days of delivery outcomes.\n\nNeeds `analytics:read`, which API keys have.", "tags": [ "Organization" ], "x-oqim-permission": "analytics:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kpis": { "type": "object", "properties": { "telegram_accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "scheduled_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "messages_sent": { "type": "integer" }, "messages_failed": { "type": "integer" }, "restricted_accounts": { "type": "integer" } } }, "attention": { "type": "array", "items": {} }, "running": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" } } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" } } } }, "account_health": { "type": "object", "properties": { "ACTIVE": { "type": "integer" } } }, "queue": { "type": "object", "properties": { "pending": { "type": "integer" }, "queued": { "type": "integer" }, "sending": { "type": "integer" }, "delivered_last_hour": { "type": "integer" } } } } }, "example": { "kpis": { "telegram_accounts": 3, "active_campaigns": 1, "scheduled_campaigns": 2, "recipients": 4210, "messages_sent": 12840, "messages_failed": 96, "restricted_accounts": 0 }, "attention": [], "running": [ { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "name": "Expo reminder, day before", "status": "RUNNING", "total_recipients": 1840, "delivered_count": 612 } ], "series": [ { "date": "2026-09-25", "delivered": 1204, "failed": 9, "unavailable": 31 } ], "account_health": { "ACTIVE": 3 }, "queue": { "pending": 1212, "queued": 2, "sending": 1, "delivered_last_hour": 468 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/analytics/messages": { "get": { "operationId": "getAnalyticsMessages", "summary": "Delivery outcomes over the last days (1 to 365, default 30) in the organization's time zone: per day, per account and per campaign", "description": "Delivery outcomes over the last days (1 to 365, default 30) in the organization's time zone: per day, per account and per campaign.\n\nNeeds `analytics:read`, which API keys have.", "tags": [ "Organization" ], "x-oqim-permission": "analytics:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "How many days, ending today.", "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer" }, "timezone": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" } } } }, "by_account": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" } } } }, "by_campaign": { "type": "array", "items": { "type": "object", "properties": { "campaign_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" } } } }, "totals": { "type": "object", "properties": { "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" }, "attempted": { "type": "integer" }, "success_rate": { "type": "number" } } } } }, "example": { "days": 30, "timezone": "Asia/Tashkent", "series": [ { "date": "2026-09-25", "delivered": 1204, "failed": 9, "unavailable": 31 } ], "by_account": [ { "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "display_name": "Silk Road Support", "delivered": 3180, "failed": 12, "unavailable": 41 } ], "by_campaign": [ { "campaign_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "name": "Expo reminder, day before", "delivered": 612, "failed": 4, "unavailable": 9 } ], "totals": { "delivered": 12840, "failed": 96, "unavailable": 355, "attempted": 13291, "success_rate": 0.966 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members": { "get": { "operationId": "getMembers", "summary": "Members of the organization with their role and sign-in details", "description": "Members of the organization with their role and sign-in details.\n\nNeeds `members:read`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Team" ], "x-oqim-permission": "members:read", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "user_id": { "type": "string" }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "user_name": { "type": "string" }, "user_email": { "type": "string" }, "last_login_at": { "type": "string", "format": "date-time" }, "mfa_enabled": { "type": "boolean" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "mem_01j9rk9p1s3v5x7z9b1d3f5h7k", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "role": "OWNER", "created_at": "2026-09-01T10:00:00Z", "user_name": "Dilnoza Yusupova", "user_email": "dilnoza@silkroad.example", "last_login_at": "2026-09-26T07:58:10Z", "mfa_enabled": true } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/members/{id}": { "patch": { "operationId": "patchMembersById", "summary": "Change a member's role: OWNER, ADMIN, MANAGER, OPERATOR or VIEWER", "description": "Change a member's role: OWNER, ADMIN, MANAGER, OPERATOR or VIEWER. Only owners grant or remove the owner role, and the last owner can't be demoted (409 last_owner).\n\nNeeds `members:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Team" ], "x-oqim-permission": "members:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Membership ID (mem_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string" } } }, "example": { "role": "MANAGER" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "user_id": { "type": "string" }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "user_name": { "type": "string" }, "user_email": { "type": "string" }, "last_login_at": { "type": "string", "format": "date-time" }, "mfa_enabled": { "type": "boolean" } } }, "example": { "id": "mem_01j9rk9p1s3v5x7z9b1d3f5h7k", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "role": "MANAGER", "created_at": "2026-09-01T10:00:00Z", "user_name": "Dilnoza Yusupova", "user_email": "dilnoza@silkroad.example", "last_login_at": "2026-09-26T07:58:10Z", "mfa_enabled": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteMembersById", "summary": "Remove a member from the organization", "description": "Remove a member from the organization. Their user remains. The last owner can't be removed.\n\nNeeds `members:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Team" ], "x-oqim-permission": "members:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Membership ID (mem_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/invitations": { "get": { "operationId": "getInvitations", "summary": "Pending and past invitations", "description": "Pending and past invitations.\n\nNeeds `members:read`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Team" ], "x-oqim-permission": "members:read", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "role": { "type": "string" }, "invited_by": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "inv_01j9rj6m8p0r2t4w6y8a0c2e4g", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "email": "timur@silkroad.example", "role": "OPERATOR", "invited_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "expires_at": "2026-10-03T09:30:00Z", "accepted_at": null, "revoked_at": null, "created_at": "2026-09-26T09:30:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postInvitations", "summary": "Invite someone by email", "description": "Invite someone by email. Oqim doesn't send email: share invite_url, which appears only in this response. Invitations expire after 7 days.\n\nNeeds `members:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Team" ], "x-oqim-permission": "members:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string" } } }, "example": { "email": "timur@silkroad.example", "role": "OPERATOR" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "role": { "type": "string" }, "invited_by": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "invite_url": { "type": "string" } } }, "example": { "id": "inv_01j9rj6m8p0r2t4w6y8a0c2e4g", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "email": "timur@silkroad.example", "role": "OPERATOR", "invited_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "expires_at": "2026-10-03T09:30:00Z", "accepted_at": null, "revoked_at": null, "created_at": "2026-09-26T09:30:00Z", "invite_url": "https://app.example.com/invite/Zk3u9QxP2mVb7Ld0sWc4Rt8nYe1Ha6Jg5Uo2Fi9Kp0" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/invitations/{id}": { "delete": { "operationId": "deleteInvitationsById", "summary": "Revoke an invitation", "description": "Revoke an invitation. One that was already accepted can't be revoked (409 invitation_accepted); remove the member instead.\n\nNeeds `members:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Team" ], "x-oqim-permission": "members:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Invitation ID (inv_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/invitations/lookup": { "get": { "operationId": "getInvitationsLookup", "summary": "Describe an invitation from its token before accepting it", "description": "Describe an invitation from its token before accepting it. Unknown tokens are 404 invalid_invitation; used, revoked or expired ones are 410.\n\nNo authentication.", "tags": [ "Team" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "The token from the invitation link.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "existing_user": { "type": "boolean" } } }, "example": { "organization_name": "Silk Road Events", "email": "timur@silkroad.example", "role": "OPERATOR", "expires_at": "2026-10-03T09:30:00Z", "existing_user": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/invitations/accept": { "post": { "operationId": "postInvitationsAccept", "summary": "Accept an invitation and start a session", "description": "Accept an invitation and start a session. New users set their name and password here; existing users must be signed in as the invited email.\n\nNo authentication.", "tags": [ "Team" ], "x-oqim-permission": "Public", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "password": { "type": "string" } } }, "example": { "token": "Zk3u9QxP2mVb7Ld0sWc4Rt8nYe1Ha6Jg5Uo2Fi9Kp0", "name": "Timur Rakhimov", "password": "at-least-10-characters" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "aup_version": { "type": [ "string", "null" ] } } }, "role": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" } } } } } }, "mfa_verified": { "type": "boolean" }, "policy_version": { "type": "string" } } }, "example": { "kind": "user", "user": { "id": "usr_01j9s2c4e6g8j0m2p4r6t8w0y2", "email": "timur@silkroad.example", "name": "Timur Rakhimov", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": false, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" }, "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "aup_version": "2026-09" }, "role": "OPERATOR", "permissions": [ "org:read", "org:manage", "members:read", "members:manage", "accounts:read", "accounts:manage", "proxies:read", "proxies:manage", "recipients:read", "recipients:manage", "campaigns:read", "campaigns:manage", "campaigns:execute", "analytics:read", "audit:read", "developers:manage", "webhooks:read", "webhooks:manage", "billing:read" ], "organizations": [ { "role": "OWNER", "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO" } } ], "mfa_verified": true, "policy_version": "2026-09" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts": { "get": { "operationId": "getAccounts", "summary": "Connected accounts", "description": "Connected accounts.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAccounts", "summary": "Start signing in to an account: Telegram sends a login code, usually to the Telegram app", "description": "Start signing in to an account: Telegram sends a login code, usually to the Telegram app. The flow lasts 15 minutes. Needs an accepted acceptable-use policy. A proxy_id of a disabled proxy is a 422.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "proxy_id": { "type": [ "string", "null" ] } } }, "example": { "phone": "+998901234517", "proxy_id": null } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "object", "properties": { "flow_id": { "type": "string" }, "step": { "type": "string" }, "phone_masked": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "code_type": { "type": "string" } } }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } } } }, "example": { "state": { "flow_id": "flw_01j9r9k3m5p7r9t1v3x5z7b9d1", "step": "CODE_SENT", "phone_masked": "+998 •• ••• 45 17", "expires_at": "2026-09-26T09:40:00Z", "code_type": "app" }, "account": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/login/{flow_id}/code": { "post": { "operationId": "postAccountsLoginByFlowIdCode", "summary": "Submit the login code", "description": "Submit the login code. The step becomes PASSWORD_REQUIRED when two-step verification is on, otherwise COMPLETED with the account. A wrong code is 422 phone_code_invalid; a flow allows 5 attempts.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "description": "Login flow ID (flw_…), from the response that started the sign-in.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } }, "example": { "code": "54210" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "object", "properties": { "flow_id": { "type": "string" }, "step": { "type": "string" }, "phone_masked": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "password_hint": { "type": "string" } } }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } } } }, "example": { "state": { "flow_id": "flw_01j9r9k3m5p7r9t1v3x5z7b9d1", "step": "PASSWORD_REQUIRED", "phone_masked": "+998 •• ••• 45 17", "expires_at": "2026-09-26T09:40:00Z", "password_hint": "office safe" }, "account": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/login/{flow_id}/password": { "post": { "operationId": "postAccountsLoginByFlowIdPassword", "summary": "Submit the two-step verification password to finish signing in", "description": "Submit the two-step verification password to finish signing in. A wrong password is 422 password_hash_invalid.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "flow_id", "in": "path", "required": true, "description": "Login flow ID (flw_…), from the response that started the sign-in.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } } }, "example": { "password": "…" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "object", "properties": { "flow_id": { "type": "string" }, "step": { "type": "string" }, "phone_masked": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "account_id": { "type": [ "string", "null" ] } } }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } } } }, "example": { "state": { "flow_id": "flw_01j9r9k3m5p7r9t1v3x5z7b9d1", "step": "COMPLETED", "phone_masked": "+998 •• ••• 45 17", "expires_at": "2026-09-26T09:40:00Z", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" }, "account": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}": { "get": { "operationId": "getAccountsById", "summary": "One account", "description": "One account.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } }, "example": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchAccountsById", "summary": "Change pacing, the proxy or inbound", "description": "Change pacing, the proxy or inbound. daily_limit and min_interval_seconds must stay within the platform's bounds; proxy_id null detaches the proxy, a proxy already used by another account is 409 proxy_in_use, and a disabled proxy is a 422 on proxy_id. inbound_enabled true keeps a connection open while the account is ACTIVE and records its private conversations for the AI Seller; turning it off stops that, and turning it on again starts from then rather than replaying the pause.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "proxy_id": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" } } }, "example": { "daily_limit": 120, "min_interval_seconds": 10, "proxy_id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "inbound_enabled": true } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } }, "example": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "daily_limit": 120, "min_interval_seconds": 10, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": true, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": "Tashkent office", "active_campaigns": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAccountsById", "summary": "Log the session out, delete the encrypted session and remove the account", "description": "Log the session out, delete the encrypted session and remove the account. Refused with 409 account_in_use while a running campaign uses it. Delivery history stays.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/pause": { "post": { "operationId": "postAccountsByIdPause", "summary": "Stop sending from an active account", "description": "Stop sending from an active account. It keeps its session; its campaigns continue on their other accounts.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } }, "example": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "PAUSED", "status_reason": "Paused by dilnoza@silkroad.example", "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/resume": { "post": { "operationId": "postAccountsByIdResume", "summary": "Resume a paused, disconnected or errored account", "description": "Resume a paused, disconnected or errored account. A RESTRICTED account needs acknowledge_restriction: true from a signed-in person, never an API key (403 person_required). Accounts that need to sign in again use reauth instead.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledge_restriction": { "type": "boolean" } } }, "example": { "acknowledge_restriction": true } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } }, "example": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/check": { "post": { "operationId": "postAccountsByIdCheck", "summary": "Ask a worker to check the session with Telegram now and update the status", "description": "Ask a worker to check the session with Telegram now and update the status.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } }, "example": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/reauth": { "post": { "operationId": "postAccountsByIdReauth", "summary": "Sign an AUTH_REQUIRED or DISCONNECTED account in again with the same phone number", "description": "Sign an AUTH_REQUIRED or DISCONNECTED account in again with the same phone number. Continues like POST /accounts, with the code and password steps.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" } } }, "example": { "phone": "+998901234517" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "object", "properties": { "flow_id": { "type": "string" }, "step": { "type": "string" }, "phone_masked": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "code_type": { "type": "string" } } }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } } } }, "example": { "state": { "flow_id": "flw_01j9r9k3m5p7r9t1v3x5z7b9d1", "step": "CODE_SENT", "phone_masked": "+998 •• ••• 45 17", "expires_at": "2026-09-26T09:40:00Z", "code_type": "app" }, "account": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/activity": { "get": { "operationId": "getAccountsByIdActivity", "summary": "The account's latest events and send jobs", "description": "The account's latest events and send jobs.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "data": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ] } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "campaign_recipient_id": { "type": "string" }, "recipient_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "result": { "type": "string" }, "attempts": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "example": { "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "events": [ { "id": "evt_01j9r7m2p4s6v8x0z2b4d6f8h0", "type": "account.connected", "data": { "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" }, "created_at": "2026-09-30T05:00:02Z" } ], "jobs": [ { "id": "job_01j9rc8e0g2j4m6p8r0t2w4y6a", "campaign_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "campaign_recipient_id": "crp_01j9rd1f3h5k7m9p1s3v5x7z9b", "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "status": "SUCCEEDED", "result": "DELIVERED", "attempts": 1, "last_error": null, "created_at": "2026-09-30T08:14:01Z", "started_at": "2026-09-30T08:14:01Z", "completed_at": "2026-09-30T08:14:02Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/test-message": { "post": { "operationId": "postAccountsByIdTestMessage", "summary": "Send one message from an active account to a recipient (recipient_id) or a public @username (username), to try the account or a draft", "description": "Send one message from an active account to a recipient (recipient_id) or a public @username (username), to try the account or a draft. Variables are filled in, the account's pacing and daily limit apply, and a failure affects the account just as a campaign send would. Opted-out and suppressed people are refused (422 recipient_opted_out, recipient_suppressed). An organization can send 20 test messages an hour and an account 10 (429 test_limit_reached). Needs an accepted acceptable-use policy.\n\nNeeds `campaigns:execute`, which API keys have.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "campaigns:execute", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_id": { "type": "string" }, "text": { "type": "string" }, "parse_mode": { "type": "string" } } }, "example": { "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "text": "Hi {{first_name|there}}! This is a test from Silk Road Support.", "parse_mode": "MARKDOWN" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string" }, "message_id": { "type": [ "integer", "null" ] }, "message": { "type": [ "string", "null" ] }, "account_status": { "type": "string" } } }, "example": { "result": "DELIVERED", "message_id": 48301, "message": "Delivered. Check the recipient's Telegram.", "account_status": "ACTIVE" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/history/import": { "post": { "operationId": "postAccountsByIdHistoryImport", "summary": "Import the account's past private chats so the case analysis can explain conversations from before Oqim", "description": "Import the account's past private chats so the case analysis can explain conversations from before Oqim. A worker reads them through the account's own session and only reads: nothing is sent and nothing is marked read. It takes private chats with people whose last message is on or after since (YYYY-MM-DD in your organization's time zone, at most 365 days back, 90 by default), at most 500 messages per chat, the newest first; messages from the minute before the import started on are left to the live listener. Groups, channels, bots, Saved Messages, Telegram's service accounts and deleted accounts are skipped, and so are personal chats: the account's contacts (unless include_contacts is true, and even then their conversations stay personal) and chats marked personal. Imported messages keep Telegram's time and are marked imported: they never start an AI turn, a draft or an analysis, open no reply window, don't count as unread and fire no event or webhook, except that a stop request in them still opts the person out. A re-import adds only what's missing. It pauses exactly as long as Telegram asks (FLOOD_WAIT) and resumes where it stopped after a restart. One import per account at a time (409 history_import_running); only ACTIVE accounts (409 account_not_active); since out of range is a 422. channels.history.imported fires once when it's done. Needs an accepted acceptable-use policy.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date" }, "include_contacts": { "type": "boolean" } } }, "example": { "since": "2026-06-29", "include_contacts": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "since": { "type": "string", "format": "date" }, "chats_found": { "type": "integer" }, "chats_imported": { "type": "integer" }, "chats_skipped_personal": { "type": "integer" }, "messages_imported": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "example": { "status": "RUNNING", "since": "2026-06-29", "chats_found": 0, "chats_imported": 0, "chats_skipped_personal": 0, "messages_imported": 0, "started_at": "2026-09-27T08:00:00Z", "finished_at": null, "error": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/history": { "get": { "operationId": "getAccountsByIdHistory", "summary": "The account's latest history import: status IDLE (never imported), RUNNING, DONE, FAILED (error says why, e.g", "description": "The account's latest history import: status IDLE (never imported), RUNNING, DONE, FAILED (error says why, e.g. the account was signed out) or CANCELLED; chats_found are its private chats with people within the period, of which chats_imported were read and chats_skipped_personal left out as personal; messages_imported counts messages added.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "since": { "type": "string", "format": "date" }, "chats_found": { "type": "integer" }, "chats_imported": { "type": "integer" }, "chats_skipped_personal": { "type": "integer" }, "messages_imported": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "example": { "status": "DONE", "since": "2026-06-29", "chats_found": 48, "chats_imported": 41, "chats_skipped_personal": 7, "messages_imported": 3120, "started_at": "2026-09-27T08:00:00Z", "finished_at": "2026-09-27T08:14:36Z", "error": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/accounts/{id}/history/cancel": { "post": { "operationId": "postAccountsByIdHistoryCancel", "summary": "Stop the running import", "description": "Stop the running import. The worker stops before its next page; what was imported stays. 409 history_import_not_running when none is running.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Telegram accounts" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "since": { "type": "string", "format": "date" }, "chats_found": { "type": "integer" }, "chats_imported": { "type": "integer" }, "chats_skipped_personal": { "type": "integer" }, "messages_imported": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "example": { "status": "CANCELLED", "since": "2026-06-29", "chats_found": 48, "chats_imported": 12, "chats_skipped_personal": 7, "messages_imported": 804, "started_at": "2026-09-27T08:00:00Z", "finished_at": "2026-09-27T08:03:10Z", "error": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/providers": { "get": { "operationId": "getChannelsProviders", "summary": "Which platforms this Oqim platform can connect: configured (the platform owner set up the Meta app; otherwise connecting is 409 provider_not_configured), review_pending (only accounts with a role on the Meta app can connect yet), human_agent (people may answer up to 7 days after a customer's last message) and history_messages_per_thread (history imports read only this many of a thread's most recent messages: Meta's limit)", "description": "Which platforms this Oqim platform can connect: configured (the platform owner set up the Meta app; otherwise connecting is 409 provider_not_configured), review_pending (only accounts with a role on the Meta app can connect yet), human_agent (people may answer up to 7 days after a customer's last message) and history_messages_per_thread (history imports read only this many of a thread's most recent messages: Meta's limit).\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "instagram": { "type": "object", "properties": { "configured": { "type": "boolean" }, "review_pending": { "type": "boolean" }, "human_agent": { "type": "boolean" }, "history_messages_per_thread": { "type": "integer" } } }, "facebook": { "type": "object", "properties": { "configured": { "type": "boolean" }, "review_pending": { "type": "boolean" }, "human_agent": { "type": "boolean" }, "history_messages_per_thread": { "type": "integer" } } }, "youtube": { "type": "object", "properties": { "configured": { "type": "boolean" } } } } }, "example": { "instagram": { "configured": true, "review_pending": true, "human_agent": false, "history_messages_per_thread": 20 }, "facebook": { "configured": true, "review_pending": true, "human_agent": false, "history_messages_per_thread": 20 }, "youtube": { "configured": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/instagram/connect": { "post": { "operationId": "postChannelsInstagramConnect", "summary": "The Instagram Login URL to send the person to", "description": "The Instagram Login URL to send the person to. Its state is signed, lasts 10 minutes and works once. After they allow access, Instagram returns them to the callback, which connects the account and sends them to the console's /channels page. A person signed in to the console connects accounts (API keys get 403 person_required); 409 provider_not_configured when the platform has no Instagram app. Needs an accepted acceptable-use policy.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } }, "example": { "url": "https://www.instagram.com/oauth/authorize?client_id=990602627938098&redirect_uri=https%3A%2F%2Fapp.example.com%2Fapi%2Fv1%2Fchannels%2Finstagram%2Fcallback&response_type=code&scope=instagram_business_basic%2Cinstagram_business_manage_messages%2Cinstagram_business_manage_comments%2Cinstagram_business_manage_insights&state=…" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/instagram/callback": { "get": { "operationId": "getChannelsInstagramCallback", "summary": "Where Instagram returns the browser (public; the state is verified and used once, and the browser must carry the console session of the person who started the flow, so nobody can be tricked into connecting their account to another organization)", "description": "Where Instagram returns the browser (public; the state is verified and used once, and the browser must carry the console session of the person who started the flow, so nobody can be tricked into connecting their account to another organization). The code becomes a 60-day token, the account is read, stored with capabilities from the permissions granted, subscribed to its webhooks (messages, messaging_postbacks, message_reactions, messaging_seen, and comments and mentions when granted) and its history import starts. Redirects (302) to PUBLIC_APP_URL/channels?connected=, or ?error= denied, state_invalid, already_connected_elsewhere, missing_permissions (messaging must be allowed) or provider_error.\n\nNo authentication.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "Filter by code.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Filter by state.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Filter by error.", "schema": { "type": "string" } }, { "name": "error_reason", "in": "query", "required": false, "description": "Filter by error reason.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found: the Location header has the URL to follow.", "headers": { "Location": { "description": "The URL to follow.", "schema": { "type": "string", "format": "uri" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/facebook/connect": { "post": { "operationId": "postChannelsFacebookConnect", "summary": "The Facebook Login for Business URL (with the platform's login configuration when it has one, else the pages_* permissions)", "description": "The Facebook Login for Business URL (with the platform's login configuration when it has one, else the pages_* permissions). Same rules as Instagram's.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } }, "example": { "url": "https://www.facebook.com/v25.0/dialog/oauth?client_id=442224939723604&redirect_uri=https%3A%2F%2Fapp.example.com%2Fapi%2Fv1%2Fchannels%2Ffacebook%2Fcallback&response_type=code&state=…&scope=pages_show_list%2Cpages_manage_metadata%2Cpages_messaging%2Cpages_read_engagement%2Cpages_read_user_content%2Cbusiness_management" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/facebook/callback": { "get": { "operationId": "getChannelsFacebookCallback", "summary": "Where Facebook returns the browser (public; state-verified and bound to the starter's console session, as for Instagram)", "description": "Where Facebook returns the browser (public; state-verified and bound to the starter's console session, as for Instagram). Every Page the person granted is connected with its Page token and subscribed to messages, messaging_postbacks, message_echoes, message_reactions, message_reads (and feed), and its history import starts. Pages live in another organization are skipped. Redirects to PUBLIC_APP_URL/channels?connected=, or ?error= as for Instagram.\n\nNo authentication.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "Filter by code.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Filter by state.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Filter by error.", "schema": { "type": "string" } }, { "name": "error_reason", "in": "query", "required": false, "description": "Filter by error reason.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found: the Location header has the URL to follow.", "headers": { "Location": { "description": "The URL to follow.", "schema": { "type": "string", "format": "uri" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts": { "get": { "operationId": "getChannelsAccounts", "summary": "Connected accounts (Instagram, Facebook and YouTube), oldest first", "description": "Connected accounts (Instagram, Facebook and YouTube), oldest first. Instagram accounts and Pages have stats: their conversations and those whose 24-hour window is open. Filter by platform (INSTAGRAM, FACEBOOK, YOUTUBE) and status (CONNECTED, PUBLIC, AUTH_REQUIRED, ERROR, DISCONNECTED).\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "external_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "business_id": { "type": [ "string", "null" ] }, "ai_enabled": { "type": "boolean" }, "settings": { "type": "object", "properties": {} }, "connected_by": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "conversations": { "type": "integer" }, "open_windows": { "type": "integer" } } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "platform": "INSTAGRAM", "external_id": "17841400000000001", "name": "Silk Road Events", "username": "silkroad.events", "avatar_url": "https://scontent.cdninstagram.com/v/avatar.jpg", "status": "CONNECTED", "status_reason": null, "status_changed_at": "2026-09-20T08:00:00Z", "capabilities": [ "MESSAGING", "COMMENTS", "CONTENT" ], "scopes": [ "instagram_business_basic", "instagram_business_manage_messages", "instagram_business_manage_comments" ], "token_expires_at": "2026-11-19T08:00:00Z", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "ai_enabled": true, "settings": {}, "connected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "last_sync_at": null, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "stats": { "conversations": 42, "open_windows": 7 } } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}": { "get": { "operationId": "getChannelsAccountsById", "summary": "One connected account, with its stats", "description": "One connected account, with its stats.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "external_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "business_id": { "type": [ "string", "null" ] }, "ai_enabled": { "type": "boolean" }, "settings": { "type": "object", "properties": {} }, "connected_by": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "conversations": { "type": "integer" }, "open_windows": { "type": "integer" } } } } }, "example": { "id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "platform": "INSTAGRAM", "external_id": "17841400000000001", "name": "Silk Road Events", "username": "silkroad.events", "avatar_url": "https://scontent.cdninstagram.com/v/avatar.jpg", "status": "CONNECTED", "status_reason": null, "status_changed_at": "2026-09-20T08:00:00Z", "capabilities": [ "MESSAGING", "COMMENTS", "CONTENT" ], "scopes": [ "instagram_business_basic", "instagram_business_manage_messages", "instagram_business_manage_comments" ], "token_expires_at": "2026-11-19T08:00:00Z", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "ai_enabled": true, "settings": {}, "connected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "last_sync_at": null, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "stats": { "conversations": 42, "open_windows": 7 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchChannelsAccountsById", "summary": "The business the account serves (business_id; null clears it), whether its AI Seller answers the account's direct messages (ai_enabled: needs a business and the MESSAGING capability, otherwise a 422 on ai_enabled) and settings (an object)", "description": "The business the account serves (business_id; null clears it), whether its AI Seller answers the account's direct messages (ai_enabled: needs a business and the MESSAGING capability, otherwise a 422 on ai_enabled) and settings (an object). Audited.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "ai_enabled": { "type": "boolean" } } }, "example": { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "ai_enabled": true } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "external_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "business_id": { "type": [ "string", "null" ] }, "ai_enabled": { "type": "boolean" }, "settings": { "type": "object", "properties": {} }, "connected_by": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "conversations": { "type": "integer" }, "open_windows": { "type": "integer" } } } } }, "example": { "id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "platform": "INSTAGRAM", "external_id": "17841400000000001", "name": "Silk Road Events", "username": "silkroad.events", "avatar_url": "https://scontent.cdninstagram.com/v/avatar.jpg", "status": "CONNECTED", "status_reason": null, "status_changed_at": "2026-09-20T08:00:00Z", "capabilities": [ "MESSAGING", "COMMENTS", "CONTENT" ], "scopes": [ "instagram_business_basic", "instagram_business_manage_messages", "instagram_business_manage_comments" ], "token_expires_at": "2026-11-19T08:00:00Z", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "ai_enabled": true, "settings": {}, "connected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "last_sync_at": null, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "stats": { "conversations": 42, "open_windows": 7 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteChannelsAccountsById", "summary": "Disconnect the account: its webhook subscription is removed (best effort), its tokens deleted and its status DISCONNECTED", "description": "Disconnect the account: its webhook subscription is removed (best effort), its tokens deleted and its status DISCONNECTED. Its conversations and their history stay. It may then be connected by another organization.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}/check": { "post": { "operationId": "postChannelsAccountsByIdCheck", "summary": "Check the account with Meta now: its profile is read again and its webhook subscription renewed", "description": "Check the account with Meta now: its profile is read again and its webhook subscription renewed. The status follows: CONNECTED, AUTH_REQUIRED (the token expired or was revoked; reconnect) or ERROR with the reason. 502 provider_unavailable when Meta can't be reached.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "external_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "business_id": { "type": [ "string", "null" ] }, "ai_enabled": { "type": "boolean" }, "settings": { "type": "object", "properties": {} }, "connected_by": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "stats": { "type": "object", "properties": { "conversations": { "type": "integer" }, "open_windows": { "type": "integer" } } } } }, "example": { "id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "platform": "INSTAGRAM", "external_id": "17841400000000001", "name": "Silk Road Events", "username": "silkroad.events", "avatar_url": "https://scontent.cdninstagram.com/v/avatar.jpg", "status": "CONNECTED", "status_reason": null, "status_changed_at": "2026-09-20T08:00:00Z", "capabilities": [ "MESSAGING", "COMMENTS", "CONTENT" ], "scopes": [ "instagram_business_basic", "instagram_business_manage_messages", "instagram_business_manage_comments" ], "token_expires_at": "2026-11-19T08:00:00Z", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "ai_enabled": true, "settings": {}, "connected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "last_sync_at": null, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "stats": { "conversations": 42, "open_windows": 7 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}/history/import": { "post": { "operationId": "postChannelsAccountsByIdHistoryImport", "summary": "Import the account's past direct messages from Meta's Conversations API: threads active since since (a date, at most 365 days back; 90 days by default), and of each only the 20 most recent messages (Meta's limit), paced at 2 calls a second", "description": "Import the account's past direct messages from Meta's Conversations API: threads active since since (a date, at most 365 days back; 90 days by default), and of each only the 20 most recent messages (Meta's limit), paced at 2 calls a second. Imported messages keep Meta's times, are marked imported, and never start an AI turn, open a reply window, raise the unread count or fire per-message events; a stop request found in them still stops the conversation. Importing again adds only what's missing. An import already running is returned as it is. 409 history_unavailable when the account can't read its messages. It also starts when an account connects.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date" } } }, "example": { "since": "2026-06-29" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "since": { "type": "string", "format": "date" }, "chats_found": { "type": "integer" }, "chats_imported": { "type": "integer" }, "chats_skipped_personal": { "type": "integer" }, "messages_imported": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "example": { "status": "RUNNING", "since": "2026-06-29", "chats_found": 0, "chats_imported": 0, "chats_skipped_personal": 0, "messages_imported": 0, "started_at": "2026-09-20T08:00:05Z", "finished_at": null, "error": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}/history": { "get": { "operationId": "getChannelsAccountsByIdHistory", "summary": "The account's latest history import: status IDLE (never ran), RUNNING, DONE, FAILED or CANCELLED, with its counts", "description": "The account's latest history import: status IDLE (never ran), RUNNING, DONE, FAILED or CANCELLED, with its counts. chats_skipped_personal is always 0 on Instagram and Facebook.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "since": { "type": "string", "format": "date" }, "chats_found": { "type": "integer" }, "chats_imported": { "type": "integer" }, "chats_skipped_personal": { "type": "integer" }, "messages_imported": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "example": { "status": "DONE", "since": "2026-06-29", "chats_found": 38, "chats_imported": 35, "chats_skipped_personal": 0, "messages_imported": 512, "started_at": "2026-09-20T08:00:05Z", "finished_at": "2026-09-20T08:01:40Z", "error": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}/history/cancel": { "post": { "operationId": "postChannelsAccountsByIdHistoryCancel", "summary": "Stop a running import; what it stored stays", "description": "Stop a running import; what it stored stays. Returns the import.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "since": { "type": "string", "format": "date" }, "chats_found": { "type": "integer" }, "chats_imported": { "type": "integer" }, "chats_skipped_personal": { "type": "integer" }, "messages_imported": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } } }, "example": { "status": "CANCELLED", "since": "2026-06-29", "chats_found": 38, "chats_imported": 35, "chats_skipped_personal": 0, "messages_imported": 512, "started_at": "2026-09-20T08:00:05Z", "finished_at": "2026-09-20T08:01:40Z", "error": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/automations": { "get": { "operationId": "getChannelsAutomations", "summary": "List comment-to-DM automations", "description": "List comment-to-DM automations. ?connected_account_id= filters to one account. Newest first.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "connected_account_id", "in": "query", "required": false, "description": "Filter by connected account ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "posts_scope": { "type": "string" }, "post_ids": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "keywords": { "type": "array", "items": {} }, "threshold": { "type": "number" }, "reply_mode": { "type": "string" }, "templates": { "type": "object", "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "hourly_cap": { "type": "integer" }, "sent_last_hour": { "type": "integer" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cau_01j9r6d7f9k1m3p5r7t9v1w3x", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "account_id": "cha_…", "platform": "INSTAGRAM", "name": "Price questions", "enabled": true, "posts_scope": "ALL", "post_ids": [], "trigger": "JEV_PURCHASE_INTEREST", "keywords": [], "threshold": 0.7, "reply_mode": "TEMPLATE", "templates": { "uz": "Rahmat! Narxni DMda yubordik …", "ru": "…", "en": "…" }, "hourly_cap": 100, "sent_last_hour": 3, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T00:00:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postChannelsAutomations", "summary": "Create a comment-to-DM automation on one Instagram account or Facebook Page", "description": "Create a comment-to-DM automation on one Instagram account or Facebook Page. When the trigger fires on a comment on the account's own post (within 7 days), the private reply goes out once, within the hourly cap.\n\n422 validation_error names the field (scope, keywords, templates, threshold, hourly_cap); 404 account_not_found.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connected_account_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "posts_scope": { "type": "string" }, "post_ids": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "keywords": { "type": "string" }, "threshold": { "type": "string" }, "reply_mode": { "type": "string" }, "templates": { "type": "string" }, "hourly_cap": { "type": "string" } } }, "example": { "connected_account_id": "cha_…", "name": "Price questions (optional)", "enabled": true, "posts_scope": "ALL | SELECTED (with SELECTED, only the posts in post_ids)", "post_ids": [ "external post ids (social_posts.external_id) when posts_scope=SELECTED" ], "trigger": "KEYWORDS | JEV_PURCHASE_INTEREST", "keywords": "price,qancha? (required for KEYWORDS)", "threshold": "0.7 (JEV's confidence for JEV_PURCHASE_INTEREST, 0-1)", "reply_mode": "TEMPLATE | SELLER", "templates": "{ uz, ru, en } (at least one non-empty variant for TEMPLATE)", "hourly_cap": "100 (at most 750, Meta's limit)" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "posts_scope": { "type": "string" }, "post_ids": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "keywords": { "type": "array", "items": {} }, "threshold": { "type": "number" }, "reply_mode": { "type": "string" }, "templates": { "type": "object", "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "hourly_cap": { "type": "integer" }, "sent_last_hour": { "type": "integer" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cau_01j9r6d7f9k1m3p5r7t9v1w3x", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "account_id": "cha_…", "platform": "INSTAGRAM", "name": "Price questions", "enabled": true, "posts_scope": "ALL", "post_ids": [], "trigger": "JEV_PURCHASE_INTEREST", "keywords": [], "threshold": 0.7, "reply_mode": "TEMPLATE", "templates": { "uz": "Rahmat! Narxni DMda yubordik …", "ru": "…", "en": "…" }, "hourly_cap": 100, "sent_last_hour": 3, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T00:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/automations/{id}": { "get": { "operationId": "getChannelsAutomationsById", "summary": "One automation, with sent_last_hour: what went out in the last hour, against the cap", "description": "One automation, with sent_last_hour: what went out in the last hour, against the cap.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "posts_scope": { "type": "string" }, "post_ids": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "keywords": { "type": "array", "items": {} }, "threshold": { "type": "number" }, "reply_mode": { "type": "string" }, "templates": { "type": "object", "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "hourly_cap": { "type": "integer" }, "sent_last_hour": { "type": "integer" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cau_01j9r6d7f9k1m3p5r7t9v1w3x", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "account_id": "cha_…", "platform": "INSTAGRAM", "name": "Price questions", "enabled": true, "posts_scope": "ALL", "post_ids": [], "trigger": "JEV_PURCHASE_INTEREST", "keywords": [], "threshold": 0.7, "reply_mode": "TEMPLATE", "templates": { "uz": "Rahmat! Narxni DMda yubordik …", "ru": "…", "en": "…" }, "hourly_cap": 100, "sent_last_hour": 3, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T00:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchChannelsAutomationsById", "summary": "Change the fields the body carries; the same rules as on create apply", "description": "Change the fields the body carries; the same rules as on create apply.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": {} } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "{ ...any create field }" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "posts_scope": { "type": "string" }, "post_ids": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "keywords": { "type": "array", "items": {} }, "threshold": { "type": "number" }, "reply_mode": { "type": "string" }, "templates": { "type": "object", "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "hourly_cap": { "type": "integer" }, "sent_last_hour": { "type": "integer" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cau_01j9r6d7f9k1m3p5r7t9v1w3x", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "account_id": "cha_…", "platform": "INSTAGRAM", "name": "Price questions", "enabled": true, "posts_scope": "ALL", "post_ids": [], "trigger": "JEV_PURCHASE_INTEREST", "keywords": [], "threshold": 0.7, "reply_mode": "TEMPLATE", "templates": { "uz": "Rahmat! Narxni DMda yubordik …", "ru": "…", "en": "…" }, "hourly_cap": 100, "sent_last_hour": 3, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T00:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteChannelsAutomationsById", "summary": "Delete the automation", "description": "Delete the automation. Its past private replies stay in the log (their automation_id becomes null).\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file, with its original Content-Type.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}/private-replies": { "get": { "operationId": "getChannelsAccountsByIdPrivateReplies", "summary": "The private-reply log of an account: every comment an automation considered and what it did", "description": "The private-reply log of an account: every comment an automation considered and what it did. ?automation_id= and ?status= (PENDING, SENDING, SENT, FAILED, SKIPPED) filter.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } }, { "name": "automation_id", "in": "query", "required": false, "description": "Filter by automation ID.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "automation_id": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "comment_id": { "type": "string" }, "post_external_id": { "type": "string" }, "post_id": { "type": "string" }, "social_comment_id": { "type": [ "string", "null" ] }, "parent_comment_id": { "type": [ "string", "null" ] }, "commenter_id": { "type": "string" }, "commenter": { "type": "string" }, "comment_text": { "type": "string" }, "comment_created_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "status": { "type": "string" }, "skip_reason": { "type": [ "string", "null" ] }, "trigger": { "type": "string" }, "matched_keyword": { "type": [ "string", "null" ] }, "jev_probability": { "type": "number" }, "reply_mode": { "type": "string" }, "language": { "type": "string" }, "reply_text": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "message_id": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cpr_01j9r6e8g0k2m4p6r8t0v2w4x", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "account_id": "cha_…", "automation_id": "cau_…", "platform": "INSTAGRAM", "comment_id": "17891…", "post_external_id": "17902…", "post_id": "spo_…", "social_comment_id": null, "parent_comment_id": null, "commenter_id": "54321…", "commenter": "@dilnoza.uz", "comment_text": "Narxi qancha?", "comment_created_at": "2026-09-28T00:00:00Z", "source": "WEBHOOK", "status": "SENT", "skip_reason": null, "trigger": "JEV_PURCHASE_INTEREST", "matched_keyword": null, "jev_probability": 0.91, "reply_mode": "TEMPLATE", "language": "uz", "reply_text": "Rahmat! Narx …", "execution_id": null, "recipient_id": "54321…", "message_id": "…", "error_code": null, "error": null, "attempts": 1, "due_at": null, "sent_at": "2026-09-28T00:01:00Z", "created_at": "2026-09-28T00:00:30Z", "updated_at": "2026-09-28T00:01:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}/marketing-topics": { "get": { "operationId": "getChannelsAccountsByIdMarketingTopics", "summary": "A Facebook Page's marketing-message topics: who opted in, who is eligible right now (outside Meta's frequency limits), who stopped or whose token expired", "description": "A Facebook Page's marketing-message topics: who opted in, who is eligible right now (outside Meta's frequency limits), who stopped or whose token expired. Instagram has no marketing messages.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "active": { "type": "integer" }, "eligible": { "type": "integer" }, "stopped": { "type": "integer" }, "expired": { "type": "integer" }, "last_opt_in_at": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "topic": "Weekly deals", "active": 12, "eligible": 9, "stopped": 2, "expired": 1, "last_opt_in_at": "…" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/accounts/{id}/marketing-subscriptions": { "get": { "operationId": "getChannelsAccountsByIdMarketingSubscriptions", "summary": "The people who opted in to a Page's marketing messages", "description": "The people who opted in to a Page's marketing messages. ?topic= and ?status= (ACTIVE, STOPPED, EXPIRED) filter. Tokens are never returned.\n\nNeeds `accounts:read`, which API keys have.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "accounts:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } }, { "name": "topic", "in": "query", "required": false, "description": "Filter by topic.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "topic": { "type": "string" }, "status": { "type": "string" }, "token_status": { "type": "string" }, "timezone": { "type": "string" }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_eligible_at": { "type": "string", "format": "date-time" }, "last_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "opted_in_at": { "type": "string", "format": "date-time" }, "stopped_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "mms_01j9r6f9h1k3m5p7r9t1v3w5x", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "account_id": "cha_…", "conversation_id": "cnv_…", "recipient_id": "psid-12345", "topic": "Weekly deals", "status": "ACTIVE", "token_status": "NOTIFICATION_MESSAGES_TOKEN", "timezone": "Asia/Tashkent", "token_expires_at": null, "next_eligible_at": "2026-09-29T00:00:00Z", "last_sent_at": null, "opted_in_at": "2026-09-28T00:00:00Z", "stopped_at": null, "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T00:00:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/meta/webhook": { "get": { "operationId": "getChannelsMetaWebhook", "summary": "Meta's subscription handshake: with hub.mode subscribe and the platform's hub.verify_token, the answer is hub.challenge as plain text; otherwise 403", "description": "Meta's subscription handshake: with hub.mode subscribe and the platform's hub.verify_token, the answer is hub.challenge as plain text; otherwise 403.\n\nNo authentication.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "hub.mode", "in": "query", "required": false, "description": "Filter by hub.mode.", "schema": { "type": "string" } }, { "name": "hub.verify_token", "in": "query", "required": false, "description": "Filter by hub.verify token.", "schema": { "type": "string" } }, { "name": "hub.challenge", "in": "query", "required": false, "description": "Filter by hub.challenge.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file, with its original Content-Type.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postChannelsMetaWebhook", "summary": "Meta's notifications for Instagram (object instagram) and Pages (object page), signed with X-Hub-Signature-256 (401 signature_missing, signature_invalid)", "description": "Meta's notifications for Instagram (object instagram) and Pages (object page), signed with X-Hub-Signature-256 (401 signature_missing, signature_invalid). Each item (a message, an echo, a reaction, a read, an unsend, an edit) is stored once, deduplicated by its kind and mid, and processed by a worker; the answer comes at once. Items for accounts no organization has live are ignored.\n\nNo authentication.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "Public", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string" }, "entry": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "integer" }, "messaging": { "type": "array", "items": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "id": { "type": "string" } } }, "recipient": { "type": "object", "properties": { "id": { "type": "string" } } }, "timestamp": { "type": "integer" }, "message": { "type": [ "object", "null" ], "properties": { "mid": { "type": "string" }, "text": { "type": "string" } } } } } } } } } } }, "example": { "object": "instagram", "entry": [ { "id": "17841400000000001", "time": 1790000000000, "messaging": [ { "sender": { "id": "1784120000000042" }, "recipient": { "id": "17841400000000001" }, "timestamp": 1790000000000, "message": { "mid": "aWdfZAG1…", "text": "Salom! Narxi qancha?" } } ] } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "ignored": { "type": "integer" } } }, "example": { "accepted": 1, "duplicates": 0, "ignored": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/meta/deauthorize": { "post": { "operationId": "postChannelsMetaDeauthorize", "summary": "Meta's deauthorize callback (form field signed_request, signed with the Meta or Instagram app's secret; 400 invalid_signed_request otherwise): every account the person connected loses its tokens and becomes DISCONNECTED, in every organization", "description": "Meta's deauthorize callback (form field signed_request, signed with the Meta or Instagram app's secret; 400 invalid_signed_request otherwise): every account the person connected loses its tokens and becomes DISCONNECTED, in every organization.\n\nNo authentication.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "Public", "security": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "signed_request": { "type": "string" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST https://app.example.com/api/v1/channels/meta/deauthorize \\\n -F signed_request=." } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "accounts": { "type": "integer" } } }, "example": { "success": true, "accounts": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/meta/data-deletion": { "post": { "operationId": "postChannelsMetaDataDeletion", "summary": "Meta's data-deletion callback (signed_request as above): the person's accounts lose their tokens and profile and become DISCONNECTED, and their conversations and messages are deleted", "description": "Meta's data-deletion callback (signed_request as above): the person's accounts lose their tokens and profile and become DISCONNECTED, and their conversations and messages are deleted. The answer is the status URL and the confirmation code Meta shows the person.\n\nNo authentication.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "Public", "security": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "signed_request": { "type": "string" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST https://app.example.com/api/v1/channels/meta/data-deletion \\\n -F signed_request=." } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "confirmation_code": { "type": "string" } } }, "example": { "url": "https://app.example.com/api/v1/channels/meta/data-deletion/8f14e45fceea167a5a36dedd", "confirmation_code": "8f14e45fceea167a5a36dedd" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/meta/data-deletion/{code}": { "get": { "operationId": "getChannelsMetaDataDeletionByCode", "summary": "The status of a data-deletion request (RECEIVED or COMPLETED)", "description": "The status of a data-deletion request (RECEIVED or COMPLETED). 404 for an unknown code.\n\nNo authentication.", "tags": [ "Channels: Instagram and Facebook" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "The code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation_code": { "type": "string" }, "status": { "type": "string" }, "requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "confirmation_code": "8f14e45fceea167a5a36dedd", "status": "COMPLETED", "requested_at": "2026-09-26T09:30:00Z", "completed_at": "2026-09-26T09:30:00Z" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxies": { "get": { "operationId": "getProxies", "summary": "Your proxies with their last health check", "description": "Your proxies with their last health check.\n\nNeeds `proxies:read`, which API keys have.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "ACTIVE", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postProxies", "summary": "Add a SOCKS5 or HTTP (CONNECT) proxy with an optional username and password, or an MTProto proxy with its secret", "description": "Add a SOCKS5 or HTTP (CONNECT) proxy with an optional username and password, or an MTProto proxy with its secret. Credentials are encrypted at rest and never returned. An address (protocol, host and port) a platform administrator disabled can't be added again: 409 proxy_disabled.\n\nNeeds `proxies:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "password": { "type": "string" } } }, "example": { "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "password": "…" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] } } }, "example": { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "ACTIVE", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": null, "assigned_account_name": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxies/import": { "post": { "operationId": "postProxiesImport", "summary": "Add up to 1,000 proxies at once from text in a JSON body, or from a file in a multipart field named file (2 MB at most)", "description": "Add up to 1,000 proxies at once from text in a JSON body, or from a file in a multipart field named file (2 MB at most). Oqim reads one proxy per line (socks5://user:pass@host:port, host:port, host:port:user:pass or a tg://proxy link), a CSV with a header row, or a JSON list. Lines without a scheme use default_protocol, SOCKS5 or HTTP. Send dry_run=true first for the report; the real import answers 201 and checks each new proxy right away. Proxies you already have are skipped, and an address a platform administrator disabled is reported INVALID.\n\nNeeds `proxies:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "default_protocol": { "type": "string" }, "name_prefix": { "type": "string" }, "dry_run": { "type": "boolean" } } }, "example": { "text": "socks5://oqim:…@proxy.silkroad.example:1080\nhttp://203.0.113.40:8080\n203.0.113.41:1080:office:…", "default_protocol": "SOCKS5", "name_prefix": "Office", "dry_run": true } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "A TXT, CSV or JSON export, 2 MB at most." }, "text": { "type": "string" }, "dry_run": { "type": "boolean" }, "default_protocol": { "type": "string", "enum": [ "SOCKS5", "HTTP" ] }, "name_prefix": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "total": { "type": "integer" }, "ready": { "type": "integer" }, "duplicates": { "type": "integer" }, "invalid": { "type": "integer" }, "created": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer" }, "raw": { "type": "string" }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "has_auth": { "type": "boolean" }, "status": { "type": "string" }, "message": { "type": [ "string", "null" ] } } } } } }, "example": { "dry_run": true, "total": 3, "ready": 2, "duplicates": 1, "invalid": 0, "created": 0, "items": [ { "line": 1, "raw": "socks5://oqim:…@proxy.silkroad.example:1080", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "has_auth": true, "status": "DUPLICATE", "message": "Already in your proxies." }, { "line": 2, "raw": "http://203.0.113.40:8080", "protocol": "HTTP", "host": "203.0.113.40", "port": 8080, "has_auth": false, "status": "READY" }, { "line": 3, "raw": "203.0.113.41:1080:office:…", "protocol": "SOCKS5", "host": "203.0.113.41", "port": 1080, "has_auth": true, "status": "READY" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxies/bulk": { "post": { "operationId": "postProxiesBulk", "summary": "Act on many proxies at once, chosen by proxy_ids (up to 5,000), by status such as UNREACHABLE, or both", "description": "Act on many proxies at once, chosen by proxy_ids (up to 5,000), by status such as UNREACHABLE, or both. action \"check\" queues a health check for each and answers 202 with queued; \"delete\" removes them, detaching any account that used one, and answers 200 with deleted; proxies a platform administrator disabled stay, counted in kept_disabled.\n\nNeeds `proxies:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string" }, "status": { "type": "string" } } }, "example": { "action": "check", "status": "UNREACHABLE" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "integer" } } }, "example": { "queued": 4 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxies/{id}": { "get": { "operationId": "getProxiesById", "summary": "One proxy", "description": "One proxy.\n\nNeeds `proxies:read`, which API keys have.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] } } }, "example": { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "ACTIVE", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchProxiesById", "summary": "Change a proxy", "description": "Change a proxy. Omit password to keep the stored one. A proxy a platform administrator disabled (status DISABLED, with disabled_reason) can't be changed, and no proxy can be moved to its address: 409 proxy_disabled.\n\nNeeds `proxies:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "port": { "type": "integer" } } }, "example": { "name": "Tashkent office (backup line)", "port": 1081 } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] } } }, "example": { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office (backup line)", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1081, "username": "oqim", "status": "ACTIVE", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteProxiesById", "summary": "Delete a proxy", "description": "Delete a proxy. An account using it is detached and connects directly. A proxy a platform administrator disabled stays until they enable it: 409 proxy_disabled.\n\nNeeds `proxies:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxies/{id}/check": { "post": { "operationId": "postProxiesByIdCheck", "summary": "Dial a Telegram data centre through the proxy now; updates status and latency_ms", "description": "Dial a Telegram data centre through the proxy now; updates status and latency_ms. A disabled proxy isn't checked: 409 proxy_disabled.\n\nNeeds `proxies:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] } } }, "example": { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "ACTIVE", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/proxies/{id}/checks": { "get": { "operationId": "getProxiesByIdChecks", "summary": "Recent health checks, newest first", "description": "Recent health checks, newest first.\n\nNeeds `proxies:read`, which API keys have.", "tags": [ "Proxies" ], "x-oqim-permission": "proxies:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "proxy_id": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "checked_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": 5521, "proxy_id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "status": "ACTIVE", "latency_ms": 84, "error": null, "checked_at": "2026-09-26T09:30:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/recipients": { "get": { "operationId": "getRecipients", "summary": "Search and filter recipients", "description": "Search and filter recipients.\n\nNeeds `recipients:read`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "consent", "in": "query", "required": false, "description": "Filter by consent.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Filter by tag.", "schema": { "type": "string" } }, { "name": "list_id", "in": "query", "required": false, "description": "Filter by list ID.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "Filter by source.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "consent_status": { "type": "string" }, "consent_timestamp": { "type": "string", "format": "date-time" }, "consent_note": { "type": "string" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "opt_out_source": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "string" } }, "imported_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "opt_out_status": { "type": "boolean" }, "list_ids": { "type": "array", "items": { "type": "string" } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "language": "uz", "source": "CSV", "consent_status": "OPTED_IN", "consent_timestamp": "2026-08-14T11:20:00Z", "consent_note": "Registered for Tashkent Expo 2026 on expo.example", "opted_out_at": null, "opt_out_source": null, "attributes": { "event_date": "1 October", "location": "Tashkent City Hall" }, "tags": [ "expo-2026", "vip" ], "imported_at": "2026-09-05T09:00:00Z", "created_at": "2026-09-05T09:00:00Z", "updated_at": "2026-09-05T09:00:00Z", "opt_out_status": false, "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ] } ], "total": 4210, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postRecipients", "summary": "Add one recipient", "description": "Add one recipient. telegram_id or username is required; everything else is optional. A Telegram ID or username that already exists is 409 recipient_exists.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "consent_status": { "type": "string" }, "consent_note": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } }, "list_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "consent_status": "OPTED_IN", "consent_note": "Registered for Tashkent Expo 2026 on expo.example", "tags": [ "expo-2026", "vip" ], "attributes": { "event_date": "1 October", "location": "Tashkent City Hall" }, "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "consent_status": { "type": "string" }, "consent_timestamp": { "type": "string", "format": "date-time" }, "consent_note": { "type": "string" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "opt_out_source": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "string" } }, "imported_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "opt_out_status": { "type": "boolean" }, "list_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "language": "uz", "source": "API", "consent_status": "OPTED_IN", "consent_timestamp": "2026-08-14T11:20:00Z", "consent_note": "Registered for Tashkent Expo 2026 on expo.example", "opted_out_at": null, "opt_out_source": null, "attributes": { "event_date": "1 October", "location": "Tashkent City Hall" }, "tags": [ "expo-2026", "vip" ], "imported_at": "2026-09-05T09:00:00Z", "created_at": "2026-09-05T09:00:00Z", "updated_at": "2026-09-05T09:00:00Z", "opt_out_status": false, "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/recipients/import": { "post": { "operationId": "postRecipientsImport", "summary": "Import a CSV or JSON file (multipart), or a JSON body with records", "description": "Import a CSV or JSON file (multipart), or a JSON body with records. Send dry_run=true first for the report without saving anything, then the same data with dry_run=false. Up to 10 MB and 100,000 rows.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "dry_run": { "type": "boolean" }, "default_consent": { "type": "string" }, "list_id": { "type": "string" } } } }, "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object" }, "description": "Recipients, with the same fields as a CSV row." }, "dry_run": { "type": "boolean" }, "default_consent": { "type": "string" }, "list_id": { "type": "string" }, "new_list_name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" } }, "required": [ "records" ] }, "example": { "records": [ { "telegram_id": 123456789, "first_name": "Aziza", "consent_status": "OPTED_IN", "location": "Tashkent City Hall" } ], "dry_run": true, "default_consent": "UNKNOWN" } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl https://app.example.com/api/v1/recipients/import \\\n -H \"Authorization: Bearer $OQIM_API_KEY\" \\\n -F file=@expo-attendees.csv \\\n -F dry_run=true \\\n -F default_consent=UNKNOWN \\\n -F list_id=lst_01j9r5e2g4j6m8p0r2t4w6y8a0" } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "total": { "type": "integer" }, "valid": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "duplicates": { "type": "integer" }, "invalid": { "type": "integer" }, "suppressed": { "type": "integer" }, "opted_out": { "type": "integer" }, "by_consent": { "type": "object", "properties": { "OPTED_IN": { "type": "integer" }, "AUTHORIZED": { "type": "integer" }, "EXISTING_RELATIONSHIP": { "type": "integer" }, "UNKNOWN": { "type": "integer" } } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "field": { "type": "string" }, "value": { "type": "string" }, "kind": { "type": "string" }, "message": { "type": [ "string", "null" ] } } } }, "columns": { "type": "array", "items": { "type": "string" } }, "sample": { "type": "array", "items": { "type": "object", "properties": { "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "consent_status": { "type": "string" } } } } } }, "example": { "dry_run": true, "total": 1950, "valid": 1923, "created": 0, "updated": 0, "duplicates": 12, "invalid": 9, "suppressed": 6, "opted_out": 0, "by_consent": { "OPTED_IN": 1402, "AUTHORIZED": 0, "EXISTING_RELATIONSHIP": 496, "UNKNOWN": 25 }, "issues": [ { "row": 14, "field": "telegram_id", "value": "12ab", "kind": "INVALID", "message": "Telegram IDs are positive whole numbers." }, { "row": 88, "field": "telegram_id", "value": "987654321", "kind": "DUPLICATE", "message": "Same Telegram ID as row 31; skipped." }, { "row": 402, "kind": "SUPPRESSED", "message": "On the suppression list, so imported as opted out." }, { "row": 977, "kind": "UNKNOWN_CONSENT", "message": "Consent is unknown, so campaigns skip this recipient unless platform policy allows it." } ], "columns": [ "telegram_id", "username", "first_name", "last_name", "consent_status", "event_date", "location" ], "sample": [ { "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "consent_status": "OPTED_IN" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/recipients/bulk": { "post": { "operationId": "postRecipientsBulk", "summary": "Apply one action to up to 5,000 recipients: tag, untag, add_to_list, remove_from_list, set_consent, opt_out or delete", "description": "Apply one action to up to 5,000 recipients: tag, untag, add_to_list, remove_from_list, set_consent, opt_out or delete. set_consent can't opt anyone out; use opt_out. in_flight counts recipients skipped because a message to them was being sent.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string" }, "recipient_ids": { "type": "array", "items": { "type": "string" } }, "list_id": { "type": "string" } } }, "example": { "action": "add_to_list", "recipient_ids": [ "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "rcp_01j9s3d5f7h9k1m3p5r7t9v1x3" ], "list_id": "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string" }, "requested": { "type": "integer" }, "matched": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" }, "in_flight": { "type": "integer" } } }, "example": { "action": "add_to_list", "requested": 2, "matched": 2, "updated": 2, "skipped": 0, "in_flight": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/recipients/tags": { "get": { "operationId": "getRecipientsTags", "summary": "Every tag in use with its recipient count", "description": "Every tag in use with its recipient count.\n\nNeeds `recipients:read`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "tag": { "type": "string" }, "count": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "tag": "expo-2026", "count": 1902 }, { "tag": "vip", "count": 64 } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/recipients/{id}": { "get": { "operationId": "getRecipientsById", "summary": "One recipient, with the lists it belongs to", "description": "One recipient, with the lists it belongs to.\n\nNeeds `recipients:read`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipient ID (rcp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "consent_status": { "type": "string" }, "consent_timestamp": { "type": "string", "format": "date-time" }, "consent_note": { "type": "string" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "opt_out_source": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "string" } }, "imported_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "opt_out_status": { "type": "boolean" }, "list_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "language": "uz", "source": "CSV", "consent_status": "OPTED_IN", "consent_timestamp": "2026-08-14T11:20:00Z", "consent_note": "Registered for Tashkent Expo 2026 on expo.example", "opted_out_at": null, "opt_out_source": null, "attributes": { "event_date": "1 October", "location": "Tashkent City Hall" }, "tags": [ "expo-2026", "vip" ], "imported_at": "2026-09-05T09:00:00Z", "created_at": "2026-09-05T09:00:00Z", "updated_at": "2026-09-05T09:00:00Z", "opt_out_status": false, "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchRecipientsById", "summary": "Update a recipient", "description": "Update a recipient. An opted-out recipient's consent can't be changed (409 recipient_opted_out).\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipient ID (rcp_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } } } }, "example": { "tags": [ "expo-2026", "vip", "speaker" ], "attributes": { "event_date": "1 October", "location": "Hall B" } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "consent_status": { "type": "string" }, "consent_timestamp": { "type": "string", "format": "date-time" }, "consent_note": { "type": "string" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "opt_out_source": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "string" } }, "imported_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "opt_out_status": { "type": "boolean" }, "list_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "language": "uz", "source": "CSV", "consent_status": "OPTED_IN", "consent_timestamp": "2026-08-14T11:20:00Z", "consent_note": "Registered for Tashkent Expo 2026 on expo.example", "opted_out_at": null, "opt_out_source": null, "attributes": { "event_date": "1 October", "location": "Tashkent City Hall" }, "tags": [ "expo-2026", "vip", "speaker" ], "imported_at": "2026-09-05T09:00:00Z", "created_at": "2026-09-05T09:00:00Z", "updated_at": "2026-09-05T09:00:00Z", "opt_out_status": false, "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteRecipientsById", "summary": "Delete a recipient", "description": "Delete a recipient. If they opted out, their suppression entry stays, so they're never messaged again. 409 recipient_busy while a message to them is being sent.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipient ID (rcp_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/recipients/{id}/opt-out": { "post": { "operationId": "postRecipientsByIdOptOut", "summary": "Record an opt-out the person made outside Oqim", "description": "Record an opt-out the person made outside Oqim. Permanent and organization-wide: adds them to the suppression list, skips their pending sends and emits recipient.opted_out.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Recipient ID (rcp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "consent_status": { "type": "string" }, "consent_timestamp": { "type": "string", "format": "date-time" }, "consent_note": { "type": "string" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "opt_out_source": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "string" } }, "imported_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "opt_out_status": { "type": "boolean" }, "list_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "language": "uz", "source": "CSV", "consent_status": "OPTED_OUT", "consent_timestamp": "2026-08-14T11:20:00Z", "consent_note": "Registered for Tashkent Expo 2026 on expo.example", "opted_out_at": "2026-09-26T09:30:00Z", "opt_out_source": "MANUAL", "attributes": { "event_date": "1 October", "location": "Tashkent City Hall" }, "tags": [ "expo-2026", "vip" ], "imported_at": "2026-09-05T09:00:00Z", "created_at": "2026-09-05T09:00:00Z", "updated_at": "2026-09-05T09:00:00Z", "opt_out_status": true, "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/recipient-imports": { "get": { "operationId": "getRecipientImports", "summary": "Past imports and their counts", "description": "Past imports and their counts.\n\nNeeds `recipients:read`, which API keys have.", "tags": [ "Recipients" ], "x-oqim-permission": "recipients:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "filename": { "type": "string" }, "list_id": { "type": "string" }, "total": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "duplicates": { "type": "integer" }, "invalid": { "type": "integer" }, "suppressed": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "imp_01j9rh3k5m7p9s1t3v5x7z9b1d", "source": "CSV", "filename": "expo-attendees.csv", "list_id": "lst_01j9r5e2g4j6m8p0r2t4w6y8a0", "total": 1950, "created": 1901, "updated": 22, "duplicates": 12, "invalid": 9, "suppressed": 6, "created_at": "2026-09-05T09:00:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/lists": { "get": { "operationId": "getLists", "summary": "Lists with member and sendable counts", "description": "Lists with member and sendable counts.\n\nNeeds `recipients:read`, which API keys have.", "tags": [ "Lists" ], "x-oqim-permission": "recipients:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "member_count": { "type": "integer" }, "sendable_count": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "lst_01j9r5e2g4j6m8p0r2t4w6y8a0", "name": "Expo 2026 attendees", "description": "Registered through the expo website", "created_at": "2026-09-05T08:55:00Z", "updated_at": "2026-09-05T09:00:00Z", "member_count": 1902, "sendable_count": 1840 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postLists", "summary": "Create a list", "description": "Create a list.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Lists" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": "string" } } }, "example": { "name": "Expo 2026 attendees", "description": "Registered through the expo website" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "member_count": { "type": "integer" }, "sendable_count": { "type": "integer" } } }, "example": { "id": "lst_01j9r5e2g4j6m8p0r2t4w6y8a0", "name": "Expo 2026 attendees", "description": "Registered through the expo website", "created_at": "2026-09-05T08:55:00Z", "updated_at": "2026-09-05T09:00:00Z", "member_count": 0, "sendable_count": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/lists/{id}": { "get": { "operationId": "getListsById", "summary": "One list", "description": "One list.\n\nNeeds `recipients:read`, which API keys have.", "tags": [ "Lists" ], "x-oqim-permission": "recipients:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID (lst_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "member_count": { "type": "integer" }, "sendable_count": { "type": "integer" } } }, "example": { "id": "lst_01j9r5e2g4j6m8p0r2t4w6y8a0", "name": "Expo 2026 attendees", "description": "Registered through the expo website", "created_at": "2026-09-05T08:55:00Z", "updated_at": "2026-09-05T09:00:00Z", "member_count": 1902, "sendable_count": 1840 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchListsById", "summary": "Rename a list or change its description", "description": "Rename a list or change its description.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Lists" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID (lst_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } } }, "example": { "name": "Expo 2026 attendees (confirmed)" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "member_count": { "type": "integer" }, "sendable_count": { "type": "integer" } } }, "example": { "id": "lst_01j9r5e2g4j6m8p0r2t4w6y8a0", "name": "Expo 2026 attendees (confirmed)", "description": "Registered through the expo website", "created_at": "2026-09-05T08:55:00Z", "updated_at": "2026-09-05T09:00:00Z", "member_count": 1902, "sendable_count": 1840 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteListsById", "summary": "Delete a list", "description": "Delete a list. Its recipients stay.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Lists" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID (lst_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/lists/{id}/members": { "post": { "operationId": "postListsByIdMembers", "summary": "Add recipients to a list", "description": "Add recipients to a list.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Lists" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID (lst_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "recipient_ids": [ "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "requested": { "type": "integer" }, "added": { "type": "integer" } } }, "example": { "requested": 1, "added": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteListsByIdMembers", "summary": "Remove recipients from a list (they stay in your recipients)", "description": "Remove recipients from a list (they stay in your recipients).\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Lists" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List ID (lst_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "recipient_ids": [ "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "requested": { "type": "integer" }, "removed": { "type": "integer" } } }, "example": { "requested": 1, "removed": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/suppressions": { "get": { "operationId": "getSuppressions", "summary": "Suppressed IDs and usernames", "description": "Suppressed IDs and usernames.\n\nNeeds `recipients:read`, which API keys have.", "tags": [ "Suppression list" ], "x-oqim-permission": "recipients:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "source": { "type": "string" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "sup_01j9rg0j2m4p6r8t0w2y4a6c8e", "telegram_id": 443210987, "username": null, "reason": "Asked by email to stop", "source": "MANUAL", "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-12T14:03:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postSuppressions", "summary": "Suppress a Telegram ID or username, for example after a request by email", "description": "Suppress a Telegram ID or username, for example after a request by email. Existing recipients who match are opted out at once, and future imports of them arrive opted out.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Suppression list" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "telegram_id": { "type": "integer" }, "reason": { "type": "string" } } }, "example": { "telegram_id": 443210987, "reason": "Asked by email to stop" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "suppression": { "type": "object", "properties": { "id": { "type": "string" }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "source": { "type": "string" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "recipients_opted_out": { "type": "integer" } } }, "example": { "suppression": { "id": "sup_01j9rg0j2m4p6r8t0w2y4a6c8e", "telegram_id": 443210987, "username": null, "reason": "Asked by email to stop", "source": "MANUAL", "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-12T14:03:00Z" }, "recipients_opted_out": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/suppressions/{id}": { "delete": { "operationId": "deleteSuppressionsById", "summary": "Remove a suppression entry", "description": "Remove a suppression entry. This never restores consent: recipients who opted out stay opted out.\n\nNeeds `recipients:manage`, which API keys have.", "tags": [ "Suppression list" ], "x-oqim-permission": "recipients:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suppression ID (sup_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/templates": { "get": { "operationId": "getTemplates", "summary": "Saved message templates", "description": "Saved message templates.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Templates and attachments" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "parse_mode": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "tpl_01j9re4g6j8m0p2r4t6w8y0a2c", "name": "Event reminder", "body": "Hi {{first_name|there}}! {{event_date}} at {{location}}.\n\nStop these messages: {{opt_out_url}}", "parse_mode": "MARKDOWN", "created_at": "2026-09-10T11:00:00Z", "updated_at": "2026-09-10T11:00:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postTemplates", "summary": "Save a template", "description": "Save a template. parse_mode is MARKDOWN, HTML or PLAIN.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Templates and attachments" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "parse_mode": { "type": "string" } } }, "example": { "name": "Event reminder", "body": "Hi {{first_name|there}}! {{event_date}} at {{location}}.\n\nStop these messages: {{opt_out_url}}", "parse_mode": "MARKDOWN" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "parse_mode": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "tpl_01j9re4g6j8m0p2r4t6w8y0a2c", "name": "Event reminder", "body": "Hi {{first_name|there}}! {{event_date}} at {{location}}.\n\nStop these messages: {{opt_out_url}}", "parse_mode": "MARKDOWN", "created_at": "2026-09-10T11:00:00Z", "updated_at": "2026-09-10T11:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/templates/{id}": { "patch": { "operationId": "patchTemplatesById", "summary": "Change a template", "description": "Change a template. Campaigns already launched keep the text they were launched with.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Templates and attachments" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template ID (tpl_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } } }, "example": { "name": "Event reminder (short)" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "parse_mode": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "tpl_01j9re4g6j8m0p2r4t6w8y0a2c", "name": "Event reminder (short)", "body": "Hi {{first_name|there}}! {{event_date}} at {{location}}.\n\nStop these messages: {{opt_out_url}}", "parse_mode": "MARKDOWN", "created_at": "2026-09-10T11:00:00Z", "updated_at": "2026-09-10T11:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteTemplatesById", "summary": "Delete a template", "description": "Delete a template.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Templates and attachments" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Template ID (tpl_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/attachments": { "post": { "operationId": "postAttachments", "summary": "Upload a file to attach to a campaign, in a multipart field named file", "description": "Upload a file to attach to a campaign, in a multipart field named file. JPEG, PNG and WebP images become photos (up to 10 MB), video/* becomes a video, anything else a document; 20 MB at most.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Templates and attachments" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl https://app.example.com/api/v1/attachments \\\n -H \"Authorization: Bearer $OQIM_API_KEY\" \\\n -F file=@expo-floor-plan.png" } ], "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "sha256": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "att_01j9rf7h9k1m3p5r7t9v1x3z5b", "kind": "PHOTO", "filename": "expo-floor-plan.png", "content_type": "image/png", "size_bytes": 482113, "sha256": "9f2c4e1a7b3d5f60c8e2a4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6", "created_at": "2026-09-28T10:02:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/attachments/{id}/content": { "get": { "operationId": "getAttachmentsByIdContent", "summary": "Download an attachment's file, with its original Content-Type", "description": "Download an attachment's file, with its original Content-Type.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Templates and attachments" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Attachment ID (att_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file, with its original Content-Type.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/messages/preview": { "post": { "operationId": "postMessagesPreview", "summary": "Render a message body for one recipient (by default your most recent sendable one): the Telegram HTML, the plain text and its length, the limit, and variables left without a value", "description": "Render a message body for one recipient (by default your most recent sendable one): the Telegram HTML, the plain text and its length, the limit, and variables left without a value.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Templates and attachments" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" }, "parse_mode": { "type": "string" }, "recipient_id": { "type": "string" } } }, "example": { "body": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string" }, "text": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "missing_variables": { "type": "array", "items": {} }, "length": { "type": "integer" }, "limit": { "type": "integer" }, "over_limit": { "type": "boolean" }, "sample_recipient": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "consent_status": { "type": "string" } } } } }, "example": { "html": "Hi Aziza! Tashkent Expo opens tomorrow at 10:00 in Tashkent City Hall.\n\nNo longer want these messages? https://app.example.com/u/b3JnXzAxajlyMm02azRufHJjcF8wMWo5cjVi.q8Zr0mX2pLk5Vd7nWc3TyA", "text": "Hi Aziza! Tashkent Expo opens tomorrow at 10:00 in Tashkent City Hall.\n\nNo longer want these messages? https://app.example.com/u/b3JnXzAxajlyMm02azRufHJjcF8wMWo5cjVi.q8Zr0mX2pLk5Vd7nWc3TyA", "variables": [ "first_name", "location", "opt_out_url" ], "missing_variables": [], "length": 188, "limit": 4096, "over_limit": false, "sample_recipient": { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "first_name": "Aziza", "last_name": "Karimova", "username": "aziza_k", "consent_status": "OPTED_IN" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns": { "get": { "operationId": "getCampaigns", "summary": "Campaigns, newest first", "description": "Campaigns, newest first. status accepts several values separated by commas. A repeating campaign has recurrence and next_run_at; its runs have series_id and occurrence.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "RUNNING", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } ], "total": 18, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postCampaigns", "summary": "Create a draft", "description": "Create a draft. Everything except name can be filled in later. Set recurrence to repeat it; see Scheduling.\n\nrecurrence: frequency (DAILY, WEEKLY or MONTHLY), interval (every N days up to 60, weeks or months up to 12; default 1), weekdays (WEEKLY: MON to SUN, all sending days), month_day (MONTHLY: 1 to 31; shorter months use their last day) and ends: type NEVER, AFTER with count (2 to 365 runs, the first included) or ON with until (a date in the campaign's time zone, at most 2 years ahead). null means it runs once. Errors come back per field, like recurrence.weekdays.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } } } }, "example": { "name": "Expo reminder, day before", "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": { "frequency": "WEEKLY", "interval": 1, "weekdays": [ "MON", "THU" ], "ends": { "type": "AFTER", "count": 8 } } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "DRAFT", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": { "frequency": "WEEKLY", "interval": 1, "weekdays": [ "MON", "THU" ], "ends": { "type": "AFTER", "count": 8 } }, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": "2026-10-01T05:00:00Z", "total_recipients": 0, "delivered_count": 0, "failed_count": 0, "unavailable_count": 0, "skipped_count": 0, "pending_count": 0, "in_flight_count": 0, "launched_by": null, "launched_at": null, "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}": { "get": { "operationId": "getCampaignsById", "summary": "One campaign with its counters", "description": "One campaign with its counters. A run of a repeating campaign also has series: runs launched so far, total_runs when the series ends after a count, whether it's still repeating, the rule, when the next run starts (next_run_at, next_run_id) and its neighbours (previous_id, next_id).\n\nnext_run_at on the campaign itself is when the run after it would start, projected from the rule; null when it doesn't repeat. auto_launch_at is set on a run Oqim added: it launches by itself then, 15 minutes before its start.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "series": { "type": "object", "properties": { "id": { "type": "string" }, "runs": { "type": "integer" }, "total_runs": { "type": [ "integer", "null" ] }, "repeating": { "type": "boolean" }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_id": { "type": "string" }, "previous_id": { "type": "string" }, "next_id": { "type": [ "string", "null" ] } } } } }, "example": { "id": "cmp_01j9s6g8j0m2p4r6t8w0y2a4c6", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo weekly digest · run 2", "description": "", "status": "SCHEDULED", "status_reason": null, "message_text": "Hi {{first_name|there}}! This week at Tashkent Expo: {{highlights}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-10-01T05:00:00Z", "end_at": "2026-10-01T13:00:00Z", "window_start": 600, "window_end": 1080, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": { "frequency": "WEEKLY", "interval": 1, "weekdays": [ "MON", "THU" ], "ends": { "type": "AFTER", "count": 8 } }, "series_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "occurrence": 2, "auto_launch_at": null, "next_run_at": "2026-10-05T05:00:00Z", "total_recipients": 1840, "delivered_count": 0, "failed_count": 0, "unavailable_count": 0, "skipped_count": 0, "pending_count": 1840, "in_flight_count": 0, "launched_by": "system", "launched_at": "2026-10-01T04:45:01Z", "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T13:00:04Z", "updated_at": "2026-10-01T04:45:01Z", "series": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "runs": 2, "total_runs": 8, "repeating": true, "recurrence": { "frequency": "WEEKLY", "interval": 1, "weekdays": [ "MON", "THU" ], "ends": { "type": "AFTER", "count": 8 } }, "next_run_at": "2026-10-01T05:00:00Z", "next_run_id": "cmp_01j9s6g8j0m2p4r6t8w0y2a4c6", "previous_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "next_id": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchCampaignsById", "summary": "Change a campaign", "description": "Change a campaign. Drafts accept every field; scheduled and paused campaigns only name, description, end_at, the window and account_ids; running ones only name and description. A locked field is 409 field_locked; a finished campaign is 409 campaign_locked.\n\nrecurrence changes only while the campaign is a draft; stop a launched series with stop-repeating. Moving the start_at of a run Oqim added moves its auto_launch_at with it.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "end_at": { "type": "string", "format": "date-time" }, "account_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "end_at": "2026-09-30T16:00:00Z", "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "acc_01j9s4e6g8j0m2p4r6t8w0y2a4" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "RUNNING", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T16:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteCampaignsById", "summary": "Delete a draft", "description": "Delete a draft. Launched campaigns can't be deleted (409 campaign_not_draft); cancel them instead. Deleting the next run of a repeating campaign ends its series.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/preview": { "post": { "operationId": "postCampaignsByIdPreview", "summary": "Render the campaign's message for a recipient (by default your most recent sendable one)", "description": "Render the campaign's message for a recipient (by default your most recent sendable one).\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient_id": { "type": "string" } } }, "example": { "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": "string" }, "text": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "missing_variables": { "type": "array", "items": {} }, "length": { "type": "integer" }, "limit": { "type": "integer" }, "over_limit": { "type": "boolean" }, "sample_recipient": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "consent_status": { "type": "string" } } } } }, "example": { "html": "Hi Aziza! Tashkent Expo opens tomorrow at 10:00 in Tashkent City Hall.\n\nNo longer want these messages? https://app.example.com/u/b3JnXzAxajlyMm02azRufHJjcF8wMWo5cjVi.q8Zr0mX2pLk5Vd7nWc3TyA", "text": "Hi Aziza! Tashkent Expo opens tomorrow at 10:00 in Tashkent City Hall.\n\nNo longer want these messages? https://app.example.com/u/b3JnXzAxajlyMm02azRufHJjcF8wMWo5cjVi.q8Zr0mX2pLk5Vd7nWc3TyA", "variables": [ "first_name", "location", "opt_out_url" ], "missing_variables": [], "length": 188, "limit": 4096, "over_limit": false, "sample_recipient": { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "first_name": "Aziza", "last_name": "Karimova", "username": "aziza_k", "consent_status": "OPTED_IN" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/validate": { "post": { "operationId": "postCampaignsByIdValidate", "summary": "Run the pre-launch checks without launching", "description": "Run the pre-launch checks without launching. Also saved on the campaign as validation.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "estimated_hours": { "type": "number" }, "audience": { "type": "object", "properties": { "matched": { "type": "integer" }, "sendable": { "type": "integer" }, "opted_out": { "type": "integer" }, "suppressed": { "type": "integer" }, "unknown_consent": { "type": "integer" }, "missing_variables": { "type": "integer" } } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "message": { "type": [ "string", "null" ] } } } } } }, "example": { "ok": false, "checked_at": "2026-09-29T14:01:58Z", "estimated_hours": 6.2, "audience": { "matched": 1902, "sendable": 1840, "opted_out": 31, "suppressed": 6, "unknown_consent": 25, "missing_variables": 0 }, "checks": [ { "key": "organization_active", "label": "Organization active", "status": "PASS", "message": "The organization is active." }, { "key": "accounts_authorized", "label": "Accounts authorized", "status": "FAIL", "message": "Expo Desk (needs to sign in again) can't send. Remove it from the campaign or fix it first." }, { "key": "unknown_consent", "label": "Unknown consent", "status": "WARN", "message": "25 recipients with unknown consent will be skipped. Record their consent to include them." }, { "key": "opt_out_link", "label": "Opt-out link", "status": "PASS", "message": "Recipients can opt out with the included link." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/start": { "post": { "operationId": "postCampaignsByIdStart", "summary": "Launch a draft: re-run the checks, freeze the message and audience, and move to SCHEDULED", "description": "Launch a draft: re-run the checks, freeze the message and audience, and move to SCHEDULED. A failed check is 422 campaign_invalid with the report in validation; a full plan is 403 plan_limit_reached.\n\nA draft with recurrence needs a start_at and becomes the first run of its series: series_id is its own id and occurrence is 1. Oqim launches the later runs itself through the same checks.\n\nNeeds `campaigns:execute`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:execute", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "SCHEDULED", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 0, "failed_count": 0, "unavailable_count": 0, "skipped_count": 0, "pending_count": 1840, "in_flight_count": 0, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "A pre-launch check failed (campaign_invalid). The report is in validation.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "validation": { "type": "object", "properties": { "ok": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "estimated_hours": { "type": "number" }, "audience": { "type": "object", "properties": { "matched": { "type": "integer" }, "sendable": { "type": "integer" }, "opted_out": { "type": "integer" }, "suppressed": { "type": "integer" }, "unknown_consent": { "type": "integer" }, "missing_variables": { "type": "integer" } } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "message": { "type": [ "string", "null" ] } } } } } } } } ] }, "example": { "error": { "code": "campaign_invalid", "message": "Fix the failed checks before launching." }, "validation": { "ok": false, "checked_at": "2026-09-29T14:01:58Z", "estimated_hours": 6.2, "audience": { "matched": 1902, "sendable": 1840, "opted_out": 31, "suppressed": 6, "unknown_consent": 25, "missing_variables": 0 }, "checks": [ { "key": "organization_active", "label": "Organization active", "status": "PASS", "message": "The organization is active." }, { "key": "accounts_authorized", "label": "Accounts authorized", "status": "FAIL", "message": "Expo Desk (needs to sign in again) can't send. Remove it from the campaign or fix it first." }, { "key": "unknown_consent", "label": "Unknown consent", "status": "WARN", "message": "25 recipients with unknown consent will be skipped. Record their consent to include them." }, { "key": "opt_out_link", "label": "Opt-out link", "status": "PASS", "message": "Recipients can opt out with the included link." } ] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/pause": { "post": { "operationId": "postCampaignsByIdPause", "summary": "Stop dispatching a running or scheduled campaign", "description": "Stop dispatching a running or scheduled campaign. Recipients keep their place. Pausing a paused campaign returns it unchanged.\n\nNeeds `campaigns:execute`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:execute", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "PAUSED", "status_reason": "Paused by dilnoza@silkroad.example", "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": "2026-09-30T08:20:00Z", "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/resume": { "post": { "operationId": "postCampaignsByIdResume", "summary": "Resume a paused campaign: back to RUNNING if it had started, otherwise SCHEDULED", "description": "Resume a paused campaign: back to RUNNING if it had started, otherwise SCHEDULED. Refused (409) when its end time has passed (campaign_ended), none of its accounts can send (no_active_accounts) or a platform administrator paused it (paused_by_admin).\n\nNeeds `campaigns:execute`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:execute", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "RUNNING", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/cancel": { "post": { "operationId": "postCampaignsByIdCancel", "summary": "Stop a draft, scheduled, running or paused campaign for good", "description": "Stop a draft, scheduled, running or paused campaign for good. Recipients not yet sent to are marked cancelled. Cancelling a run of a repeating campaign also stops its series.\n\nNeeds `campaigns:execute`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:execute", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "CANCELLED", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 0, "in_flight_count": 0, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": "2026-09-30T08:25:00Z", "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/stop-repeating": { "post": { "operationId": "postCampaignsByIdStopRepeating", "summary": "Stop a repeating campaign from adding runs", "description": "Stop a repeating campaign from adding runs. Call it on any run of the series; a run in progress finishes normally. The next run waiting to launch by itself is deleted if nobody edited it, and kept as an ordinary draft otherwise; the run you call it on is always kept. Stopping a stopped series changes nothing; a campaign that never repeated is 409 not_repeating.\n\nNeeds `campaigns:execute`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:execute", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "series": { "type": "object", "properties": { "id": { "type": "string" }, "runs": { "type": "integer" }, "total_runs": { "type": [ "integer", "null" ] }, "repeating": { "type": "boolean" }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_id": { "type": "string" }, "previous_id": { "type": "string" }, "next_id": { "type": [ "string", "null" ] } } } } }, "example": { "id": "cmp_01j9s6g8j0m2p4r6t8w0y2a4c6", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo weekly digest · run 2", "description": "", "status": "SCHEDULED", "status_reason": null, "message_text": "Hi {{first_name|there}}! This week at Tashkent Expo: {{highlights}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-10-01T05:00:00Z", "end_at": "2026-10-01T13:00:00Z", "window_start": 600, "window_end": 1080, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "occurrence": 2, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 0, "failed_count": 0, "unavailable_count": 0, "skipped_count": 0, "pending_count": 1840, "in_flight_count": 0, "launched_by": "system", "launched_at": "2026-10-01T04:45:01Z", "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T13:00:04Z", "updated_at": "2026-10-01T04:45:01Z", "series": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "runs": 2, "total_runs": null, "repeating": false, "recurrence": null, "next_run_at": "2026-10-01T05:00:00Z", "next_run_id": "cmp_01j9s6g8j0m2p4r6t8w0y2a4c6", "previous_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "next_id": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/duplicate": { "post": { "operationId": "postCampaignsByIdDuplicate", "summary": "Copy a campaign into a new draft with the same message, audience, accounts and schedule", "description": "Copy a campaign into a new draft with the same message, audience, accounts and schedule. A repeat rule is copied too, as a new series, unless it no longer fits (its end date passed, say).\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cmp_01j9s5f7h9k1m3p5r7t9v1x3z5", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before (copy)", "description": "", "status": "DRAFT", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 0, "delivered_count": 0, "failed_count": 0, "unavailable_count": 0, "skipped_count": 0, "pending_count": 0, "in_flight_count": 0, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": null, "started_at": null, "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/audience-preview": { "get": { "operationId": "getCampaignsByIdAudiencePreview", "summary": "Who an Instagram or Facebook campaign would reach if it sent now, and why the rest wouldn't", "description": "Who an Instagram or Facebook campaign would reach if it sent now, and why the rest wouldn't. Telegram campaigns answer 409: their audience is their recipient list.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "audience": { "type": "string" }, "reachable": { "type": "integer" }, "window_closing_within_1h": { "type": "integer" }, "excluded": { "type": "object", "properties": { "window_closed": { "type": "integer" }, "opted_out": { "type": "integer" }, "personal": { "type": "integer" }, "handed_off": { "type": "integer" }, "ai_off": { "type": "integer" }, "cooling_down": { "type": "integer" }, "stopped": { "type": "integer" }, "expired": { "type": "integer" } } }, "by_language": { "type": "object", "properties": { "uz": { "type": "integer" }, "ru": { "type": "integer" }, "en": { "type": "integer" }, "default": { "type": "integer" } } }, "sendable": { "type": "boolean" }, "sendable_reason": { "type": "string" }, "evaluated_at": { "type": "string", "format": "date-time" } } }, "example": { "campaign_id": "cmp_…", "channel": "INSTAGRAM | FACEBOOK", "account_id": "cha_…", "audience": "OPEN_WINDOW | MARKETING_SUBSCRIBERS", "reachable": 12, "window_closing_within_1h": 3, "excluded": { "window_closed": 4, "opted_out": 1, "personal": 2, "handed_off": 1, "ai_off": 0, "cooling_down": 0, "stopped": 0, "expired": 0 }, "by_language": { "uz": 7, "ru": 3, "en": 2, "default": 0 }, "sendable": true, "sendable_reason": "why not, when sendable is false", "evaluated_at": "2026-09-28T00:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/statistics": { "get": { "operationId": "getCampaignsByIdStatistics", "summary": "Live progress: counts by status, a lane per account with its latest sends, a time series, the current rate and an ETA", "description": "Live progress: counts by status, a lane per account with its latest sends, a time series, the current rate and an ETA.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "total": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" }, "skipped": { "type": "integer" }, "pending": { "type": "integer" }, "in_flight": { "type": "integer" }, "by_status": { "type": "object", "properties": { "DELIVERED": { "type": "integer" }, "FAILED": { "type": "integer" }, "RECIPIENT_UNAVAILABLE": { "type": "integer" }, "QUEUED": { "type": "integer" }, "SENDING": { "type": "integer" }, "PENDING": { "type": "integer" } } }, "by_account": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" }, "in_flight": { "type": "integer" }, "ticks": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "status": { "type": "string" } } } } } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" } } } }, "bucket_seconds": { "type": "integer" }, "rate_per_minute": { "type": "number" }, "eta": { "type": "string", "format": "date-time" } } }, "example": { "campaign_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "status": "RUNNING", "total": 1840, "delivered": 612, "failed": 4, "unavailable": 9, "skipped": 0, "pending": 1215, "in_flight": 3, "by_status": { "DELIVERED": 612, "FAILED": 4, "RECIPIENT_UNAVAILABLE": 9, "QUEUED": 2, "SENDING": 1, "PENDING": 1212 }, "by_account": [ { "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "display_name": "Silk Road Support", "username": "silkroad_support", "status": "ACTIVE", "status_reason": null, "cooldown_until": null, "delivered": 318, "failed": 2, "unavailable": 5, "in_flight": 1, "ticks": [ { "at": "2026-09-30T08:14:02Z", "status": "DELIVERED" }, { "at": "2026-09-30T08:14:10Z", "status": "DELIVERED" } ] } ], "series": [ { "at": "2026-09-30T08:05:00Z", "delivered": 38, "failed": 0, "unavailable": 1 }, { "at": "2026-09-30T08:10:00Z", "delivered": 41, "failed": 1, "unavailable": 0 } ], "bucket_seconds": 300, "rate_per_minute": 7.8, "eta": "2026-09-30T11:05:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/campaigns/{id}/recipients": { "get": { "operationId": "getCampaignsByIdRecipients", "summary": "Per-recipient delivery state, the account that sent it, attempts and the last error", "description": "Per-recipient delivery state, the account that sent it, attempts and the last error.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Campaigns" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "status": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "job_id": { "type": "string" }, "telegram_message_id": { "type": [ "integer", "null" ] }, "attempts": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "queued_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "recipient_name": { "type": "string" }, "recipient_username": { "type": "string" }, "recipient_telegram_id": { "type": "integer" }, "account_name": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "crp_01j9rd1f3h5k7m9p1s3v5x7z9b", "campaign_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "status": "DELIVERED", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "job_id": "job_01j9rc8e0g2j4m6p8r0t2w4y6a", "telegram_message_id": 48213, "attempts": 1, "last_error": null, "queued_at": "2026-09-30T08:14:01Z", "sent_at": "2026-09-30T08:14:02Z", "updated_at": "2026-09-30T08:14:02Z", "recipient_name": "Aziza Karimova", "recipient_username": "aziza_k", "recipient_telegram_id": 123456789, "account_name": "Silk Road Support" } ], "total": 1840, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/jobs": { "get": { "operationId": "getJobs", "summary": "Send jobs with their result: DELIVERED, FAILED, RECIPIENT_UNAVAILABLE, ACCOUNT_RESTRICTED, AUTH_REQUIRED, TEMPORARY_ERROR or CANCELLED", "description": "Send jobs with their result: DELIVERED, FAILED, RECIPIENT_UNAVAILABLE, ACCOUNT_RESTRICTED, AUTH_REQUIRED, TEMPORARY_ERROR or CANCELLED.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Jobs and events" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "campaign_id", "in": "query", "required": false, "description": "Filter by campaign ID.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "Filter by account ID.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "campaign_id": { "type": [ "string", "null" ] }, "campaign_recipient_id": { "type": "string" }, "recipient_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "result": { "type": "string" }, "attempts": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "job_01j9rc8e0g2j4m6p8r0t2w4y6a", "campaign_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "campaign_recipient_id": "crp_01j9rd1f3h5k7m9p1s3v5x7z9b", "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "status": "SUCCEEDED", "result": "DELIVERED", "attempts": 1, "last_error": null, "created_at": "2026-09-30T08:14:01Z", "started_at": "2026-09-30T08:14:01Z", "completed_at": "2026-09-30T08:14:02Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/events": { "get": { "operationId": "getEvents", "summary": "Organization events, newest first: the same events webhooks deliver", "description": "Organization events, newest first: the same events webhooks deliver. type takes several values separated by commas; since takes a time or a date.\n\nNeeds `campaigns:read`, which API keys have.", "tags": [ "Jobs and events" ], "x-oqim-permission": "campaigns:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Event types separated by commas; campaign.* matches a prefix.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only events after this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "data": { "type": "object", "properties": { "campaign_id": { "type": [ "string", "null" ] }, "total": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "evt_01j9r7m2p4s6v8x0z2b4d6f8h0", "type": "campaign.started", "data": { "campaign_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "total": 1840 }, "created_at": "2026-09-30T05:00:02Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/events/stream": { "get": { "operationId": "getEventsStream", "summary": "Server-sent events (text/event-stream): every organization event as it happens, with a ping comment every 20 seconds to keep proxies from closing the connection", "description": "Server-sent events (text/event-stream): every organization event as it happens, with a ping comment every 20 seconds to keep proxies from closing the connection. Readable with campaigns:read or ai:read (for the AI's events: ai.analysis.updated, ai.insights.narrative_ready, ai.cases.generated, ai.insights.backfill and the rest).\n\nNeeds `campaigns:read or ai:read`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Jobs and events" ], "x-oqim-permission": "campaigns:read or ai:read", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "retry: 5000\n: connected\n\nid: evt_01j9r7m2p4s6v8x0z2b4d6f8h0\nevent: campaign.started\ndata: {\"id\":\"evt_01j9r7m2p4s6v8x0z2b4d6f8h0\",\"type\":\"campaign.started\",\"data\":{\"campaign_id\":\"cmp_01j9r4c6e8g0j2m4p6r8t0w2y4\",\"total\":1840},\"created_at\":\"2026-09-30T05:00:02Z\"}\n\n: ping" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api-keys": { "get": { "operationId": "getApiKeys", "summary": "Keys with their prefix and last use", "description": "Keys with their prefix and last use. Secrets are never returned.\n\nNeeds `developers:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "API keys" ], "x-oqim-permission": "developers:manage", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_ip": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "rotated_from": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "key_01j9r8a1c3e5g7j9m1p3r5t7w9", "name": "CRM sync", "prefix": "oqk_n4v8t2kq7wzc", "last_used_at": null, "last_used_ip": null, "expires_at": null, "revoked_at": null, "rotated_from": null, "created_at": "2026-09-26T09:30:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postApiKeys", "summary": "Create a key", "description": "Create a key. expires_in_days is 1 to 3650; leave it out for a key that doesn't expire. The plan must include API access.\n\nNeeds `developers:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "API keys" ], "x-oqim-permission": "developers:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "expires_in_days": { "type": "integer" } } }, "example": { "name": "CRM sync", "expires_in_days": 90 } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_ip": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "rotated_from": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } } }, "example": { "id": "key_01j9r8a1c3e5g7j9m1p3r5t7w9", "name": "CRM sync", "prefix": "oqk_n4v8t2kq7wzc", "last_used_at": null, "last_used_ip": null, "expires_at": "2026-12-25T09:30:00Z", "revoked_at": null, "rotated_from": null, "created_at": "2026-09-26T09:30:00Z", "secret": "oqk_n4v8t2kq7wzc_yR3fT9qLm2Vx8KpZc6WnB4sHd1JgQ7eU0aXoN5tYiEw" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api-keys/{id}/rotate": { "post": { "operationId": "postApiKeysByIdRotate", "summary": "Issue a replacement key", "description": "Issue a replacement key. The old key keeps working for 24 hours, then stops. A revoked or expired key can't be rotated (409 key_inactive).\n\nNeeds `developers:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "API keys" ], "x-oqim-permission": "developers:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key ID (key_…).", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_ip": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "rotated_from": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } } }, "example": { "id": "key_01j9s7h9k1m3p5r7t9v1x3z5b7", "name": "CRM sync", "prefix": "oqk_p7s2d9fm3ktx", "last_used_at": null, "last_used_ip": null, "expires_at": null, "revoked_at": null, "rotated_from": "key_01j9r8a1c3e5g7j9m1p3r5t7w9", "created_at": "2026-09-26T09:30:00Z", "secret": "oqk_p7s2d9fm3ktx_Lq8Wz3Nc6Vb1Xm4Ks7Rd0Tf2Yh5Jg9Pa3Ue6Io1Bn8C" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api-keys/{id}": { "delete": { "operationId": "deleteApiKeysById", "summary": "Revoke a key immediately, along with any access tokens issued from it", "description": "Revoke a key immediately, along with any access tokens issued from it.\n\nNeeds `developers:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "API keys" ], "x-oqim-permission": "developers:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "API key ID (key_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks": { "get": { "operationId": "getWebhooks", "summary": "Webhook endpoints and their health", "description": "Webhook endpoints and their health.\n\nNeeds `webhooks:read`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "failure_streak": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "whk_01j9r6d4f6h8k0m2p4s6v8x0z2", "url": "https://hooks.silkroad.example/oqim", "description": "CRM sync", "events": [ "campaign.completed", "recipient.opted_out" ], "status": "ACTIVE", "failure_streak": 0, "last_success_at": "2026-09-26T09:12:00Z", "last_failure_at": null, "created_at": "2026-09-10T08:00:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postWebhooks", "summary": "Add an endpoint for some event types, or [\"*\"] for all", "description": "Add an endpoint for some event types, or [\"*\"] for all. In production the URL must be https on a public host. The signing secret appears once, in this response.\n\nNeeds `webhooks:manage`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } }, "example": { "url": "https://hooks.silkroad.example/oqim", "description": "CRM sync", "events": [ "campaign.completed", "recipient.opted_out" ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "failure_streak": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "signing_secret": { "type": "string" } } }, "example": { "id": "whk_01j9r6d4f6h8k0m2p4s6v8x0z2", "url": "https://hooks.silkroad.example/oqim", "description": "CRM sync", "events": [ "campaign.completed", "recipient.opted_out" ], "status": "ACTIVE", "failure_streak": 0, "last_success_at": null, "last_failure_at": null, "created_at": "2026-09-10T08:00:00Z", "signing_secret": "whsec_Qm9vc3RlZC1ieS1vcWltLXdlYmhvb2tz" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}": { "get": { "operationId": "getWebhooksById", "summary": "One endpoint", "description": "One endpoint.\n\nNeeds `webhooks:read`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID (whk_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "failure_streak": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "whk_01j9r6d4f6h8k0m2p4s6v8x0z2", "url": "https://hooks.silkroad.example/oqim", "description": "CRM sync", "events": [ "campaign.completed", "recipient.opted_out" ], "status": "ACTIVE", "failure_streak": 0, "last_success_at": "2026-09-26T09:12:00Z", "last_failure_at": null, "created_at": "2026-09-10T08:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchWebhooksById", "summary": "Change the URL, description or events, or set status to ACTIVE to re-enable an endpoint that was disabled after repeated failures", "description": "Change the URL, description or events, or set status to ACTIVE to re-enable an endpoint that was disabled after repeated failures.\n\nNeeds `webhooks:manage`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID (whk_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } }, "example": { "events": [ "*" ], "status": "ACTIVE" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "failure_streak": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "whk_01j9r6d4f6h8k0m2p4s6v8x0z2", "url": "https://hooks.silkroad.example/oqim", "description": "CRM sync", "events": [ "*" ], "status": "ACTIVE", "failure_streak": 0, "last_success_at": "2026-09-26T09:12:00Z", "last_failure_at": null, "created_at": "2026-09-10T08:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteWebhooksById", "summary": "Delete an endpoint and its delivery history", "description": "Delete an endpoint and its delivery history.\n\nNeeds `webhooks:manage`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID (whk_…).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/test": { "post": { "operationId": "postWebhooksByIdTest", "summary": "Queue a webhook.test delivery to this endpoint and return it (202)", "description": "Queue a webhook.test delivery to this endpoint and return it (202). A disabled endpoint is 409 webhook_disabled.\n\nNeeds `webhooks:manage`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID (whk_…).", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "event_id": { "type": [ "string", "null" ] }, "event_type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "id": "dlv_01j9s9k1m3p5r7t9v1x3z5b7d9", "webhook_id": "whk_01j9r6d4f6h8k0m2p4s6v8x0z2", "event_id": "evt_01j9r7m2p4s6v8x0z2b4d6f8h0", "event_type": "webhook.test", "status": "PENDING", "attempts": 0, "response_status": null, "response_body": null, "duration_ms": null, "created_at": "2026-09-30T13:41:07Z", "delivered_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/rotate-secret": { "post": { "operationId": "postWebhooksByIdRotateSecret", "summary": "Replace the signing secret", "description": "Replace the signing secret. Deliveries are signed with the new secret from now on.\n\nNeeds `webhooks:manage`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID (whk_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "failure_streak": { "type": "integer" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "signing_secret": { "type": "string" } } }, "example": { "id": "whk_01j9r6d4f6h8k0m2p4s6v8x0z2", "url": "https://hooks.silkroad.example/oqim", "description": "CRM sync", "events": [ "campaign.completed", "recipient.opted_out" ], "status": "ACTIVE", "failure_streak": 0, "last_success_at": "2026-09-26T09:12:00Z", "last_failure_at": null, "created_at": "2026-09-10T08:00:00Z", "signing_secret": "whsec_TmV3LXNlY3JldC1hZnRlci1yb3RhdGlv" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "getWebhooksByIdDeliveries", "summary": "The latest 100 deliveries with their attempts, the response status, the first 2 KB of the response body and the duration", "description": "The latest 100 deliveries with their attempts, the response status, the first 2 KB of the response body and the duration.\n\nNeeds `webhooks:read`, which API keys have.", "tags": [ "Webhooks" ], "x-oqim-permission": "webhooks:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook ID (whk_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "webhook_id": { "type": "string" }, "event_id": { "type": [ "string", "null" ] }, "event_type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "dlv_01j9rb5d7f9h1k3m5p7r9t1v3x", "webhook_id": "whk_01j9r6d4f6h8k0m2p4s6v8x0z2", "event_id": "evt_01j9r7m2p4s6v8x0z2b4d6f8h0", "event_type": "campaign.completed", "status": "SUCCEEDED", "attempts": 1, "response_status": 204, "response_body": "", "duration_ms": 142, "created_at": "2026-09-30T13:41:07Z", "delivered_at": "2026-09-30T13:41:07Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses": { "get": { "operationId": "getAiBusinesses", "summary": "All businesses in the organization", "description": "All businesses in the organization.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "timezone": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "biz_01", "name": "Acme Store", "timezone": "Asia/Tashkent" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiBusinesses", "summary": "Create a business", "description": "Create a business. A default 9-stage funnel and seller settings are created atomically.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "timezone": { "type": "string" } } }, "example": { "name": "Acme Store", "timezone": "Asia/Tashkent" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "timezone": { "type": "string" } } }, "example": { "id": "biz_01", "name": "Acme Store", "timezone": "Asia/Tashkent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}": { "get": { "operationId": "getAiBusinessesById", "summary": "One business", "description": "One business.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "example": { "id": "biz_01", "name": "Acme Store" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchAiBusinessesById", "summary": "Update any subset of business fields", "description": "Update any subset of business fields. business_hours are the opening hours the calendar books within, in the business's timezone: an object of days mon to sun, each {open, close} as HH:MM (close may be 24:00) or null for closed (a missing day is closed too). calendar_config are the booking rules (all optional): enabled (true), default_duration_minutes (30), min_duration_minutes (15), max_duration_minutes (120), buffer_minutes (0, kept free around each meeting), min_notice_minutes (60), max_days_ahead (60) and require_customer_confirmation (true; false lets autonomy 5 book without asking the customer to confirm the time first). Unknown days or fields and out-of-range values are refused (422).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "business_hours": { "type": "object", "properties": { "mon": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } } }, "sat": { "type": "object", "properties": { "open": { "type": "string" }, "close": { "type": "string" } } }, "sun": { "type": [ "string", "null" ] } } }, "calendar_config": { "type": "object", "properties": { "default_duration_minutes": { "type": "integer" }, "min_notice_minutes": { "type": "integer" } } } } }, "example": { "name": "Acme Store (updated)", "business_hours": { "mon": { "open": "09:00", "close": "18:00" }, "sat": { "open": "10:00", "close": "16:00" }, "sun": null }, "calendar_config": { "default_duration_minutes": 45, "min_notice_minutes": 120 } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "example": { "id": "biz_01", "name": "Acme Store (updated)" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiBusinessesById", "summary": "Delete a business and all its data (offers, funnels, identities, settings)", "description": "Delete a business and all its data (offers, funnels, identities, settings).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/offers": { "get": { "operationId": "getAiBusinessesByIdOffers", "summary": "Offers for a business, ordered by sales_priority", "description": "Offers for a business, ordered by sales_priority.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "ofr_01", "name": "Premium Plan", "type": "SUBSCRIPTION", "status": "ACTIVE" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiBusinessesByIdOffers", "summary": "Create an offer", "description": "Create an offer. type is required: PRODUCT, SERVICE, COURSE, SUBSCRIPTION, EVENT, PACKAGE or OTHER. currency must be a 3-letter ISO-4217 code (e.g. USD, UZS, RUB).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "price": { "type": "number" }, "currency": { "type": "string" } } }, "example": { "type": "PRODUCT", "name": "Starter Kit", "price": 29.99, "currency": "USD" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "example": { "id": "ofr_01", "type": "PRODUCT", "name": "Starter Kit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/offers/{id}": { "patch": { "operationId": "patchAiOffersById", "summary": "Update offer fields", "description": "Update offer fields. status: ACTIVE or ARCHIVED.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "ARCHIVED" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } }, "example": { "id": "ofr_01", "status": "ARCHIVED" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiOffersById", "summary": "Delete an offer", "description": "Delete an offer.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/funnels": { "get": { "operationId": "getAiBusinessesByIdFunnels", "summary": "Sales funnels for a business, each with its stages", "description": "Sales funnels for a business, each with its stages.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "position": { "type": "integer" } } } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "fnl_01", "name": "Default", "is_default": true, "stages": [] } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiBusinessesByIdFunnels", "summary": "Create a new funnel (empty stages; use PUT /stages to fill it)", "description": "Create a new funnel (empty stages; use PUT /stages to fill it).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } } }, "example": { "name": "Warm Leads" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "position": { "type": "integer" } } } } } }, "example": { "id": "fnl_01", "name": "Warm Leads", "is_default": false, "stages": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/funnels/{id}": { "get": { "operationId": "getAiFunnelsById", "summary": "One funnel with its stages", "description": "One funnel with its stages.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "stages": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "position": { "type": "integer" } } } } } }, "example": { "id": "fnl_01", "name": "Default", "stages": [ { "key": "NEW", "name": "New Lead", "position": 0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchAiFunnelsById", "summary": "Rename a funnel or change is_default", "description": "Rename a funnel or change is_default.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } } }, "example": { "name": "Default (renamed)" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "example": { "id": "fnl_01", "name": "Default (renamed)" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiFunnelsById", "summary": "Delete a funnel and its stages", "description": "Delete a funnel and its stages.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/funnels/{id}/stages": { "put": { "operationId": "putAiFunnelsByIdStages", "summary": "Replace the entire stage list atomically", "description": "Replace the entire stage list atomically. stages[] must have unique keys and end with a terminal stage (key CONVERTED, or ending in _DONE, _COMPLETE, _CONVERTED, _CLOSED). Each stage may set objective, allowed_actions and prohibited_actions (the AI Seller only does what the stage allows, and never what it prohibits), recommended_questions, and handoff_rules shaped like the seller settings' ones, which apply on top of them while a conversation is in the stage. Stage ids change with every replace; conversations keep their stage by key.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] } } } } } }, "example": { "stages": [ { "key": "NEW", "name": "New Lead" }, { "key": "CONVERTED", "name": "Converted" } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "funnel_id": { "type": "string" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "position": { "type": "integer" } } } } } }, "example": { "funnel_id": "fnl_01", "stages": [ { "key": "NEW", "position": 0 }, { "key": "CONVERTED", "position": 1 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/identities": { "get": { "operationId": "getAiBusinessesByIdIdentities", "summary": "AI personas for a business", "description": "AI personas for a business.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "language": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "idn_01", "display_name": "Zulfiya", "language": "uz" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiBusinessesByIdIdentities", "summary": "Create a persona", "description": "Create a persona. display_name is required. biography must not claim the AI is a human (422 if it contains phrases like 'I am a real person', 'я живой человек' or 'men haqiqiy odamman').\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "role": { "type": "string" } } }, "example": { "display_name": "Zulfiya", "language": "uz", "role": "Sales consultant" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] } } }, "example": { "id": "idn_01", "display_name": "Zulfiya" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/identities/{id}": { "patch": { "operationId": "patchAiIdentitiesById", "summary": "Update identity fields", "description": "Update identity fields.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": [ "string", "null" ] } } }, "example": { "display_name": "Zulfiya (updated)" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] } } }, "example": { "id": "idn_01", "display_name": "Zulfiya (updated)" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiIdentitiesById", "summary": "Delete an identity", "description": "Delete an identity.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/communication-profiles": { "get": { "operationId": "getAiCommunicationProfiles", "summary": "Built-in profiles (is_builtin: true) and organization-owned profiles", "description": "Built-in profiles (is_builtin: true) and organization-owned profiles. Built-in profiles are read-only; copy them to customize.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_builtin": { "type": "boolean" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cpf_small_business", "name": "Small Business", "is_builtin": true }, { "id": "cpf_01", "name": "My Profile", "is_builtin": false } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiCommunicationProfiles", "summary": "Create a custom communication profile", "description": "Create a custom communication profile. All style fields are required: tone, formality, message_length, vocabulary, sentence_structure, greeting_style, emoji_policy, technical_depth, sales_aggressiveness, question_frequency, explanation_depth, cta_style, objection_style.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "audience_type": { "type": "string" }, "language": { "type": "string" }, "tone": { "type": "string" }, "formality": { "type": "string" }, "message_length": { "type": "string" }, "vocabulary": { "type": "string" }, "sentence_structure": { "type": "string" }, "greeting_style": { "type": "string" }, "emoji_policy": { "type": "string" }, "technical_depth": { "type": "string" }, "sales_aggressiveness": { "type": "string" }, "question_frequency": { "type": "string" }, "explanation_depth": { "type": "string" }, "cta_style": { "type": "string" }, "objection_style": { "type": "string" } } }, "example": { "name": "Direct B2B", "audience_type": "B2B", "language": "en", "tone": "PROFESSIONAL", "formality": "FORMAL", "message_length": "SHORT", "vocabulary": "STANDARD", "sentence_structure": "SHORT", "greeting_style": "FORMAL", "emoji_policy": "NONE", "technical_depth": "BASIC", "sales_aggressiveness": "MODERATE", "question_frequency": "LOW", "explanation_depth": "BRIEF", "cta_style": "DIRECT", "objection_style": "EVIDENCE" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "example": { "id": "cpf_01", "name": "Direct B2B" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/communication-profiles/{id}": { "patch": { "operationId": "patchAiCommunicationProfilesById", "summary": "Update a custom profile", "description": "Update a custom profile. 403 if is_builtin.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tone": { "type": "string" } } }, "example": { "tone": "FRIENDLY" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "tone": { "type": "string" } } }, "example": { "id": "cpf_01", "tone": "FRIENDLY" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiCommunicationProfilesById", "summary": "Delete a custom profile", "description": "Delete a custom profile. 403 if is_builtin.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/communication-profiles/{id}/copy": { "post": { "operationId": "postAiCommunicationProfilesByIdCopy", "summary": "Copy any profile (built-in or custom) into the organization as a new custom profile", "description": "Copy any profile (built-in or custom) into the organization as a new custom profile.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } } }, "example": { "name": "My Custom Profile" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_builtin": { "type": "boolean" } } }, "example": { "id": "cpf_02", "name": "My Custom Profile", "is_builtin": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/language-profiles": { "get": { "operationId": "getAiLanguageProfiles", "summary": "Built-in language profiles (is_builtin: true) and organization-owned ones", "description": "Built-in language profiles (is_builtin: true) and organization-owned ones.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "language": { "type": "string" }, "is_builtin": { "type": "boolean" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "lpf_uz_latin", "language": "uz", "is_builtin": true }, { "id": "lpf_01", "language": "uz", "is_builtin": false } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiLanguageProfiles", "summary": "Create a custom language profile", "description": "Create a custom language profile. language (uz/ru/en), formality (FORMAL/INFORMAL/MIXED) and vocabulary (SIMPLE/STANDARD/RICH) are required.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "language": { "type": "string" }, "formality": { "type": "string" }, "vocabulary": { "type": "string" } } }, "example": { "language": "uz", "formality": "INFORMAL", "vocabulary": "STANDARD" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "language": { "type": "string" } } }, "example": { "id": "lpf_01", "language": "uz" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/language-profiles/{id}": { "patch": { "operationId": "patchAiLanguageProfilesById", "summary": "Update a custom language profile", "description": "Update a custom language profile. 403 if is_builtin.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "formality": { "type": "string" } } }, "example": { "formality": "FORMAL" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "formality": { "type": "string" } } }, "example": { "id": "lpf_01", "formality": "FORMAL" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiLanguageProfilesById", "summary": "Delete a custom language profile", "description": "Delete a custom language profile. 403 if is_builtin.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/language-profiles/{id}/copy": { "post": { "operationId": "postAiLanguageProfilesByIdCopy", "summary": "Copy any language profile into the organization", "description": "Copy any language profile into the organization.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "language": { "type": "string" }, "is_builtin": { "type": "boolean" } } }, "example": { "id": "lpf_02", "language": "uz", "is_builtin": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/seller-settings": { "get": { "operationId": "getAiBusinessesByIdSellerSettings", "summary": "Runtime settings for the AI Seller on this business", "description": "Runtime settings for the AI Seller on this business.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "autonomy_level": { "type": "integer" }, "reply_window_hours": { "type": "integer" }, "followup_limit": { "type": "integer" }, "disclosure_enabled": { "type": "boolean" }, "active": { "type": "boolean" } } }, "example": { "business_id": "biz_01", "autonomy_level": 2, "reply_window_hours": 24, "followup_limit": 1, "disclosure_enabled": true, "active": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAiBusinessesByIdSellerSettings", "summary": "Create or replace seller settings", "description": "Create or replace seller settings. autonomy_level 0–5 (0 analytics only, 1 recommendations, 2 drafts a person approves, 3 automatic only for approved_scenarios, 4 automatic, 5 automatic with the tools approved in the agent configuration); reply_window_hours 1–168; followup_limit 0–5. When disclosure_enabled is true, disclosure_text must have non-empty text for uz, ru and en; the first AI message of each conversation starts with it. approved_scenarios for autonomy 3: GREETING, FAQ, PRICING, PRODUCT_INFO, AVAILABILITY, DELIVERY, OBJECTION, CLOSING, SCHEDULING, AI_DISCLOSURE, OTHER (complaints and requests for a person always go to a person). handoff_rules (all optional; a funnel stage's own handoff_rules apply on top while the conversation is in it): triggers turns HUMAN_REQUESTED, COMPLAINT, SENSITIVE_TOPIC, PRICING_EXCEPTION, CALENDAR_AMBIGUITY, POLICY_UNCERTAINTY, LOW_CONFIDENCE, REPEATED_FAILURES on or off (all on by default); keywords hand off (CUSTOM) when the customer's message contains one (a trailing * matches word endings); high_value_min hands off a lead worth at least that (HIGH_VALUE_LEAD, once per conversation); low_confidence_below (default 0.3) and max_failures (default 2) tune LOW_CONFIDENCE and REPEATED_FAILURES. Unknown scenarios, triggers or fields are refused (422).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "autonomy_level": { "type": "integer" }, "reply_window_hours": { "type": "integer" }, "active": { "type": "boolean" }, "approved_scenarios": { "type": "array", "items": { "type": "string" } }, "handoff_rules": { "type": "object", "properties": { "triggers": { "type": "object", "properties": { "CALENDAR_AMBIGUITY": { "type": "boolean" } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "high_value_min": { "type": "integer" } } } } }, "example": { "autonomy_level": 3, "reply_window_hours": 24, "active": true, "approved_scenarios": [ "FAQ", "PRICING" ], "handoff_rules": { "triggers": { "CALENDAR_AMBIGUITY": false }, "keywords": [ "advokat", "возврат*" ], "high_value_min": 5000000 } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "autonomy_level": { "type": "integer" }, "active": { "type": "boolean" }, "approved_scenarios": { "type": "array", "items": { "type": "string" } } } }, "example": { "business_id": "biz_01", "autonomy_level": 3, "active": true, "approved_scenarios": [ "FAQ", "PRICING" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/accounts": { "get": { "operationId": "getAiBusinessesByIdAccounts", "summary": "List Telegram accounts mapped to this business", "description": "List Telegram accounts mapped to this business. An account can serve only one business.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "example": [ { "organization_id": "org_01", "business_id": "biz_01", "account_id": "acc_01", "created_at": "2026-01-01T00:00:00Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAiBusinessesByIdAccounts", "summary": "Replace the full set of accounts mapped to this business", "description": "Replace the full set of accounts mapped to this business. Pass an empty array to clear all mappings. Each account must belong to the same organization and cannot be mapped to another business.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: configuration" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "account_ids": [ "acc_01" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "example": [ { "organization_id": "org_01", "business_id": "biz_01", "account_id": "acc_01", "created_at": "2026-01-01T00:00:00Z" } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/catalog": { "get": { "operationId": "getAiCatalog", "summary": "The built-in providers with their fixed endpoints and where to get a key, plus CUSTOM", "description": "The built-in providers with their fixed endpoints and where to get a key, plus CUSTOM. allow_private_endpoints says whether custom endpoints may use private network addresses on this installation.\n\nNeeds `org:read`, which API keys have.", "tags": [ "AI" ], "x-oqim-permission": "org:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "base_url": { "type": [ "string", "null" ] }, "api_format": { "type": "string" }, "key_url": { "type": "string" }, "key_required": { "type": "boolean" }, "model_placeholder": { "type": "string" } } } }, "allow_private_endpoints": { "type": "boolean" } } }, "example": { "data": [ { "kind": "OPENAI", "name": "OpenAI", "base_url": "https://api.openai.com/v1", "api_format": "OPENAI", "key_url": "https://platform.openai.com/api-keys", "key_required": true, "model_placeholder": "gpt-5.6" }, { "kind": "ANTHROPIC", "name": "Anthropic", "base_url": "https://api.anthropic.com/v1", "api_format": "ANTHROPIC", "key_url": "https://platform.claude.com/settings/keys", "key_required": true, "model_placeholder": "claude-sonnet-5" }, { "kind": "CUSTOM", "name": "Custom", "base_url": "", "api_format": "OPENAI", "key_url": "", "key_required": false, "model_placeholder": "llama3.2" } ], "allow_private_endpoints": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/providers": { "get": { "operationId": "getAiProviders", "summary": "Connected providers, the default first", "description": "Connected providers, the default first. The API key is never returned; key_hint shows its last characters and endpoint where requests go.\n\nNeeds `org:read`, which API keys have.", "tags": [ "AI" ], "x-oqim-permission": "org:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "api_format": { "type": "string" }, "base_url": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "key_hint": { "type": [ "string", "null" ] }, "has_key": { "type": "boolean" }, "is_default": { "type": "boolean" }, "status": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "endpoint": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "OpenAI", "kind": "OPENAI", "api_format": "OPENAI", "base_url": null, "model": "gpt-5.6", "key_hint": "•••• 4f2a", "has_key": true, "is_default": true, "status": "OK", "last_error": null, "last_checked_at": "2026-09-26T09:30:00Z", "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "endpoint": "https://api.openai.com/v1" }, { "id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Office GPU server", "kind": "CUSTOM", "api_format": "OPENAI", "base_url": "http://host.docker.internal:11434/v1", "model": "qwen3:8b", "key_hint": null, "has_key": false, "is_default": false, "status": "OK", "last_error": null, "last_checked_at": "2026-09-26T09:30:00Z", "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "endpoint": "http://host.docker.internal:11434/v1" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiProviders", "summary": "Connect a provider", "description": "Connect a provider. Presets (OPENAI, ANTHROPIC, GEMINI, DEEPSEEK, OPENROUTER) need api_key and use their built-in endpoint. CUSTOM needs base_url, the part before /chat/completions, and api_format OPENAI or ANTHROPIC; its key is optional. The first provider becomes the default; up to 20 per organization. Test it next.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "api_key": { "type": "string" }, "model": { "type": "string" }, "is_default": { "type": "boolean" } } }, "example": { "kind": "OPENAI", "name": "OpenAI", "api_key": "sk-…", "model": "gpt-5.6", "is_default": true } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "api_format": { "type": "string" }, "base_url": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "key_hint": { "type": [ "string", "null" ] }, "has_key": { "type": "boolean" }, "is_default": { "type": "boolean" }, "status": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "endpoint": { "type": "string" } } }, "example": { "id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "OpenAI", "kind": "OPENAI", "api_format": "OPENAI", "base_url": null, "model": "gpt-5.6", "key_hint": "•••• 4f2a", "has_key": true, "is_default": true, "status": "UNTESTED", "last_error": null, "last_checked_at": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "endpoint": "https://api.openai.com/v1" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/providers/{id}": { "patch": { "operationId": "patchAiProvidersById", "summary": "Change a provider", "description": "Change a provider. Omit api_key (or send an empty string) to keep the stored key, send a new one to rotate it, or null to remove it from a custom endpoint. Changing the provider or base URL needs the key again. is_default: true makes it the default; to change the default, make another provider the default. Connection changes reset status to UNTESTED.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" } } }, "example": { "api_key": "sk-…" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "api_format": { "type": "string" }, "base_url": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "key_hint": { "type": [ "string", "null" ] }, "has_key": { "type": "boolean" }, "is_default": { "type": "boolean" }, "status": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "endpoint": { "type": "string" } } }, "example": { "id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "OpenAI", "kind": "OPENAI", "api_format": "OPENAI", "base_url": null, "model": "gpt-5.6", "key_hint": "•••• 9c1d", "has_key": true, "is_default": true, "status": "UNTESTED", "last_error": null, "last_checked_at": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "endpoint": "https://api.openai.com/v1" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiProvidersById", "summary": "Remove a provider and delete its key", "description": "Remove a provider and delete its key. When it was the default, the oldest remaining provider becomes the default.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/providers/{id}/test": { "post": { "operationId": "postAiProvidersByIdTest", "summary": "Send a tiny request and record the outcome in status (OK or ERROR), last_error and last_checked_at", "description": "Send a tiny request and record the outcome in status (OK or ERROR), last_error and last_checked_at. A failed test is still a 200 with status ERROR. Counts toward the provider-check limit.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "api_format": { "type": "string" }, "base_url": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "key_hint": { "type": [ "string", "null" ] }, "has_key": { "type": "boolean" }, "is_default": { "type": "boolean" }, "status": { "type": "string" }, "last_error": { "type": [ "string", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "endpoint": { "type": "string" } } }, "example": { "id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "OpenAI", "kind": "OPENAI", "api_format": "OPENAI", "base_url": null, "model": "gpt-5.6", "key_hint": "•••• 4f2a", "has_key": true, "is_default": true, "status": "OK", "last_error": null, "last_checked_at": "2026-09-26T09:30:00Z", "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "endpoint": "https://api.openai.com/v1" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/providers/{id}/models": { "get": { "operationId": "getAiProvidersByIdModels", "summary": "The provider's chat models, listed with the stored key", "description": "The provider's chat models, listed with the stored key. Lists that include every kind of model (OpenAI, Gemini, OpenRouter) are filtered to chat models.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "gpt-5.2" }, { "id": "gpt-5.6" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/models": { "post": { "operationId": "postAiModels", "summary": "List models for a configuration that isn't saved yet, so a form can offer a model picker", "description": "List models for a configuration that isn't saved yet, so a form can offer a model picker. The key is used for this one call and is neither stored nor logged.\n\nNeeds `org:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI" ], "x-oqim-permission": "org:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string" }, "api_format": { "type": "string" }, "base_url": { "type": [ "string", "null" ] }, "api_key": { "type": "string" } } }, "example": { "kind": "CUSTOM", "api_format": "OPENAI", "base_url": "http://host.docker.internal:11434/v1", "api_key": "" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "llama3.2:3b" }, { "id": "qwen3:8b" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getAiModels", "summary": "The model registry as your organization sees it: models with their capabilities, context window and prices in USD per million tokens", "description": "The model registry as your organization sees it: models with their capabilities, context window and prices in USD per million tokens. Platform entries are kept by Oqim's administrators; an organization entry overrides the platform's for the same provider and model. priced is false when a price the model needs is missing: its calls are then recorded at cost 0 and marked unpriced.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "provider_kind", "in": "query", "required": false, "description": "Filter by provider kind.", "schema": { "type": "string" } }, { "name": "capability", "in": "query", "required": false, "description": "Filter by capability.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "provider_kind": { "type": "string" }, "model_id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "context_window": { "type": "integer" }, "price_in_per_mtok": { "type": [ "number", "null" ] }, "price_out_per_mtok": { "type": [ "integer", "null" ] }, "price_embed_per_mtok": { "type": [ "number", "null" ] }, "enabled": { "type": "boolean" }, "created_by": { "type": [ "string", "null" ] }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "priced": { "type": "boolean" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "aim_01j9rs4w6y8a0c2e4g6j8m0p2r", "organization_id": null, "provider_kind": "OPENAI", "model_id": "gpt-5.6", "display_name": "GPT-5.6", "capabilities": [ "CHAT", "STRUCTURED" ], "context_window": 400000, "price_in_per_mtok": 1.25, "price_out_per_mtok": 10, "price_embed_per_mtok": null, "enabled": true, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "scope": "PLATFORM", "priced": true }, { "id": "aim_01j9s5ck4m6p8r0t2w4y6a8c0e", "organization_id": null, "provider_kind": "OPENAI", "model_id": "text-embedding-3-small", "display_name": null, "capabilities": [ "EMBEDDINGS" ], "context_window": 8191, "price_in_per_mtok": null, "price_out_per_mtok": null, "price_embed_per_mtok": 0.02, "enabled": true, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "scope": "PLATFORM", "priced": true } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/compose": { "post": { "operationId": "postAiCompose", "summary": "Draft or edit one message with a connected provider: provider_id, or the default", "description": "Draft or edit one message with a connected provider: provider_id, or the default. action DRAFT needs brief (up to 2,000 characters); IMPROVE, SHORTEN, FRIENDLIER, FORMAL, FIX and TRANSLATE need text (up to 4,096), and TRANSLATE needs language en, ru or uz. The result keeps {{variables}}, follows parse_mode and is never sent to anyone. warnings flags dropped or added placeholders and overlong results.\n\n30 requests an hour per person and 100 per organization (429 ai_rate_limited). A declined request is 422 ai_refused; a provider failure is 502 with an ai_provider_ code. While a platform administrator has AI turned off, it's 403 ai_disabled.\n\nNeeds `campaigns:manage`, which API keys have.", "tags": [ "AI" ], "x-oqim-permission": "campaigns:manage", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string" }, "text": { "type": "string" }, "parse_mode": { "type": "string" } } }, "example": { "action": "IMPROVE", "text": "hi {{first_name|there}}, expo opens tomorrow 10:00 in {{location}}. stop: {{opt_out_url}}", "parse_mode": "MARKDOWN" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "provider_id": { "type": "string" }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } } }, "warnings": { "type": "array", "items": {} } } }, "example": { "text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}. See you there.\n\nNo longer want these messages? {{opt_out_url}}", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "model": "gpt-5.6-2026-09-01", "usage": { "input_tokens": 412, "output_tokens": 61 }, "warnings": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/agents": { "get": { "operationId": "getAiAgents", "summary": "The agents (SELLER, CI, CALENDAR, RESEARCH, JUDGE, EMBEDDER), each with whether the platform lets it run (enabled), the tools it can be granted, the organization's configuration (config, null when it uses the default provider), how many businesses override it, and the effective chain with each entry's health", "description": "The agents (SELLER, CI, CALENDAR, RESEARCH, JUDGE, EMBEDDER), each with whether the platform lets it run (enabled), the tools it can be granted, the organization's configuration (config, null when it uses the default provider), how many businesses override it, and the effective chain with each entry's health.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "capability": { "type": "string" }, "enabled": { "type": "boolean" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "default": { "type": "boolean" } } } }, "config": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "provider_id": { "type": "string" }, "model": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "string" }, "model": { "type": "string" } } } }, "params": { "type": "object", "properties": { "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "tool_permissions": { "type": "array", "items": { "type": "string" } }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "business_overrides": { "type": "integer" }, "effective": { "type": "object", "properties": { "source": { "type": "string" }, "chain": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "provider_id": { "type": "string" }, "provider_name": { "type": "string" }, "provider_kind": { "type": "string" }, "model": { "type": "string" }, "health": { "type": "object", "properties": { "status": { "type": "string" }, "failures": { "type": "integer" }, "until": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "key": "SELLER", "name": "Seller", "description": "Answers customers in conversations they started, with a structured reply and actions that are validated before anything is sent.", "capability": "STRUCTURED", "enabled": true, "tools": [ { "key": "knowledge.search", "name": "Search knowledge", "description": "Look up the business's knowledge base.", "default": true }, { "key": "memory.read", "name": "Read memory", "description": "Read what's remembered about the customer.", "default": true }, { "key": "handoff.request", "name": "Hand over to a person", "description": "Pause the AI in the conversation and ask a person to take over.", "default": true }, { "key": "lead.update", "name": "Update the lead", "description": "Update the lead's stage, quality and details.", "default": true }, { "key": "calendar.check_availability", "name": "Check availability", "description": "Look up free times in the connected calendar.", "default": true } ], "config": { "id": "agc_01j9rt7x9z1b3d5f7h9k1m3p5s", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "model": "gpt-5.6", "fallbacks": [ { "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "model": "qwen3:8b" } ], "params": { "temperature": 0.4, "max_tokens": 1200 }, "tool_permissions": [ "knowledge.search", "memory.read", "handoff.request", "lead.update" ], "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-21T09:00:00Z", "updated_at": "2026-09-26T09:30:00Z" }, "business_overrides": 1, "effective": { "source": "ORGANIZATION", "chain": [ { "role": "PRIMARY", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_name": "OpenAI", "provider_kind": "OPENAI", "model": "gpt-5.6", "health": { "status": "OK", "failures": 0, "until": null } }, { "role": "FALLBACK", "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "provider_name": "Office GPU server", "provider_kind": "CUSTOM", "model": "qwen3:8b", "health": { "status": "COOLING", "failures": 3, "until": "2026-09-26T09:30:30Z", "last_error_code": "timeout" } } ] } } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/agents/{agent}/config": { "get": { "operationId": "getAiAgentsByAgentConfig", "summary": "An agent's configuration for the organization, or with business_id for one business", "description": "An agent's configuration for the organization, or with business_id for one business. config is the row of exactly that scope (null and inherited true when it inherits: a business from the organization, the organization from its default provider). effective is the chain the router uses; an entry with problem (a removed provider, no embedding model) is skipped.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "capability": { "type": "string" } } }, "business_id": { "type": [ "string", "null" ] }, "config": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "provider_id": { "type": "string" }, "model": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "string" }, "model": { "type": "string" } } } }, "params": { "type": "object", "properties": { "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "tool_permissions": { "type": "array", "items": { "type": "string" } }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "inherited": { "type": "boolean" }, "effective": { "type": "object", "properties": { "source": { "type": "string" }, "chain": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "provider_id": { "type": "string" }, "provider_name": { "type": "string" }, "provider_kind": { "type": "string" }, "model": { "type": "string" }, "health": { "type": "object", "properties": { "status": { "type": "string" }, "failures": { "type": "integer" }, "until": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "params": { "type": "object", "properties": { "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "tool_permissions": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "default": { "type": "boolean" } } } } } }, "example": { "agent": { "key": "SELLER", "name": "Seller", "description": "Answers customers in conversations they started, with a structured reply and actions that are validated before anything is sent.", "capability": "STRUCTURED" }, "business_id": null, "config": { "id": "agc_01j9rt7x9z1b3d5f7h9k1m3p5s", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "model": "gpt-5.6", "fallbacks": [ { "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "model": "qwen3:8b" } ], "params": { "temperature": 0.4, "max_tokens": 1200 }, "tool_permissions": [ "knowledge.search", "memory.read", "handoff.request", "lead.update" ], "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-21T09:00:00Z", "updated_at": "2026-09-26T09:30:00Z" }, "inherited": false, "effective": { "source": "ORGANIZATION", "chain": [ { "role": "PRIMARY", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_name": "OpenAI", "provider_kind": "OPENAI", "model": "gpt-5.6", "health": { "status": "OK", "failures": 0, "until": null } }, { "role": "FALLBACK", "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "provider_name": "Office GPU server", "provider_kind": "CUSTOM", "model": "qwen3:8b", "health": { "status": "COOLING", "failures": 3, "until": "2026-09-26T09:30:30Z", "last_error_code": "timeout" } } ] }, "params": { "temperature": 0.4, "max_tokens": 1200 }, "tool_permissions": [ "knowledge.search", "memory.read", "handoff.request", "lead.update" ], "tools": [ { "key": "knowledge.search", "name": "Search knowledge", "description": "Look up the business's knowledge base.", "default": true }, { "key": "memory.read", "name": "Read memory", "description": "Read what's remembered about the customer.", "default": true }, { "key": "handoff.request", "name": "Hand over to a person", "description": "Pause the AI in the conversation and ask a person to take over.", "default": true }, { "key": "lead.update", "name": "Update the lead", "description": "Update the lead's stage, quality and details.", "default": true }, { "key": "calendar.check_availability", "name": "Check availability", "description": "Look up free times in the connected calendar.", "default": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchAiAgentsByAgentConfig", "summary": "Set which provider and model an agent uses, for the organization or (business_id) one business", "description": "Set which provider and model an agent uses, for the organization or (business_id) one business. Fields left out keep their value. provider_id null is the organization's default provider; model null is the provider's own model (for EMBEDDER, the registry's embedding model for that provider). fallbacks: up to 4 {provider_id, model}, tried in order after retryable failures. params: temperature 0 to 2 (used for every call) and max_tokens 16 to 200,000 (a ceiling per call). tool_permissions: tools from the agent's list. A business's new configuration starts as a copy of the organization's; the organization's starts with the default tools.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_id": { "type": "string" }, "model": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "string" }, "model": { "type": "string" } } } }, "params": { "type": "object", "properties": { "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } } } }, "example": { "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "model": "gpt-5.6", "fallbacks": [ { "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "model": "qwen3:8b" } ], "params": { "temperature": 0.4, "max_tokens": 1200 } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "capability": { "type": "string" } } }, "business_id": { "type": [ "string", "null" ] }, "config": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "provider_id": { "type": "string" }, "model": { "type": "string" }, "fallbacks": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "string" }, "model": { "type": "string" } } } }, "params": { "type": "object", "properties": { "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "tool_permissions": { "type": "array", "items": { "type": "string" } }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "inherited": { "type": "boolean" }, "effective": { "type": "object", "properties": { "source": { "type": "string" }, "chain": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "provider_id": { "type": "string" }, "provider_name": { "type": "string" }, "provider_kind": { "type": "string" }, "model": { "type": "string" }, "health": { "type": "object", "properties": { "status": { "type": "string" }, "failures": { "type": "integer" }, "until": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "params": { "type": "object", "properties": { "temperature": { "type": "number" }, "max_tokens": { "type": "integer" } } }, "tool_permissions": { "type": "array", "items": { "type": "string" } }, "tools": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "default": { "type": "boolean" } } } } } }, "example": { "agent": { "key": "SELLER", "name": "Seller", "description": "Answers customers in conversations they started, with a structured reply and actions that are validated before anything is sent.", "capability": "STRUCTURED" }, "business_id": null, "config": { "id": "agc_01j9rt7x9z1b3d5f7h9k1m3p5s", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "model": "gpt-5.6", "fallbacks": [ { "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "model": "qwen3:8b" } ], "params": { "temperature": 0.4, "max_tokens": 1200 }, "tool_permissions": [ "knowledge.search", "memory.read", "handoff.request", "lead.update" ], "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-21T09:00:00Z", "updated_at": "2026-09-26T09:30:00Z" }, "inherited": false, "effective": { "source": "ORGANIZATION", "chain": [ { "role": "PRIMARY", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_name": "OpenAI", "provider_kind": "OPENAI", "model": "gpt-5.6", "health": { "status": "OK", "failures": 0, "until": null } }, { "role": "FALLBACK", "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "provider_name": "Office GPU server", "provider_kind": "CUSTOM", "model": "qwen3:8b", "health": { "status": "COOLING", "failures": 3, "until": "2026-09-26T09:30:30Z", "last_error_code": "timeout" } } ] }, "params": { "temperature": 0.4, "max_tokens": 1200 }, "tool_permissions": [ "knowledge.search", "memory.read", "handoff.request", "lead.update" ], "tools": [ { "key": "knowledge.search", "name": "Search knowledge", "description": "Look up the business's knowledge base.", "default": true }, { "key": "memory.read", "name": "Read memory", "description": "Read what's remembered about the customer.", "default": true }, { "key": "handoff.request", "name": "Hand over to a person", "description": "Pause the AI in the conversation and ask a person to take over.", "default": true }, { "key": "lead.update", "name": "Update the lead", "description": "Update the lead's stage, quality and details.", "default": true }, { "key": "calendar.check_availability", "name": "Check availability", "description": "Look up free times in the connected calendar.", "default": true } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiAgentsByAgentConfig", "summary": "Remove the configuration of one scope: a business then inherits the organization's, and the organization's agent uses its default provider", "description": "Remove the configuration of one scope: a business then inherits the organization's, and the organization's agent uses its default provider.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "agent", "in": "path", "required": true, "description": "The agent.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/prompts": { "get": { "operationId": "getAiPrompts", "summary": "The prompts your organization sees: Oqim's platform defaults (scope PLATFORM, not editable) and your own, per organization or business, each with its active version", "description": "The prompts your organization sees: Oqim's platform defaults (scope PLATFORM, not editable) and your own, per organization or business, each with its active version. effective names the version each agent uses (for business_id, or the organization): the business's active version, else the organization's, else the platform default. placeholders lists the {{placeholders}} a prompt may use.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": false, "description": "Filter by agent.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "editable": { "type": "boolean" }, "versions": { "type": "integer" }, "active_version": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "effective": { "type": "object", "properties": { "SELLER": { "type": "object", "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" } } } } }, "placeholders": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": "string" } } } } } }, "example": { "data": [ { "id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "name": "Seller, expo season", "description": "Shorter replies for the expo weeks.", "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-22T11:00:00Z", "updated_at": "2026-09-22T11:00:00Z", "scope": "ORGANIZATION", "editable": true, "versions": 3, "active_version": { "id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 3, "content": "You are {{identity}}\n\nYou write the replies of a business in a Telegram conversation that the customer started. …\n\n# Knowledge\n{{knowledge}}", "status": "ACTIVE", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z" } } ], "total": 1, "limit": 50, "offset": 0, "effective": { "SELLER": { "id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 3, "content": "", "status": "ACTIVE", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "scope": "ORGANIZATION" } }, "placeholders": [ { "name": "identity", "description": "Who the assistant is: the persona's name, that it's the business's AI assistant, and the disclosure instruction." }, { "name": "knowledge", "description": "Retrieved knowledge passages with their sources, or a note that none matched." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiPrompts", "summary": "Create a prompt for an agent, for the organization or (business_id) one business, with its first version", "description": "Create a prompt for an agent, for the organization or (business_id) one business, with its first version. Without content it starts as a copy of the version the agent uses now. status is DRAFT (default) or TESTING; activate: true makes it the active version at once. Content is up to 32,000 characters and may use only the listed {{placeholders}}.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "content": { "type": "string" }, "changelog": { "type": "string" }, "activate": { "type": "boolean" } } }, "example": { "agent": "SELLER", "name": "Seller, expo season", "description": "Shorter replies for the expo weeks.", "content": "You are {{identity}} …", "changelog": "First version.", "activate": false } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "editable": { "type": "boolean" }, "versions": { "type": "integer" }, "active_version": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "version": { "type": "object", "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "example": { "prompt": { "id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "name": "Seller, expo season", "description": "Shorter replies for the expo weeks.", "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-22T11:00:00Z", "updated_at": "2026-09-22T11:00:00Z", "scope": "ORGANIZATION", "editable": true, "versions": 1, "active_version": null }, "version": { "id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 1, "content": "You are {{identity}}\n\nYou write the replies of a business in a Telegram conversation that the customer started. …\n\n# Knowledge\n{{knowledge}}", "status": "DRAFT", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": null, "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/prompts/{id}/versions": { "get": { "operationId": "getAiPromptsByIdVersions", "summary": "A prompt's versions, newest first, with their content", "description": "A prompt's versions, newest first, with their content.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 3, "content": "You are {{identity}}\n\nYou write the replies of a business in a Telegram conversation that the customer started. …\n\n# Knowledge\n{{knowledge}}", "status": "ACTIVE", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z" }, { "id": "prv_01j9s6dm5p7r9t1v3x5z7b9d1f", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 2, "content": "You are {{identity}}\n\nYou write the replies of a business in a Telegram conversation that the customer started. …\n\n# Knowledge\n{{knowledge}}", "status": "ARCHIVED", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiPromptsByIdVersions", "summary": "Add a version to one of your prompts (platform prompts can't be changed: 403 platform_prompt)", "description": "Add a version to one of your prompts (platform prompts can't be changed: 403 platform_prompt). status is DRAFT or TESTING; activate: true makes it active at once.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "changelog": { "type": "string" }, "status": { "type": "string" } } }, "example": { "content": "You are {{identity}} …", "changelog": "Shorter answers; always offer a person for refunds.", "status": "TESTING" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 4, "content": "You are {{identity}}\n\nYou write the replies of a business in a Telegram conversation that the customer started. …\n\n# Knowledge\n{{knowledge}}", "status": "TESTING", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": null, "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/prompts/{id}/versions/{v}/activate": { "post": { "operationId": "postAiPromptsByIdVersionsByVActivate", "summary": "Make version v the active version for its agent and scope", "description": "Make version v the active version for its agent and scope. The version it replaces is archived in the same step: there is never more than one active version per organization, agent and business. Activating an archived version rolls back to it.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "v", "in": "path", "required": true, "description": "The v.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "previous": { "type": "object", "properties": { "id": { "type": "string" }, "prompt_id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "status": { "type": "string" }, "changelog": { "type": "string" }, "author_id": { "type": "string" }, "author_label": { "type": "string" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } }, "example": { "version": { "id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 3, "content": "You are {{identity}}\n\nYou write the replies of a business in a Telegram conversation that the customer started. …\n\n# Knowledge\n{{knowledge}}", "status": "ACTIVE", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z" }, "previous": { "id": "prv_01j9s6dm5p7r9t1v3x5z7b9d1f", "prompt_id": "prm_01j9ry9d1f3h5k7m9p1s3v5x7z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "agent": "SELLER", "version": 2, "content": "You are {{identity}}\n\nYou write the replies of a business in a Telegram conversation that the customer started. …\n\n# Knowledge\n{{knowledge}}", "status": "ARCHIVED", "changelog": "Shorter answers; always offer a person for refunds.", "author_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "author_label": "dilnoza@silkroad.example", "activated_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-25T16:20:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/executions": { "get": { "operationId": "getAiExecutions", "summary": "AI runs, newest first: the agent, mode (LIVE, PLAYGROUND or EVAL), status (RUNNING, SUCCEEDED, FAILED or BLOCKED by the platform's switches or a budget), the provider and model of the main model call, tokens, cost in micro-dollars (unpriced when a price was missing), latency and the final action", "description": "AI runs, newest first: the agent, mode (LIVE, PLAYGROUND or EVAL), status (RUNNING, SUCCEEDED, FAILED or BLOCKED by the platform's switches or a budget), the provider and model of the main model call, tokens, cost in micro-dollars (unpriced when a price was missing), latency and the final action. conversation filters by conversation ID; from and to by start time.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "agent", "in": "query", "required": false, "description": "Filter by agent.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "Filter by mode.", "schema": { "type": "string" } }, { "name": "conversation", "in": "query", "required": false, "description": "Filter by conversation.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "mode": { "type": "string" }, "conversation_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "provider_id": { "type": "string" }, "provider_kind": { "type": "string" }, "model": { "type": "string" }, "prompt_version_id": { "type": "string" }, "identity_id": { "type": [ "string", "null" ] }, "communication_profile_id": { "type": [ "string", "null" ] }, "language_profile_id": { "type": [ "string", "null" ] }, "knowledge_version": { "type": [ "string", "null" ] }, "memory_refs": { "type": "array", "items": {} }, "jev_decision_id": { "type": [ "string", "null" ] }, "tools": { "type": "array", "items": { "type": "string" } }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "tokens_estimated": { "type": "boolean" }, "cost_micros": { "type": "integer" }, "unpriced": { "type": "boolean" }, "llm_calls": { "type": "integer" }, "fallbacks": { "type": "integer" }, "latency_ms": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "string" } } } }, "final_action": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "agent": "SELLER", "mode": "LIVE", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_kind": "OPENAI", "model": "gpt-5.6", "prompt_version_id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "identity_id": null, "communication_profile_id": null, "language_profile_id": null, "knowledge_version": null, "memory_refs": [], "jev_decision_id": null, "tools": [ "knowledge.search" ], "input_tokens": 2140, "output_tokens": 96, "embed_tokens": 12, "tokens_estimated": false, "cost_micros": 3636, "unpriced": false, "llm_calls": 2, "fallbacks": 0, "latency_ms": 2410, "status": "SUCCEEDED", "validation": { "passed": true, "checks": [ "schema", "honesty", "grounding", "length" ] }, "final_action": "SEND", "error": null, "started_at": "2026-09-26T09:29:57Z", "finished_at": "2026-09-26T09:29:59Z", "created_at": "2026-09-26T09:29:57Z", "updated_at": "2026-09-26T09:29:59Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/executions/{id}": { "get": { "operationId": "getAiExecutionsById", "summary": "One run with its trace: the steps in order (input summary, output, the model call each made with its tokens and cost, errors) and the tool calls the model asked for (REQUESTED, then EXECUTED, REJECTED or FAILED)", "description": "One run with its trace: the steps in order (input summary, output, the model call each made with its tokens and cost, errors) and the tool calls the model asked for (REQUESTED, then EXECUTED, REJECTED or FAILED). Step payloads are stored encrypted. No model reasoning is stored.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "agent": { "type": "string" }, "mode": { "type": "string" }, "conversation_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "provider_id": { "type": "string" }, "provider_kind": { "type": "string" }, "model": { "type": "string" }, "prompt_version_id": { "type": "string" }, "identity_id": { "type": [ "string", "null" ] }, "communication_profile_id": { "type": [ "string", "null" ] }, "language_profile_id": { "type": [ "string", "null" ] }, "knowledge_version": { "type": [ "string", "null" ] }, "memory_refs": { "type": "array", "items": {} }, "jev_decision_id": { "type": [ "string", "null" ] }, "tools": { "type": "array", "items": { "type": "string" } }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "tokens_estimated": { "type": "boolean" }, "cost_micros": { "type": "integer" }, "unpriced": { "type": "boolean" }, "llm_calls": { "type": "integer" }, "fallbacks": { "type": "integer" }, "latency_ms": { "type": [ "integer", "null" ] }, "status": { "type": "string" }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "string" } } } }, "final_action": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "step": { "type": "string" }, "status": { "type": "string" }, "input_summary": { "type": "object", "properties": { "query_terms": { "type": "integer" } } }, "output": { "type": "object", "properties": { "chunks": { "type": "integer" } } }, "error": { "type": [ "string", "null" ] }, "operation": { "type": "string" }, "provider_id": { "type": "string" }, "provider_kind": { "type": "string" }, "model": { "type": "string" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "tokens_estimated": { "type": "boolean" }, "cost_micros": { "type": "integer" }, "unpriced": { "type": "boolean" }, "fallbacks": { "type": "integer" }, "call_failed": { "type": "boolean" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "latency_ms": { "type": [ "integer", "null" ] } } } }, "tool_calls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "step_id": { "type": "string" }, "tool": { "type": "string" }, "args": { "type": "object", "properties": { "query": { "type": "string" } } }, "result": { "type": "object", "properties": { "chunks": { "type": "integer" } } }, "status": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "latency_ms": { "type": [ "integer", "null" ] } } } } } }, "example": { "id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "agent": "SELLER", "mode": "LIVE", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_kind": "OPENAI", "model": "gpt-5.6", "prompt_version_id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "identity_id": null, "communication_profile_id": null, "language_profile_id": null, "knowledge_version": null, "memory_refs": [], "jev_decision_id": null, "tools": [ "knowledge.search" ], "input_tokens": 2140, "output_tokens": 96, "embed_tokens": 12, "tokens_estimated": false, "cost_micros": 3636, "unpriced": false, "llm_calls": 2, "fallbacks": 0, "latency_ms": 2410, "status": "SUCCEEDED", "validation": { "passed": true, "checks": [ "schema", "honesty", "grounding", "length" ] }, "final_action": "SEND", "error": null, "started_at": "2026-09-26T09:29:57Z", "finished_at": "2026-09-26T09:29:59Z", "created_at": "2026-09-26T09:29:57Z", "updated_at": "2026-09-26T09:29:59Z", "steps": [ { "id": "axs_01j9rw3b5d7f9h1k3m5p7r9t1v", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "position": 0, "step": "knowledge", "status": "SUCCEEDED", "input_summary": { "query_terms": 4 }, "output": { "chunks": 3 }, "error": null, "operation": "EMBED", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_kind": "OPENAI", "model": "text-embedding-3-small", "input_tokens": 0, "output_tokens": 0, "embed_tokens": 12, "tokens_estimated": false, "cost_micros": 0, "unpriced": false, "fallbacks": 0, "call_failed": false, "started_at": "2026-09-26T09:29:57Z", "finished_at": "2026-09-26T09:29:57Z", "latency_ms": 180 }, { "id": "axs_01j9s7en8r0t2w4y6a8c0e2g4j", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "position": 1, "step": "generate", "status": "SUCCEEDED", "input_summary": { "messages": 8, "knowledge_chunks": 3 }, "output": { "message": "Salom! Ha, ertaga soat 10:00 da ochiq. Sizni qaysi kun qiziqtiradi?", "actions": [] }, "error": null, "operation": "STRUCTURED", "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_kind": "OPENAI", "model": "gpt-5.6", "input_tokens": 2140, "output_tokens": 96, "embed_tokens": 0, "tokens_estimated": false, "cost_micros": 3636, "unpriced": false, "fallbacks": 0, "call_failed": false, "started_at": "2026-09-26T09:29:57Z", "finished_at": "2026-09-26T09:29:59Z", "latency_ms": 2210 } ], "tool_calls": [ { "id": "atc_01j9rx6c8e0g2j4m6p8r0t2w4y", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "step_id": "axs_01j9rw3b5d7f9h1k3m5p7r9t1v", "tool": "knowledge.search", "args": { "query": "opening hours" }, "result": { "chunks": 3 }, "status": "EXECUTED", "error": null, "created_at": "2026-09-26T09:29:57Z", "finished_at": "2026-09-26T09:29:57Z", "latency_ms": 40 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/costs": { "get": { "operationId": "getAiCosts", "summary": "AI usage and cost for period today, week (the last 7 UTC days) or month (the calendar month so far, the default), in total and by business, agent, provider, model and mode, plus a day-by-day series", "description": "AI usage and cost for period today, week (the last 7 UTC days) or month (the calendar month so far, the default), in total and by business, agent, provider, model and mode, plus a day-by-day series. Requests and tokens are what providers reported (observed); cost is derived from the registry's prices at the time of each call.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Filter by period.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string" }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "basis": { "type": "object", "properties": { "requests": { "type": "string" }, "tokens": { "type": "string" }, "cost": { "type": "string" } } }, "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } }, "by_business": { "type": "array", "items": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_agent": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_provider": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "string" }, "provider_kind": { "type": "string" }, "provider_name": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_model": { "type": "array", "items": { "type": "object", "properties": { "provider_kind": { "type": "string" }, "model": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_mode": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "daily": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } } } }, "example": { "period": "month", "from": "2026-09-01", "to": "2026-09-26", "currency": "USD", "basis": { "requests": "observed", "tokens": "observed", "cost": "derived" }, "totals": { "requests": 1840, "failed_requests": 1, "input_tokens": 3496000, "output_tokens": 202400, "embed_tokens": 25760, "cost_micros": 6412300, "cost_usd": 6.4123, "unpriced_requests": 0, "estimated_requests": 0 }, "by_business": [ { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "requests": 1790, "failed_requests": 1, "input_tokens": 3401000, "output_tokens": 196900, "embed_tokens": 25060, "cost_micros": 6231000, "cost_usd": 6.231, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_agent": [ { "agent": "SELLER", "requests": 1210, "failed_requests": 1, "input_tokens": 2299000, "output_tokens": 133100, "embed_tokens": 16940, "cost_micros": 5102000, "cost_usd": 5.102, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_provider": [ { "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_kind": "OPENAI", "provider_name": "OpenAI", "requests": 1840, "failed_requests": 1, "input_tokens": 3496000, "output_tokens": 202400, "embed_tokens": 25760, "cost_micros": 6412300, "cost_usd": 6.4123, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_model": [ { "provider_kind": "OPENAI", "model": "gpt-5.6", "requests": 1210, "failed_requests": 1, "input_tokens": 2299000, "output_tokens": 133100, "embed_tokens": 16940, "cost_micros": 5102000, "cost_usd": 5.102, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_mode": [ { "mode": "LIVE", "requests": 1760, "failed_requests": 1, "input_tokens": 3344000, "output_tokens": 193600, "embed_tokens": 24640, "cost_micros": 6201000, "cost_usd": 6.201, "unpriced_requests": 0, "estimated_requests": 0 } ], "daily": [ { "date": "2026-09-26", "requests": 84, "failed_requests": 1, "input_tokens": 159600, "output_tokens": 9240, "embed_tokens": 1176, "cost_micros": 301400, "cost_usd": 0.3014, "unpriced_requests": 0, "estimated_requests": 0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/budgets": { "get": { "operationId": "getAiBudgets", "summary": "The organization's AI budgets (daily and monthly, each null when unset) with this period's spending, and the combined state: ALLOWED, SOFT_ALERT (an alert threshold reached, or the limit passed on a budget without hard stop) or HARD_STOP (runs and model calls are refused until the period resets)", "description": "The organization's AI budgets (daily and monthly, each null when unset) with this period's spending, and the combined state: ALLOWED, SOFT_ALERT (an alert threshold reached, or the limit passed on a budget without hard stop) or HARD_STOP (runs and model calls are refused until the period resets).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "daily": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "messages_sent": { "type": "integer" }, "api_requests": { "type": "integer" } } } }, "monthly": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "period": { "type": "string" }, "limit_micros": { "type": "integer" }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "hard_stop": { "type": "boolean" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "limit_usd": { "type": "integer" }, "spent_micros": { "type": "integer" }, "spent_usd": { "type": "number" }, "ratio": { "type": "number" }, "state": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "resets_at": { "type": "string", "format": "date-time" } } } } }, "example": { "state": "SOFT_ALERT", "daily": null, "monthly": { "id": "abg_01j9s15f7h9k1m3p5r7t9v1x3z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "period": "MONTHLY", "limit_micros": 50000000, "alert_thresholds": [ 80, 100 ], "hard_stop": true, "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z", "limit_usd": 50, "spent_micros": 41200000, "spent_usd": 41.2, "ratio": 0.824, "state": "SOFT_ALERT", "period_start": "2026-09-01T00:00:00Z", "resets_at": "2026-10-01T00:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAiBudgets", "summary": "Set the budgets: daily and monthly each take {limit_usd, alert_thresholds, hard_stop}, null removes that budget, and a period you leave out stays as it is", "description": "Set the budgets: daily and monthly each take {limit_usd, alert_thresholds, hard_stop}, null removes that budget, and a period you leave out stays as it is. alert_thresholds are percentages of the limit (1 to 1000, default 80 and 100): crossing one notifies the organization once per period. hard_stop (default true) stops AI at 100% until the period resets. Changing the limit or thresholds re-arms this period's alerts.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI engine" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthly": { "type": "object", "properties": { "limit_usd": { "type": "integer" }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "hard_stop": { "type": "boolean" } } } } }, "example": { "monthly": { "limit_usd": 50, "alert_thresholds": [ 80, 100 ], "hard_stop": true } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "daily": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "messages_sent": { "type": "integer" }, "api_requests": { "type": "integer" } } } }, "monthly": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "period": { "type": "string" }, "limit_micros": { "type": "integer" }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "hard_stop": { "type": "boolean" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "limit_usd": { "type": "integer" }, "spent_micros": { "type": "integer" }, "spent_usd": { "type": "number" }, "ratio": { "type": "number" }, "state": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "resets_at": { "type": "string", "format": "date-time" } } } } }, "example": { "state": "SOFT_ALERT", "daily": null, "monthly": { "id": "abg_01j9s15f7h9k1m3p5r7t9v1x3z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "period": "MONTHLY", "limit_micros": 50000000, "alert_thresholds": [ 80, 100 ], "hard_stop": true, "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z", "limit_usd": 50, "spent_micros": 41200000, "spent_usd": 41.2, "ratio": 0.824, "state": "SOFT_ALERT", "period_start": "2026-09-01T00:00:00Z", "resets_at": "2026-10-01T00:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations": { "get": { "operationId": "getAiConversations", "summary": "The organization's inbox on every channel, each with its channel (TELEGRAM, INSTAGRAM or FACEBOOK), its account (account: id, channel, name, username, avatar_url; connected_account_id for Instagram and Facebook), the linked recipient's consent, last_message (author, kind, the first 80 characters of the text decrypted, at) and waiting_since (the customer's last message time when they wrote last and nobody replied; null otherwise)", "description": "The organization's inbox on every channel, each with its channel (TELEGRAM, INSTAGRAM or FACEBOOK), its account (account: id, channel, name, username, avatar_url; connected_account_id for Instagram and Facebook), the linked recipient's consent, last_message (author, kind, the first 80 characters of the text decrypted, at) and waiting_since (the customer's last message time when they wrote last and nobody replied; null otherwise). Sort with sort=recent (default: last message), unread (unread first), waiting (customer waiting, oldest first) or oldest. Filter by channel, account_id (a Telegram account or a connected account), ai_state (ACTIVE, PAUSED_HANDOFF, STOPPED or OFF), unread (true or false), waiting (true or false), has_media (true or false), personal (true lists only personal chats and needs accounts:manage; false, the default, hides them) and q (name, @username, phone, Telegram ID or Instagram/Page-scoped ID).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "Filter by channel.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "Filter by account ID.", "schema": { "type": "string" } }, { "name": "ai_state", "in": "query", "required": false, "description": "Filter by ai state.", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "required": false, "description": "Filter by unread.", "schema": { "type": "string" } }, { "name": "waiting", "in": "query", "required": false, "description": "Filter by waiting.", "schema": { "type": "string" } }, { "name": "has_media", "in": "query", "required": false, "description": "Filter by has media.", "schema": { "type": "string" } }, { "name": "personal", "in": "query", "required": false, "description": "Filter by personal.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Filter by sort.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "peer_user_id": { "type": "integer" }, "peer_external_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "ai_state": { "type": "string" }, "ai_state_reason": { "type": [ "string", "null" ] }, "ai_state_changed_at": { "type": "string", "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_inbound_at": { "type": "string", "format": "date-time" }, "last_analyzed_message_id": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "personal": { "type": "boolean" }, "personal_source": { "type": [ "string", "null" ] }, "history_imported_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_name": { "type": "string" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "channel": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "consent_status": { "type": "string" }, "last_message": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" }, "deleted": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" } } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "channel": "TELEGRAM", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "connected_account_id": null, "peer_user_id": 6021437788, "peer_external_id": null, "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "username": "aziza_k", "language": "uz", "ai_state": "ACTIVE", "ai_state_reason": null, "ai_state_changed_at": "2026-09-26T09:12:00Z", "last_message_at": "2026-09-26T09:14:05Z", "last_inbound_at": "2026-09-26T09:14:05Z", "last_analyzed_message_id": null, "unread_count": 2, "opted_out_at": null, "personal": false, "personal_source": null, "history_imported_at": null, "created_at": "2026-09-26T09:12:00Z", "updated_at": "2026-09-26T09:14:05Z", "account_name": "Silk Road Support", "account": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "channel": "TELEGRAM", "name": "Silk Road Support", "username": "silkroad_support", "avatar_url": null }, "consent_status": "OPTED_IN", "last_message": { "id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "direction": "IN", "author": "CUSTOMER", "status": "RECEIVED", "text": "Salom! Expo chiptasi qancha turadi?", "deleted": false, "occurred_at": "2026-09-26T09:14:05Z" } } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}": { "get": { "operationId": "getAiConversationsById", "summary": "One conversation with its newest messages (oldest first; limit up to 200, default 50), the linked recipient, the open handoff, and reply: whether a person can reply now and on what basis (REPLY_WINDOW, CONSENT on Telegram, or HUMAN_AGENT on Instagram and Facebook, with window_ends_at and, where the platform's Meta app has the Human Agent permission, human_window_ends_at), or why not (code, reason), and max_length with max_length_unit: the channel's text limit (Telegram 4096 utf16, Instagram 1000 bytes, Facebook 2000 characters)", "description": "One conversation with its newest messages (oldest first; limit up to 200, default 50), the linked recipient, the open handoff, and reply: whether a person can reply now and on what basis (REPLY_WINDOW, CONSENT on Telegram, or HUMAN_AGENT on Instagram and Facebook, with window_ends_at and, where the platform's Meta app has the Human Agent permission, human_window_ends_at), or why not (code, reason), and max_length with max_length_unit: the channel's text limit (Telegram 4096 utf16, Instagram 1000 bytes, Facebook 2000 characters). On Instagram and Facebook the window is 24 hours after the customer's last message (the business's reply window can shorten it); after that only a person may answer, up to 7 days, with Meta's HUMAN_AGENT tag, and nothing goes out on consent (code window_closed). Messages carry external_message_id (Meta's mid), imported (from a history import), read_at and reaction where Meta reports them, reply_to_message_id, forwarded_from, reactions ([{emoji, by: CUSTOMER|BUSINESS}]), attachments (id, kind, status, mime, filename, size_bytes, width, height, duration_ms, has_thumb; served by GET …/attachments/{attachment_id}), and metadata describing locations and contacts. Pass next_cursor as before for older messages. A message the customer deleted keeps its metadata but not its text. The AI Seller's side: state (what it knows about the customer: stage, intent with its confidence, interest, lead quality, objections, language, sentiment, next action, and details — needs, pain points, budget, timeline, whether they decide alone — which are encrypted at rest; null before the Seller's first turn), draft (the draft or recommendation waiting for a person, with its text, or null), lead, and stage_events (the last 20 moves between funnel stages, oldest first).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "before", "in": "query", "required": false, "description": "Filter by before.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "peer_user_id": { "type": "integer" }, "peer_external_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "ai_state": { "type": "string" }, "ai_state_reason": { "type": [ "string", "null" ] }, "ai_state_changed_at": { "type": "string", "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_inbound_at": { "type": "string", "format": "date-time" }, "last_analyzed_message_id": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "personal": { "type": "boolean" }, "personal_source": { "type": [ "string", "null" ] }, "history_imported_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_name": { "type": "string" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "channel": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "consent_status": { "type": "string" }, "last_message": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" }, "deleted": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" } } } } }, "recipient": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "language": { "type": "string" }, "source": { "type": "string" }, "consent_status": { "type": "string" }, "consent_timestamp": { "type": "string", "format": "date-time" }, "consent_note": { "type": "string" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "opt_out_source": { "type": [ "string", "null" ] }, "attributes": { "type": "object", "properties": { "event_date": { "type": "string" }, "location": { "type": "string" } } }, "tags": { "type": "array", "items": { "type": "string" } }, "imported_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "opt_out_status": { "type": "boolean" }, "list_ids": { "type": "array", "items": { "type": "string" } } } }, "handoff": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "trigger": { "type": "string" }, "ai_state": { "type": "object", "properties": {} }, "recommended_action": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "assigned_user": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "account_id": { "type": [ "string", "null" ] } } }, "reply": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "basis": { "type": "string" }, "window_ends_at": { "type": "string", "format": "date-time" }, "max_length": { "type": "integer" }, "max_length_unit": { "type": "string" } } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "telegram_message_id": { "type": [ "integer", "null" ] }, "external_message_id": { "type": [ "string", "null" ] }, "direction": { "type": "string" }, "author": { "type": "string" }, "body_len": { "type": "integer" }, "media_kind": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "sent_by": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "send_basis": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "edited_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "imported": { "type": "boolean" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" }, "reaction": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "recipients": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "type": "string" } } } }, "next_cursor": { "type": [ "string", "null" ] }, "state": { "type": "object", "properties": { "conversation_id": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "stage": { "type": "string" }, "sales_stage_id": { "type": "string" }, "intent": { "type": "string" }, "intent_confidence": { "type": "number" }, "interest_level": { "type": "string" }, "interest_score": { "type": "number" }, "lead_quality": { "type": "string" }, "objection": { "type": "string" }, "objections": { "type": "array", "items": {} }, "offers_interested": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" }, "sentiment": { "type": "string" }, "next_action": { "type": "string" }, "human_handoff": { "type": "boolean" }, "last_message_id": { "type": "string" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_execution_id": { "type": "string" }, "turns": { "type": "integer" }, "consecutive_failures": { "type": "integer" }, "fired_triggers": { "type": "array", "items": {} }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "details": { "type": "object", "properties": { "needs": { "type": "array", "items": { "type": "string" } }, "pain_points": { "type": "array", "items": {} }, "budget": { "type": [ "string", "null" ] }, "timeline": { "type": "string" }, "decision_maker": { "type": "boolean" } } } } }, "draft": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "status": { "type": "string" }, "body_len": { "type": "integer" }, "language": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "validation": { "type": "object", "properties": { "attempts": { "type": "integer" }, "passed": { "type": "boolean" }, "disclosure": { "type": "string" }, "failures": { "type": "array", "items": {} }, "warnings": { "type": "array", "items": {} }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } } } } }, "reply_to_message_id": { "type": "string" }, "message_id": { "type": [ "integer", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "type": "string" } } }, "lead": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "stage": { "type": "string" }, "quality": { "type": "string" }, "interest": { "type": "string" }, "status": { "type": "string" }, "value_estimate": { "type": "integer" }, "currency": { "type": "string" }, "offer_ids": { "type": "array", "items": { "type": "string" } }, "owner_user_id": { "type": [ "string", "null" ] }, "last_execution_id": { "type": "string" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_id": { "type": [ "string", "null" ] }, "stage_name": { "type": "string" } } }, "stage_events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "source": { "type": "string" }, "reason": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "jev_decision_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "example": { "conversation": { "id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "channel": "TELEGRAM", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "connected_account_id": null, "peer_user_id": 6021437788, "peer_external_id": null, "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "username": "aziza_k", "language": "uz", "ai_state": "ACTIVE", "ai_state_reason": null, "ai_state_changed_at": "2026-09-26T09:12:00Z", "last_message_at": "2026-09-26T09:14:05Z", "last_inbound_at": "2026-09-26T09:14:05Z", "last_analyzed_message_id": null, "unread_count": 2, "opted_out_at": null, "personal": false, "personal_source": null, "history_imported_at": null, "created_at": "2026-09-26T09:12:00Z", "updated_at": "2026-09-26T09:14:05Z", "account_name": "Silk Road Support", "account": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "channel": "TELEGRAM", "name": "Silk Road Support", "username": "silkroad_support", "avatar_url": null }, "consent_status": "OPTED_IN", "last_message": { "id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "direction": "IN", "author": "CUSTOMER", "status": "RECEIVED", "text": "Salom! Expo chiptasi qancha turadi?", "deleted": false, "occurred_at": "2026-09-26T09:14:05Z" } }, "recipient": { "id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_id": 123456789, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "language": "uz", "source": "CSV", "consent_status": "OPTED_IN", "consent_timestamp": "2026-08-14T11:20:00Z", "consent_note": "Registered for Tashkent Expo 2026 on expo.example", "opted_out_at": null, "opt_out_source": null, "attributes": { "event_date": "1 October", "location": "Tashkent City Hall" }, "tags": [ "expo-2026", "vip" ], "imported_at": "2026-09-05T09:00:00Z", "created_at": "2026-09-05T09:00:00Z", "updated_at": "2026-09-05T09:00:00Z", "opt_out_status": false, "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ] }, "handoff": null, "reply": { "allowed": true, "basis": "REPLY_WINDOW", "window_ends_at": "2026-09-27T09:14:05Z", "max_length": 4096, "max_length_unit": "utf16" }, "messages": [ { "id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "telegram_message_id": 48213, "external_message_id": null, "direction": "IN", "author": "CUSTOMER", "body_len": 35, "media_kind": null, "execution_id": null, "sent_by": null, "status": "RECEIVED", "send_basis": null, "attempts": 0, "error_code": null, "error": null, "occurred_at": "2026-09-26T09:14:05Z", "sent_at": "2026-09-26T09:14:05Z", "edited_at": null, "deleted_at": null, "imported": false, "read_at": null, "reaction": null, "metadata": null, "created_at": "2026-09-26T09:14:06Z", "updated_at": "2026-09-26T09:14:06Z", "body": "Salom! Expo chiptasi qancha turadi?" } ], "next_cursor": null, "state": { "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "stage": "OFFER_PRESENTED", "sales_stage_id": "stg_01j9s2c4e6g8j0m2p4r6t8w0y2", "intent": "pricing_question", "intent_confidence": 0.9, "interest_level": "high", "interest_score": 3.8, "lead_quality": "warm", "objection": "none", "objections": [], "offers_interested": [ "ofr_01j9s4m7p9r1t3v5x7z9b1d3f5" ], "language": "uz", "sentiment": "positive", "next_action": "ANSWER_QUESTION", "human_handoff": false, "last_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "last_message_at": "2026-09-26T09:14:05Z", "last_execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "turns": 1, "consecutive_failures": 0, "fired_triggers": [], "created_at": "2026-09-26T09:14:08Z", "updated_at": "2026-09-26T09:14:11Z", "details": { "needs": [ "a one-day ticket" ], "pain_points": [], "budget": null, "timeline": "this Saturday", "decision_maker": true } }, "draft": { "id": "sdr_01j9s4h4k6n8q0s2u4w6y8a0c2", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "kind": "DRAFT", "status": "PENDING", "body_len": 92, "language": "uz", "actions": [ "ANSWER_QUESTION" ], "validation": { "attempts": 1, "passed": true, "disclosure": "added", "failures": [], "warnings": [], "checks": [ { "name": "honesty", "passed": true }, { "name": "grounding", "passed": true }, { "name": "language", "passed": true } ] }, "reply_to_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "message_id": null, "decided_by": null, "decided_at": null, "created_at": "2026-09-26T09:14:11Z", "updated_at": "2026-09-26T09:14:11Z", "body": "Bu xabarga AI yordamchi javob bermoqda.\n\nSalom! Chipta narxi 150 000 soʻm. Qaysi kunga kerak?" }, "lead": { "id": "led_01j9s4j5m7p9r1t3v5x7z9b1d3", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "stage": "OFFER_PRESENTED", "quality": "warm", "interest": "high", "status": "OPEN", "value_estimate": 150000, "currency": "UZS", "offer_ids": [ "ofr_01j9s4m7p9r1t3v5x7z9b1d3f5" ], "owner_user_id": null, "last_execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "closed_at": null, "created_at": "2026-09-26T09:14:11Z", "updated_at": "2026-09-26T09:14:11Z", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "stage_name": "Offer Presented" }, "stage_events": [ { "id": "sse_01j9s4k5m7p9r1t3v5x7z9b1d3", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "from": null, "to": "NEW", "source": "SYSTEM", "reason": "The conversation starts at the funnel's first stage.", "confidence": null, "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "jev_decision_id": null, "created_at": "2026-09-26T09:14:11Z" }, { "id": "sse_01j9s4k6n8q0s2u4w6y8a0c2e4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "from": "NEW", "to": "OFFER_PRESENTED", "source": "AI", "reason": "The decision layer places the conversation in OFFER_PRESENTED (confidence 0.90).", "confidence": 0.9, "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "jev_decision_id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "created_at": "2026-09-26T09:14:11Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/reply": { "post": { "operationId": "postAiConversationsByIdReply", "summary": "Reply as a person", "description": "Reply as a person. The text (plain, up to the channel's max_length: 4,096 characters on Telegram, 1,000 bytes on Instagram, 2,000 characters on Facebook) is queued and sent by a worker from the conversation's account, like the AI's replies: at least a few seconds after the previous reply in the conversation, within the account's cooldowns and daily limit, and never from another account; Instagram and Facebook replies go through Meta's Send API as plain text. The consent gate is checked now and again at sending: 409 reply_not_allowed with details.reason OPTED_OUT, SUPPRESSED, CONVERSATION_STOPPED, NO_CONSENT (the reply window closed and there's no recorded consent) or window_closed (Instagram and Facebook: past 24 hours, or past 7 days with the Human Agent permission); 409 account_not_active, account_auth_required (reconnect the Instagram account or Page) or organization_suspended. A send Meta refuses ends FAILED with error_code window_closed, account_auth_required (the account becomes AUTH_REQUIRED), recipient_unavailable or provider_error; rate limits are retried. Watch ai.conversation.message_updated for sent or failed. Needs an accepted acceptable-use policy.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } } }, "example": { "text": "Salom Aziza! Chiptalar 150 000 so'mdan. Havolani yuboraymi?" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "telegram_message_id": { "type": [ "integer", "null" ] }, "external_message_id": { "type": [ "string", "null" ] }, "direction": { "type": "string" }, "author": { "type": "string" }, "body_len": { "type": "integer" }, "media_kind": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "sent_by": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "send_basis": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "edited_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "imported": { "type": "boolean" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" }, "reaction": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "recipients": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "type": "string" } } }, "example": { "id": "msg_01j9s4f2h4k6n8q0s2u4w6y8a0", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "telegram_message_id": null, "external_message_id": null, "direction": "OUT", "author": "HUMAN", "body_len": 58, "media_kind": null, "execution_id": null, "sent_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "status": "QUEUED", "send_basis": "REPLY_WINDOW", "attempts": 0, "error_code": null, "error": null, "occurred_at": "2026-09-26T09:30:00Z", "sent_at": null, "edited_at": null, "deleted_at": null, "imported": false, "read_at": null, "reaction": null, "metadata": null, "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z", "body": "Salom Aziza! Chiptalar 150 000 so'mdan. Havolani yuboraymi?" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/takeover": { "post": { "operationId": "postAiConversationsByIdTakeover", "summary": "Take the conversation over: the AI pauses (ai_state PAUSED_HANDOFF), its unsent messages are cancelled, and a MANUAL handoff assigned to you is opened (or the open handoff, if unassigned, becomes yours)", "description": "Take the conversation over: the AI pauses (ai_state PAUSED_HANDOFF), its unsent messages are cancelled, and a MANUAL handoff assigned to you is opened (or the open handoff, if unassigned, becomes yours). A conversation the customer stopped is 409 conversation_stopped.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "peer_user_id": { "type": "integer" }, "peer_external_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "ai_state": { "type": "string" }, "ai_state_reason": { "type": [ "string", "null" ] }, "ai_state_changed_at": { "type": "string", "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_inbound_at": { "type": "string", "format": "date-time" }, "last_analyzed_message_id": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "personal": { "type": "boolean" }, "personal_source": { "type": [ "string", "null" ] }, "history_imported_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_name": { "type": "string" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "channel": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "consent_status": { "type": "string" }, "last_message": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" }, "deleted": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" } } } } }, "handoff": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "trigger": { "type": "string" }, "ai_state": { "type": "object", "properties": {} }, "recommended_action": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "assigned_user": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "account_id": { "type": [ "string", "null" ] } } } } }, "example": { "conversation": { "id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "channel": "TELEGRAM", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "connected_account_id": null, "peer_user_id": 6021437788, "peer_external_id": null, "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "username": "aziza_k", "language": "uz", "ai_state": "PAUSED_HANDOFF", "ai_state_reason": "Taken over by dilnoza@silkroad.example", "ai_state_changed_at": "2026-09-26T09:12:00Z", "last_message_at": "2026-09-26T09:14:05Z", "last_inbound_at": "2026-09-26T09:14:05Z", "last_analyzed_message_id": null, "unread_count": 0, "opted_out_at": null, "personal": false, "personal_source": null, "history_imported_at": null, "created_at": "2026-09-26T09:12:00Z", "updated_at": "2026-09-26T09:14:05Z", "account_name": "Silk Road Support", "account": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "channel": "TELEGRAM", "name": "Silk Road Support", "username": "silkroad_support", "avatar_url": null }, "consent_status": "OPTED_IN", "last_message": { "id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "direction": "IN", "author": "CUSTOMER", "status": "RECEIVED", "text": "Salom! Expo chiptasi qancha turadi?", "deleted": false, "occurred_at": "2026-09-26T09:14:05Z" } }, "handoff": { "id": "hof_01j9s4g3j5m7p9r1t3v5x7z9b1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "reason": "Taken over by dilnoza@silkroad.example", "trigger": "MANUAL", "ai_state": {}, "recommended_action": null, "execution_id": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "assigned_user": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "resolved_at": null, "resolved_by": null, "resolution_note": null, "created_at": "2026-09-26T09:20:00Z", "updated_at": "2026-09-26T09:20:00Z", "conversation_title": "Aziza Karimova", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/resume": { "post": { "operationId": "postAiConversationsByIdResume", "summary": "Hand the conversation back to the AI: ai_state ACTIVE and the open handoff resolved", "description": "Hand the conversation back to the AI: ai_state ACTIVE and the open handoff resolved. The AI then answers whatever the customer wrote meanwhile. A conversation the customer stopped can't be resumed (409 conversation_stopped).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "peer_user_id": { "type": "integer" }, "peer_external_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "ai_state": { "type": "string" }, "ai_state_reason": { "type": [ "string", "null" ] }, "ai_state_changed_at": { "type": "string", "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_inbound_at": { "type": "string", "format": "date-time" }, "last_analyzed_message_id": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "personal": { "type": "boolean" }, "personal_source": { "type": [ "string", "null" ] }, "history_imported_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_name": { "type": "string" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "channel": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "consent_status": { "type": "string" }, "last_message": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" }, "deleted": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" } } } } }, "handoff": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "trigger": { "type": "string" }, "ai_state": { "type": "object", "properties": {} }, "recommended_action": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "assigned_user": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "account_id": { "type": [ "string", "null" ] } } } } }, "example": { "conversation": { "id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "channel": "TELEGRAM", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "connected_account_id": null, "peer_user_id": 6021437788, "peer_external_id": null, "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "username": "aziza_k", "language": "uz", "ai_state": "ACTIVE", "ai_state_reason": null, "ai_state_changed_at": "2026-09-26T09:12:00Z", "last_message_at": "2026-09-26T09:14:05Z", "last_inbound_at": "2026-09-26T09:14:05Z", "last_analyzed_message_id": null, "unread_count": 2, "opted_out_at": null, "personal": false, "personal_source": null, "history_imported_at": null, "created_at": "2026-09-26T09:12:00Z", "updated_at": "2026-09-26T09:14:05Z", "account_name": "Silk Road Support", "account": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "channel": "TELEGRAM", "name": "Silk Road Support", "username": "silkroad_support", "avatar_url": null }, "consent_status": "OPTED_IN", "last_message": { "id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "direction": "IN", "author": "CUSTOMER", "status": "RECEIVED", "text": "Salom! Expo chiptasi qancha turadi?", "deleted": false, "occurred_at": "2026-09-26T09:14:05Z" } }, "handoff": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/read": { "post": { "operationId": "postAiConversationsByIdRead", "summary": "Mark the conversation read in Oqim only (unread_count 0)", "description": "Mark the conversation read in Oqim only (unread_count 0). Nothing is marked read on Telegram, Instagram or Facebook: the customer never sees a read receipt. Replying or taking over does this too.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "peer_user_id": { "type": "integer" }, "peer_external_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "ai_state": { "type": "string" }, "ai_state_reason": { "type": [ "string", "null" ] }, "ai_state_changed_at": { "type": "string", "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_inbound_at": { "type": "string", "format": "date-time" }, "last_analyzed_message_id": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "personal": { "type": "boolean" }, "personal_source": { "type": [ "string", "null" ] }, "history_imported_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_name": { "type": "string" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "channel": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "consent_status": { "type": "string" }, "last_message": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" }, "deleted": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" } } } } }, "example": { "id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "channel": "TELEGRAM", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "connected_account_id": null, "peer_user_id": 6021437788, "peer_external_id": null, "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "username": "aziza_k", "language": "uz", "ai_state": "ACTIVE", "ai_state_reason": null, "ai_state_changed_at": "2026-09-26T09:12:00Z", "last_message_at": "2026-09-26T09:14:05Z", "last_inbound_at": "2026-09-26T09:14:05Z", "last_analyzed_message_id": null, "unread_count": 0, "opted_out_at": null, "personal": false, "personal_source": null, "history_imported_at": null, "created_at": "2026-09-26T09:12:00Z", "updated_at": "2026-09-26T09:14:05Z", "account_name": "Silk Road Support", "account": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "channel": "TELEGRAM", "name": "Silk Road Support", "username": "silkroad_support", "avatar_url": null }, "consent_status": "OPTED_IN", "last_message": { "id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "direction": "IN", "author": "CUSTOMER", "status": "RECEIVED", "text": "Salom! Expo chiptasi qancha turadi?", "deleted": false, "occurred_at": "2026-09-26T09:14:05Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/platform-read": { "post": { "operationId": "postAiConversationsByIdPlatformRead", "summary": "Send a read receipt on the platform itself (Telegram readHistory, Meta mark_seen) — the ONLY way a message is ever marked read there, and only when a person asks", "description": "Send a read receipt on the platform itself (Telegram readHistory, Meta mark_seen) — the ONLY way a message is ever marked read there, and only when a person asks. Sends it exactly once: a second call answers 200 with already_read: true and sends nothing. 409 when the platform refuses, 503 when the account is unreachable (nothing was sent). Audited.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform_read": { "type": "boolean" }, "already_read": { "type": "boolean" } } }, "example": { "platform_read": true, "already_read": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/attachments/{attachment_id}": { "get": { "operationId": "getAiConversationsByIdAttachmentsByAttachmentId", "summary": "Stream a message's file from Oqim's storage with its content type and HTTP Range (audio and video seek)", "description": "Stream a message's file from Oqim's storage with its content type and HTTP Range (audio and video seek). The platform's URL or file reference is never exposed. ?thumb=1 returns the thumbnail where one exists (404 no_thumbnail otherwise). While the file is still downloading it answers 202 { status: \"PENDING\" } and queues the download; a file that is TOO_LARGE, UNAVAILABLE or FAILED answers 409 with status and error. In a personal chat the route needs accounts:manage (otherwise 404).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "attachment_id", "in": "path", "required": true, "description": "The attachment id.", "schema": { "type": "string" } }, { "name": "thumb", "in": "query", "required": false, "description": "Filter by thumb.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "PENDING" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/uploads": { "post": { "operationId": "postAiConversationsByIdUploads", "summary": "Upload one file (multipart field file) to send in the conversation, before replying", "description": "Upload one file (multipart field file) to send in the conversation, before replying. Returns upload_id, filename, mime, size_bytes, kind and expires_at (24 h). It expires unused. Kinds allowed by channel: Telegram any file up to the cap (INBOX_MAX_FILE_MB, default 50 MB), Instagram image/video/audio, Facebook image/video/audio/file; 422 kind_not_allowed otherwise, 413 file_too_large. Send it with POST …/reply (attachments: [upload_id]).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string" } } }, "example": { "file": "(multipart file)" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "upload_id": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size_bytes": { "type": "integer" }, "kind": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "upload_id": "cup_01j9t5x7z9b1d3f5h7k9m1p3r5", "filename": "price-list.pdf", "mime": "application/pdf", "size_bytes": 184320, "kind": "DOCUMENT", "expires_at": "2026-09-26T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/personal": { "put": { "operationId": "putAiConversationsByIdPersonal", "summary": "Mark the chat personal (personal: true) or a business chat (false)", "description": "Mark the chat personal (personal: true) or a business chat (false). The decision is yours (personal_source OWNER): contacts never override it, and history imports respect it. A personal chat is never answered or analysed by the AI: its pending draft is superseded, the AI's unsent messages are cancelled (ai.draft.updated, ai.conversation.message_updated), and its summary, insights, memories, the Seller's state and case analyses are removed; its messages stay and people can still reply. Made a business chat again, the AI answers from the customer's next message, never what was said while it was personal. Audited.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "personal": { "type": "boolean" } } }, "example": { "personal": true } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "connected_account_id": { "type": [ "string", "null" ] }, "peer_user_id": { "type": "integer" }, "peer_external_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "ai_state": { "type": "string" }, "ai_state_reason": { "type": [ "string", "null" ] }, "ai_state_changed_at": { "type": "string", "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" }, "last_inbound_at": { "type": "string", "format": "date-time" }, "last_analyzed_message_id": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer" }, "opted_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "personal": { "type": "boolean" }, "personal_source": { "type": [ "string", "null" ] }, "history_imported_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_name": { "type": "string" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "channel": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "consent_status": { "type": "string" }, "last_message": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "status": { "type": "string" }, "text": { "type": "string" }, "deleted": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time" } } } } }, "example": { "id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "channel": "TELEGRAM", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "connected_account_id": null, "peer_user_id": 6021437788, "peer_external_id": null, "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "username": "aziza_k", "language": "uz", "ai_state": "ACTIVE", "ai_state_reason": null, "ai_state_changed_at": "2026-09-26T09:12:00Z", "last_message_at": "2026-09-26T09:14:05Z", "last_inbound_at": "2026-09-26T09:14:05Z", "last_analyzed_message_id": null, "unread_count": 2, "opted_out_at": null, "personal": true, "personal_source": "OWNER", "history_imported_at": null, "created_at": "2026-09-26T09:12:00Z", "updated_at": "2026-09-26T09:14:05Z", "account_name": "Silk Road Support", "account": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "channel": "TELEGRAM", "name": "Silk Road Support", "username": "silkroad_support", "avatar_url": null }, "consent_status": "OPTED_IN", "last_message": { "id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "direction": "IN", "author": "CUSTOMER", "status": "RECEIVED", "text": "Salom! Expo chiptasi qancha turadi?", "deleted": false, "occurred_at": "2026-09-26T09:14:05Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/insights": { "get": { "operationId": "getAiConversationsByIdInsights", "summary": "Latest Conversation Intelligence analysis and summary for a conversation, with live: the case analysis's current reading (JEV between summaries: scores, flags and classification; see AI Seller: case analysis and insights)", "description": "Latest Conversation Intelligence analysis and summary for a conversation, with live: the case analysis's current reading (JEV between summaries: scores, flags and classification; see AI Seller: case analysis and insights). Your model writes the summary and insights at most every 10 new messages and when the conversation ends; in between, sentiment and interest follow the live reading. Returns 404 (no_insights) when neither has run yet.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": [ "string", "null" ] }, "summary_short": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "live": { "type": "object", "properties": { "analysis_id": { "type": "string" }, "phase": { "type": "string" }, "mode": { "type": "string" }, "analyzed_at": { "type": "string", "format": "date-time" }, "scores": { "type": "object", "properties": { "satisfaction": { "type": "number" }, "sentiment": { "type": "number" }, "purchase_intent": { "type": "number" }, "urgency": { "type": "number" }, "trust": { "type": "number" } } }, "flags": { "type": "object", "properties": { "unanswered_question": { "type": "number" }, "missed_opportunity": { "type": "number" }, "competitor_mentioned": { "type": "number" }, "unavailable_item_requested": { "type": "number" }, "complaint": { "type": "number" } } }, "cases": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "kind": { "type": "string" }, "case_id": { "type": [ "string", "null" ] }, "case_key": { "type": [ "string", "null" ] }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "source": { "type": "string" } } } } } }, "insights": { "type": "object", "properties": { "intent": { "type": "string" }, "sentiment": { "type": "string" }, "interest": { "type": "string" }, "lead_quality": { "type": "string" }, "objections": { "type": "array", "items": {} }, "questions": { "type": "array", "items": { "type": "string" } }, "products": { "type": "array", "items": { "type": "string" } }, "needs": { "type": "array", "items": { "type": "string" } }, "next_action": { "type": "string" }, "appointment": { "type": "boolean" }, "summary_short": { "type": "string" }, "summary_long": { "type": "string" }, "opt_out_signal": { "type": "boolean" }, "confidence": { "type": [ "number", "null" ] } } } } }, "example": { "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "summary_short": "Customer wants to buy two expo tickets for Saturday.", "execution_id": "aix_01JXYZ", "live": { "analysis_id": "can_01j9s8u4w6y8a0c2e4g6j8m0p2", "phase": "LIVE", "mode": "JEV", "analyzed_at": "2026-09-26T09:33:00Z", "scores": { "satisfaction": 4.1, "sentiment": 4.3, "purchase_intent": 3.2, "urgency": 1.4, "trust": 2.2 }, "flags": { "unanswered_question": 0.12, "missed_opportunity": 0.08, "competitor_mentioned": 0.02, "unavailable_item_requested": 0.05, "complaint": 0.03 }, "cases": [ { "dimension": "DEMAND", "kind": "CASE", "case_id": "cas_01j9s7t3v5x7z9b1d3f5h7k9m1", "case_key": "GROUP_TICKETS", "name": { "uz": "Guruh chiptalari", "ru": "Групповые билеты", "en": "Group tickets" }, "probability": 0.86, "confidence": 0.86, "source": "JEV" } ] }, "insights": { "intent": "purchase", "sentiment": "positive", "interest": "high", "lead_quality": "hot", "objections": [], "questions": [ "Is Saturday still available?" ], "products": [ "Expo ticket" ], "needs": [ "Two tickets for Saturday" ], "next_action": "Confirm availability and send payment link", "appointment": false, "summary_short": "Customer wants to buy two expo tickets for Saturday.", "summary_long": "The customer Aziza asked about expo ticket prices. She confirmed interest in two tickets for Saturday and asked about availability. Sentiment is positive and intent is clearly purchase.", "opt_out_signal": false, "confidence": 0.92 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/analyze": { "post": { "operationId": "postAiConversationsByIdAnalyze", "summary": "Queue a Conversation Intelligence summary and insights for this conversation immediately (outside the normal 60-second debounce window and the every-10-messages cadence)", "description": "Queue a Conversation Intelligence summary and insights for this conversation immediately (outside the normal 60-second debounce window and the every-10-messages cadence). Returns 202 when queued, or the result directly when no queue is configured. A personal chat is never analysed: 409 conversation_personal. Rate-limited.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "conversation_id": { "type": [ "string", "null" ] } } }, "example": { "queued": true, "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/simulate": { "post": { "operationId": "postAiConversationsSimulate", "summary": "Simulator only (TELEGRAM_DRIVER=simulator; otherwise 404 simulator_only): a customer writes to one of your accounts", "description": "Simulator only (TELEGRAM_DRIVER=simulator; otherwise 404 simulator_only): a customer writes to one of your accounts. The message goes through exactly what a real one does: stored encrypted, the recipient linked or created, stop requests applied, events emitted and the AI's turn scheduled. from.contact true simulates someone in the account's Telegram contacts: the chat becomes personal and the AI stays out (personal true, respond false). The account must be ACTIVE with inbound on (409 account_not_active, inbound_disabled).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ] }, "from": { "type": [ "object", "null" ], "properties": { "telegram_id": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "language_code": { "type": "string" }, "contact": { "type": "boolean" } } }, "text": { "type": "string" } } }, "example": { "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "from": { "telegram_id": 6021437788, "username": "aziza_k", "first_name": "Aziza", "last_name": "Karimova", "language_code": "uz", "contact": false }, "text": "Salom! Expo chiptasi qancha turadi?" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "created": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "opted_out": { "type": "boolean" }, "respond": { "type": "boolean" }, "personal": { "type": "boolean" } } }, "example": { "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "created": true, "duplicate": false, "opted_out": false, "respond": true, "personal": false } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/playground/run": { "post": { "operationId": "postAiPlaygroundRun", "summary": "Dry-run the AI Seller pipeline against a business with a synthetic conversation (mode PLAYGROUND, or EVAL for automated evaluations)", "description": "Dry-run the AI Seller pipeline against a business with a synthetic conversation (mode PLAYGROUND, or EVAL for automated evaluations). The pipeline runs in full — JEV decision, strategy, compose, generate, validate, business and platform policy, autonomy gate — but nothing is sent, drafted, handed off, or written to customer states, leads, memories or any mutable table. Only the execution trace is stored (mode=PLAYGROUND) and is inspectable at GET /ai/executions/{id}. The budget gate still applies. Supply at least one CUSTOMER message. Overrides: autonomy_level (–1 uses the stored value), prompt_version_id (a Seller version of any status; an unknown one is 422), communication_profile_id, language_profile_id, language, knowledge_enabled (false to skip retrieval), memory_items (extra facts for this run only), and provider_id and model: the run is pinned to exactly that provider and model (the reply, its regeneration and the decision layer's LLM fallback), with no fallback to the business's chain; provider_id alone uses the provider's own model, model alone runs on the provider the Seller's chain starts with; a provider that isn't the organization's, or a model id with spaces or over 200 characters, is 422 on that field. A pinned model that fails ends the run with final_action FAILED and the reason in error. provider_id and model in the response are what wrote the reply. The run's JEV decision is stored with mode PLAYGROUND (or EVAL) and linked to the run. Rate-limited to 60 runs per org per hour.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "autonomy_level": { "type": "integer" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": "string" }, "text": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } } }, "customer_state": { "type": "object", "properties": { "stage_key": { "type": "string" }, "intent": { "type": "string" }, "interest_level": { "type": "string" } } }, "knowledge_enabled": { "type": "boolean" }, "memory_items": { "type": "array", "items": { "type": "string" } } } }, "example": { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "mode": "PLAYGROUND", "autonomy_level": -1, "messages": [ { "author": "CUSTOMER", "text": "Salom! Expo chiptasi qancha turadi?", "at": "2026-09-26T09:30:00Z" }, { "author": "AI", "text": "Salom! Chipta narxi 150 000 soʻm.", "at": "2026-09-26T09:30:00Z" }, { "author": "CUSTOMER", "text": "Yetkazib berasizmi?", "at": "2026-09-26T09:30:00Z" } ], "customer_state": { "stage_key": "OFFER_PRESENTED", "intent": "PRICING_QUESTION", "interest_level": "WARM" }, "knowledge_enabled": true, "memory_items": [ "Customer prefers Uzbek" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": [ "string", "null" ] }, "final_action": { "type": "string" }, "reply": { "type": "string" }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "disclosure": { "type": "string" }, "gate": { "type": "string" }, "attempts": { "type": "integer" } } }, "validation_codes": { "type": "array", "items": {} }, "gate": { "type": "object", "properties": { "autonomy": { "type": "integer" }, "action": { "type": "string" }, "scenario": { "type": [ "string", "null" ] } } }, "jev_decision": { "type": "object", "properties": { "decision_id": { "type": "string" }, "source": { "type": "string" }, "intent": { "type": "string" }, "stage": { "type": "string" }, "next_action": { "type": "string" }, "interest_level": { "type": "string" }, "lead_quality": { "type": "string" }, "objection": { "type": "string" }, "human_handoff": { "type": "boolean" }, "opt_out": { "type": "boolean" }, "asking_if_ai": { "type": "boolean" } } }, "stage_change": { "type": [ "string", "null" ] }, "handoff_trigger": { "type": [ "string", "null" ] }, "block_codes": { "type": "array", "items": {} }, "cost_micros": { "type": "integer" }, "latency_ms": { "type": [ "integer", "null" ] }, "provider_id": { "type": "string" }, "model": { "type": "string" }, "skipped": { "type": "string" } } }, "example": { "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "final_action": "SEND", "reply": "Chiptalar elektron, Telegram orqali yuboriladi. Yana savolingiz bormi?", "validation": { "passed": true, "disclosure": "not_needed", "gate": "SEND", "attempts": 1 }, "validation_codes": [], "gate": { "autonomy": 4, "action": "SEND", "scenario": null }, "jev_decision": { "decision_id": "jdec_01j9s3m5p7", "source": "JEV", "intent": "PRODUCT_QUESTION", "stage": "OFFER_PRESENTED", "next_action": "ANSWER_QUESTION", "interest_level": "WARM", "lead_quality": "warm", "objection": "NONE", "human_handoff": false, "opt_out": false, "asking_if_ai": false }, "stage_change": null, "handoff_trigger": null, "block_codes": [], "cost_micros": 3820, "latency_ms": 1240, "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "model": "deepseek-flash", "skipped": "" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/handoffs": { "get": { "operationId": "getAiHandoffs", "summary": "Conversations handed to people, newest first: by the AI (trigger HUMAN_REQUESTED, LOW_CONFIDENCE, COMPLAINT, PRICING_EXCEPTION, …) or taken over (MANUAL)", "description": "Conversations handed to people, newest first: by the AI (trigger HUMAN_REQUESTED, LOW_CONFIDENCE, COMPLAINT, PRICING_EXCEPTION, …) or taken over (MANUAL). status is open (default), resolved or all; assigned_user_id is a user ID, me or none.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "assigned_user_id", "in": "query", "required": false, "description": "Filter by assigned user ID.", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "required": false, "description": "Filter by conversation ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "trigger": { "type": "string" }, "ai_state": { "type": "object", "properties": { "stage": { "type": "string" }, "intent": { "type": "string" } } }, "recommended_action": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "assigned_user": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "account_id": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "hof_01j9s4g3j5m7p9r1t3v5x7z9b1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "reason": "The customer asks for a discount for a group of 40.", "trigger": "PRICING_EXCEPTION", "ai_state": { "stage": "negotiation", "intent": "group_booking" }, "recommended_action": "Offer the group rate from the price list, or call back.", "execution_id": null, "created_by": null, "assigned_user": null, "resolved_at": null, "resolved_by": null, "resolution_note": null, "created_at": "2026-09-26T09:20:00Z", "updated_at": "2026-09-26T09:20:00Z", "conversation_title": "Aziza Karimova", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/handoffs/{id}": { "patch": { "operationId": "patchAiHandoffsById", "summary": "Assign an open handoff to a member (assigned_user_id; null unassigns) and/or resolve it (resolved: true, with an optional resolution_note)", "description": "Assign an open handoff to a member (assigned_user_id; null unassigns) and/or resolve it (resolved: true, with an optional resolution_note). Resolving doesn't resume the AI; POST /ai/conversations/{id}/resume does. A resolved handoff can't change (409 handoff_resolved).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assigned_user_id": { "type": "string" }, "resolved": { "type": "boolean" }, "resolution_note": { "type": [ "string", "null" ] } } }, "example": { "assigned_user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "resolved": true, "resolution_note": "Called back and agreed the group rate." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "trigger": { "type": "string" }, "ai_state": { "type": "object", "properties": { "stage": { "type": "string" }, "intent": { "type": "string" } } }, "recommended_action": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "assigned_user": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "account_id": { "type": [ "string", "null" ] } } }, "example": { "id": "hof_01j9s4g3j5m7p9r1t3v5x7z9b1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "reason": "The customer asks for a discount for a group of 40.", "trigger": "PRICING_EXCEPTION", "ai_state": { "stage": "negotiation", "intent": "group_booking" }, "recommended_action": "Offer the group rate from the price list, or call back.", "execution_id": null, "created_by": null, "assigned_user": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "resolved_at": "2026-09-26T09:30:00Z", "resolved_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "resolution_note": "Called back and agreed the group rate.", "created_at": "2026-09-26T09:20:00Z", "updated_at": "2026-09-26T09:20:00Z", "conversation_title": "Aziza Karimova", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/drafts/{draft}/approve": { "post": { "operationId": "postAiConversationsByIdDraftsByDraftApprove", "summary": "Send a draft the AI Seller prepared (autonomy 2, or 3 outside the approved scenarios)", "description": "Send a draft the AI Seller prepared (autonomy 2, or 3 outside the approved scenarios). It goes out as the AI's message with you as sent_by, through the same consent gate and pacing as every reply; the first AI message of a conversation gets the business's disclosure line when disclosure is on. 409 draft_not_pending when it was approved, discarded or replaced by a newer draft (the customer wrote again); 409 recommendation_not_sendable for recommendations (autonomy 1: guidance, write the reply yourself); 409 reply_not_allowed when the gate refuses (the draft then stays pending). Needs an accepted acceptable-use policy.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "draft", "in": "path", "required": true, "description": "The draft.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "status": { "type": "string" }, "body_len": { "type": "integer" }, "language": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "validation": { "type": "object", "properties": { "attempts": { "type": "integer" }, "passed": { "type": "boolean" }, "disclosure": { "type": "string" }, "failures": { "type": "array", "items": {} }, "warnings": { "type": "array", "items": {} }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } } } } }, "reply_to_message_id": { "type": "string" }, "message_id": { "type": [ "string", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "type": "string" } } }, "message": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "telegram_message_id": { "type": [ "integer", "null" ] }, "external_message_id": { "type": [ "string", "null" ] }, "direction": { "type": "string" }, "author": { "type": "string" }, "body_len": { "type": "integer" }, "media_kind": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "sent_by": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "send_basis": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "edited_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "imported": { "type": "boolean" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" }, "reaction": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "recipients": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "type": "string" } } } } }, "example": { "draft": { "id": "sdr_01j9s4h4k6n8q0s2u4w6y8a0c2", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "kind": "DRAFT", "status": "APPROVED", "body_len": 92, "language": "uz", "actions": [ "ANSWER_QUESTION" ], "validation": { "attempts": 1, "passed": true, "disclosure": "added", "failures": [], "warnings": [], "checks": [ { "name": "honesty", "passed": true }, { "name": "grounding", "passed": true }, { "name": "language", "passed": true } ] }, "reply_to_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "message_id": "msg_01j9s4f2h4k6n8q0s2u4w6y8a0", "decided_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "decided_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-26T09:14:11Z", "updated_at": "2026-09-26T09:14:11Z", "body": "Bu xabarga AI yordamchi javob bermoqda.\n\nSalom! Chipta narxi 150 000 soʻm. Qaysi kunga kerak?" }, "message": { "id": "msg_01j9s4f2h4k6n8q0s2u4w6y8a0", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "telegram_message_id": null, "external_message_id": null, "direction": "OUT", "author": "AI", "body_len": 92, "media_kind": null, "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "sent_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "status": "QUEUED", "send_basis": "REPLY_WINDOW", "attempts": 0, "error_code": null, "error": null, "occurred_at": "2026-09-26T09:30:00Z", "sent_at": null, "edited_at": null, "deleted_at": null, "imported": false, "read_at": null, "reaction": null, "metadata": null, "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z", "body": "Bu xabarga AI yordamchi javob bermoqda.\n\nSalom! Chipta narxi 150 000 soʻm. Qaysi kunga kerak?" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/drafts/{draft}/discard": { "post": { "operationId": "postAiConversationsByIdDraftsByDraftDiscard", "summary": "Set a pending draft or recommendation aside (status DISCARDED)", "description": "Set a pending draft or recommendation aside (status DISCARDED). 409 draft_not_pending when it isn't pending anymore.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "draft", "in": "path", "required": true, "description": "The draft.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "draft": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "status": { "type": "string" }, "body_len": { "type": "integer" }, "language": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string" } }, "validation": { "type": "object", "properties": { "attempts": { "type": "integer" }, "passed": { "type": "boolean" }, "disclosure": { "type": "string" }, "failures": { "type": "array", "items": {} }, "warnings": { "type": "array", "items": {} }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } } } } }, "reply_to_message_id": { "type": "string" }, "message_id": { "type": [ "integer", "null" ] }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "body": { "type": "string" } } }, "message": { "type": [ "string", "null" ] } } }, "example": { "draft": { "id": "sdr_01j9s4h4k6n8q0s2u4w6y8a0c2", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "kind": "DRAFT", "status": "DISCARDED", "body_len": 92, "language": "uz", "actions": [ "ANSWER_QUESTION" ], "validation": { "attempts": 1, "passed": true, "disclosure": "added", "failures": [], "warnings": [], "checks": [ { "name": "honesty", "passed": true }, { "name": "grounding", "passed": true }, { "name": "language", "passed": true } ] }, "reply_to_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "message_id": null, "decided_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "decided_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-26T09:14:11Z", "updated_at": "2026-09-26T09:14:11Z", "body": "Bu xabarga AI yordamchi javob bermoqda.\n\nSalom! Chipta narxi 150 000 soʻm. Qaysi kunga kerak?" }, "message": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/leads": { "get": { "operationId": "getAiLeads", "summary": "The AI Seller's leads, the most recently updated first: one per conversation, opened when the customer shows interest, with the funnel stage (and its name), quality (cold, warm, hot), interest, status (OPEN; WON at the funnel's last stage; LOST when the customer opted out) and a value estimate from the prices of the offers the customer is interested in", "description": "The AI Seller's leads, the most recently updated first: one per conversation, opened when the customer shows interest, with the funnel stage (and its name), quality (cold, warm, hot), interest, status (OPEN; WON at the funnel's last stage; LOST when the customer opted out) and a value estimate from the prices of the offers the customer is interested in. Filter by business_id, stage (a stage key), quality, status, conversation_id and q (the customer's name).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "stage", "in": "query", "required": false, "description": "Filter by stage.", "schema": { "type": "string" } }, { "name": "quality", "in": "query", "required": false, "description": "Filter by quality.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "required": false, "description": "Filter by conversation ID.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "title": { "type": "string" }, "stage": { "type": "string" }, "quality": { "type": "string" }, "interest": { "type": "string" }, "status": { "type": "string" }, "value_estimate": { "type": "integer" }, "currency": { "type": "string" }, "offer_ids": { "type": "array", "items": { "type": "string" } }, "owner_user_id": { "type": [ "string", "null" ] }, "last_execution_id": { "type": "string" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "account_id": { "type": [ "string", "null" ] }, "stage_name": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "led_01j9s4j5m7p9r1t3v5x7z9b1d3", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "title": "Aziza Karimova", "stage": "OFFER_PRESENTED", "quality": "warm", "interest": "high", "status": "OPEN", "value_estimate": 150000, "currency": "UZS", "offer_ids": [ "ofr_01j9s4m7p9r1t3v5x7z9b1d3f5" ], "owner_user_id": null, "last_execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "closed_at": null, "created_at": "2026-09-26T09:14:11Z", "updated_at": "2026-09-26T09:14:11Z", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "stage_name": "Offer Presented" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/sales-pipeline": { "get": { "operationId": "getAiSalesPipeline", "summary": "Funnel snapshot: for each business's default funnel, counts of open/won/lost leads per stage with estimated total value (sum of value_estimate for open leads) and oldest open lead age in days", "description": "Funnel snapshot: for each business's default funnel, counts of open/won/lost leads per stage with estimated total value (sum of value_estimate for open leads) and oldest open lead age in days. Stage-to-stage conversion rates (derived). Filter by business_id. Each pipelineResult has kind 'mixed'; conversion rates have kind 'derived'; value_total is kind 'estimated' (from AI's value_estimate); counts are kind 'observed'.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "funnel_id": { "type": "string" }, "funnel_name": { "type": "string" }, "total_open": { "type": "integer" }, "total_won": { "type": "integer" }, "total_lost": { "type": "integer" }, "total_value": { "type": "integer" }, "kind": { "type": "string" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage_key": { "type": "string" }, "stage_name": { "type": "string" }, "position": { "type": "integer" }, "lead_count": { "type": "integer" }, "won_count": { "type": "integer" }, "lost_count": { "type": "integer" }, "value_total": { "type": "integer" }, "oldest_days": { "type": "number" } } } }, "conversions": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "leads_in": { "type": "integer" }, "leads_through": { "type": "integer" }, "rate": { "type": "number" }, "kind": { "type": "string" } } } } } } }, "example": [ { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "funnel_id": "fun_01", "funnel_name": "Default", "total_open": 12, "total_won": 4, "total_lost": 2, "total_value": 5200000, "kind": "mixed", "stages": [ { "stage_key": "AWARENESS", "stage_name": "Awareness", "position": 1, "lead_count": 5, "won_count": 0, "lost_count": 0, "value_total": 1200000, "oldest_days": 3.2 } ], "conversions": [ { "from": "AWARENESS", "to": "INTEREST", "leads_in": 12, "leads_through": 8, "rate": 66.7, "kind": "derived" } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/analytics": { "get": { "operationId": "getAiAnalytics", "summary": "Conversation and sales metrics over a time range (from/to: YYYY-MM-DD or RFC3339, default last 30 days)", "description": "Conversation and sales metrics over a time range (from/to: YYYY-MM-DD or RFC3339, default last 30 days). Each metric carries kind: observed (counted from rows) | estimated (from AI judgements) | derived (computed ratio or average) and a filter_hint pointing at the underlying rows. Metrics: conversations_started, customers_replied, ai_turns_by_action (by final_action), handoffs_by_trigger, opt_outs, leads (opened/won/lost), avg_first_reply_seconds, stage_movements. Filter by business_id.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "business_id": { "type": [ "string", "null" ] }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "number" }, "kind": { "type": "string" }, "filter_hint": { "type": "string" } } } } } }, "example": { "from": "2026-09-01T00:00:00Z", "to": "2026-09-28T00:00:00Z", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "metrics": [ { "key": "conversations_started", "value": 42, "kind": "observed", "filter_hint": "conversations.created_at in range" }, { "key": "leads", "value": { "opened": 18, "won": 5, "lost": 2 }, "kind": "observed", "filter_hint": "sales_leads.created_at / closed_at in range" }, { "key": "avg_first_reply_seconds", "value": 8, "kind": "derived", "filter_hint": "conversation_messages, first IN then first OUT in range" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/performance": { "get": { "operationId": "getAiPerformance", "summary": "Per-agent/business/model performance over a time range (from/to: YYYY-MM-DD or RFC3339, default last 30 days)", "description": "Per-agent/business/model performance over a time range (from/to: YYYY-MM-DD or RFC3339, default last 30 days). Counts runs, succeeded, failed, blocked; average latency (derived); total cost_micros; fallbacks (JEV → LLM fallback count); jev_runs (runs with a JEV decision). Validator failure codes with counts. All from ai_executions (mode=LIVE).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: conversations" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "runs": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "blocked": { "type": "integer" }, "avg_latency_ms": { "type": "integer" }, "cost_micros": { "type": "integer" }, "fallbacks": { "type": "integer" }, "jev_runs": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "kind": { "type": "string" } } } }, "validator_failures": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string" }, "count": { "type": "integer" }, "kind": { "type": "string" } } } } } }, "example": { "from": "2026-09-01T00:00:00Z", "to": "2026-09-28T00:00:00Z", "rows": [ { "agent": "SELLER", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "model": "gpt-4o-mini", "runs": 150, "succeeded": 142, "failed": 3, "blocked": 5, "avg_latency_ms": 1240, "cost_micros": 45000, "fallbacks": 12, "jev_runs": 138, "input_tokens": 210000, "output_tokens": 18000, "kind": "mixed" } ], "validator_failures": [ { "check": "honesty", "count": 2, "kind": "observed" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/knowledge/sources": { "get": { "operationId": "getAiKnowledgeSources", "summary": "Knowledge sources, newest first", "description": "Knowledge sources, newest first. version is the published version the Seller reads (0 until the first ingest finishes). status is PENDING or PROCESSING while a new version is built, READY, or FAILED with error; the last good version keeps answering meanwhile. embedding_model null means full-text search only. Lists leave out config.text and config.items: get the source for them.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Filter by kind.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "config": { "type": "object", "properties": {} }, "chunk_count": { "type": "integer" }, "token_count": { "type": "integer" }, "embedding_model": { "type": [ "string", "null" ] }, "last_ingested_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "warning": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "kns_01j9s3m5p7r9t1v3x5z7b9d1f3", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "kind": "FAQ", "title": "Yetkazib berish va to‘lov", "status": "READY", "version": 3, "config": {}, "chunk_count": 1, "token_count": 84, "embedding_model": "text-embedding-3-small", "last_ingested_at": "2026-09-26T09:30:00Z", "error": null, "warning": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" }, { "id": "kns_01j9s3q1s3u5w7y9a1c3e5g7j9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "kind": "URL", "title": "Narxlar — Silk Road Events", "status": "READY", "version": 1, "config": { "url": "https://silkroad.example/narxlar" }, "chunk_count": 4, "token_count": 2210, "embedding_model": "text-embedding-3-small", "last_ingested_at": "2026-09-26T09:30:00Z", "error": null, "warning": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiKnowledgeSources", "summary": "Add knowledge to a business: kind TEXT (title, text up to 200,000 characters), FAQ (title, items: up to 500 questions with answers), URL (url of a public page, fetched through the same address guard as custom AI providers; the title defaults to the page's) or FILE (attachment_id of an uploaded attachment)", "description": "Add knowledge to a business: kind TEXT (title, text up to 200,000 characters), FAQ (title, items: up to 500 questions with answers), URL (url of a public page, fetched through the same address guard as custom AI providers; the title defaults to the page's) or FILE (attachment_id of an uploaded attachment). The source starts PENDING and is ingested in the background. OFFER sources come from offers and can't be added here.\n\nTo upload a file, send multipart/form-data with business_id, an optional title and file: .txt, .md, .csv, .tsv or .html, UTF-8 (UTF-16 with a byte-order mark and Windows-1251 are read too), up to 5 MB. PDF and Word files are refused with 422. A business can have 500 sources (409 knowledge_source_limit); an organization can start 200 ingests (additions, edits, reindexes) an hour (429 ai_rate_limited).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "title": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } } } }, "example": { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "kind": "FAQ", "title": "Yetkazib berish va to‘lov", "items": [ { "question": "Yetkazib berish bormi?", "answer": "Ha, Toshkent bo‘ylab ertasi kuni, 30 000 so‘m. 500 000 so‘mdan ortiq buyurtmalarga bepul." }, { "question": "Qanday to‘lash mumkin?", "answer": "Click, Payme, karta yoki naqd pul bilan." } ] } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "config": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } } } }, "chunk_count": { "type": "integer" }, "token_count": { "type": "integer" }, "embedding_model": { "type": [ "string", "null" ] }, "last_ingested_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "warning": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "kns_01j9s3m5p7r9t1v3x5z7b9d1f3", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "kind": "FAQ", "title": "Yetkazib berish va to‘lov", "status": "PENDING", "version": 0, "config": { "items": [ { "question": "Yetkazib berish bormi?", "answer": "Ha, Toshkent bo‘ylab ertasi kuni, 30 000 so‘m. 500 000 so‘mdan ortiq buyurtmalarga bepul." }, { "question": "Qanday to‘lash mumkin?", "answer": "Click, Payme, karta yoki naqd pul bilan." } ] }, "chunk_count": 0, "token_count": 0, "embedding_model": null, "last_ingested_at": null, "error": null, "warning": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/knowledge/sources/{id}": { "get": { "operationId": "getAiKnowledgeSourcesById", "summary": "A knowledge source with its full config: the text, the FAQ items, the page address or the file", "description": "A knowledge source with its full config: the text, the FAQ items, the page address or the file.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "config": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } } } }, "chunk_count": { "type": "integer" }, "token_count": { "type": "integer" }, "embedding_model": { "type": [ "string", "null" ] }, "last_ingested_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "warning": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "kns_01j9s3m5p7r9t1v3x5z7b9d1f3", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "kind": "FAQ", "title": "Yetkazib berish va to‘lov", "status": "READY", "version": 3, "config": { "items": [ { "question": "Yetkazib berish bormi?", "answer": "Ha, Toshkent bo‘ylab ertasi kuni, 30 000 so‘m. 500 000 so‘mdan ortiq buyurtmalarga bepul." }, { "question": "Qanday to‘lash mumkin?", "answer": "Click, Payme, karta yoki naqd pul bilan." } ] }, "chunk_count": 1, "token_count": 84, "embedding_model": "text-embedding-3-small", "last_ingested_at": "2026-09-26T09:30:00Z", "error": null, "warning": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchAiKnowledgeSourcesById", "summary": "Change a source: title, text (TEXT), items (FAQ, the whole list) or url (URL)", "description": "Change a source: title, text (TEXT), items (FAQ, the whole list) or url (URL). A change queues a new version, and the current one keeps answering until it's ready. kind, business_id and the file can't change: add a new source instead. Offer sources follow their offer (409 knowledge_source_managed).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } } } }, "example": { "items": [ { "question": "Yetkazib berish bormi?", "answer": "Ha, Toshkent bo‘ylab ertasi kuni, 30 000 so‘m. 500 000 so‘mdan ortiq buyurtmalarga bepul." }, { "question": "Qanday to‘lash mumkin?", "answer": "Click, Payme, karta yoki naqd pul bilan." }, { "question": "Qaytarish mumkinmi?", "answer": "14 kun ichida, chek bilan." } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "config": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } } } }, "chunk_count": { "type": "integer" }, "token_count": { "type": "integer" }, "embedding_model": { "type": [ "string", "null" ] }, "last_ingested_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "warning": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "kns_01j9s3m5p7r9t1v3x5z7b9d1f3", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "kind": "FAQ", "title": "Yetkazib berish va to‘lov", "status": "PENDING", "version": 3, "config": { "items": [ { "question": "Yetkazib berish bormi?", "answer": "Ha, Toshkent bo‘ylab ertasi kuni, 30 000 so‘m. 500 000 so‘mdan ortiq buyurtmalarga bepul." }, { "question": "Qanday to‘lash mumkin?", "answer": "Click, Payme, karta yoki naqd pul bilan." } ] }, "chunk_count": 1, "token_count": 84, "embedding_model": "text-embedding-3-small", "last_ingested_at": "2026-09-26T09:30:00Z", "error": null, "warning": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiKnowledgeSourcesById", "summary": "Delete a source with every version of it", "description": "Delete a source with every version of it. A file uploaded for it is deleted too, unless a campaign uses it.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/knowledge/sources/{id}/reindex": { "post": { "operationId": "postAiKnowledgeSourcesByIdReindex", "summary": "Build a new version of a source: its text is chunked again, a page fetched again, and everything embedded with the current embedding model", "description": "Build a new version of a source: its text is chunked again, a page fetched again, and everything embedded with the current embedding model. Answers 202 with the source, now PENDING; it counts toward the hourly ingest limit.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "integer" }, "config": { "type": "object", "properties": { "url": { "type": "string" } } }, "chunk_count": { "type": "integer" }, "token_count": { "type": "integer" }, "embedding_model": { "type": [ "string", "null" ] }, "last_ingested_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "warning": { "type": [ "string", "null" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "kns_01j9s3q1s3u5w7y9a1c3e5g7j9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "kind": "URL", "title": "Narxlar — Silk Road Events", "status": "PENDING", "version": 1, "config": { "url": "https://silkroad.example/narxlar" }, "chunk_count": 4, "token_count": 2210, "embedding_model": "text-embedding-3-small", "last_ingested_at": "2026-09-26T09:30:00Z", "error": null, "warning": null, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/knowledge/search": { "get": { "operationId": "getAiKnowledgeSearch", "summary": "Retrieve knowledge the way the Seller does, to test it: q is what a customer might write (up to 1,000 characters)", "description": "Retrieve knowledge the way the Seller does, to test it: q is what a customer might write (up to 1,000 characters). Retrieval is hybrid: full-text matching of the query's words (oʻ, o' and o match, as do ё and е, and fuzzy matching catches word forms and typos) and, with an embedding provider, similarity of meaning. why says what matched: fts (words), vector (meaning only) or both. Hits fit within budget estimated tokens (default 2,000); limit is 1 to 50 (default 5).\n\nmode is hybrid when the query was embedded, else full_text. strategy is exhaustive when every chunk of the business was scored (knowledge bases up to 256 chunks), prefilter when full-text matching chose the candidates. 600 searches per organization per hour.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Filter by kind.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "budget", "in": "query", "required": false, "description": "Filter by budget.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "chunk_id": { "type": "string" }, "source_id": { "type": "string" }, "document_id": { "type": "string" }, "kind": { "type": "string" }, "version": { "type": "integer" }, "title": { "type": "string" }, "heading": { "type": "string" }, "content": { "type": "string" }, "tokens": { "type": "integer" }, "score": { "type": "number" }, "why": { "type": "string" }, "lexical": { "type": "integer" }, "vector": { "type": "number" } } } }, "mode": { "type": "string" }, "strategy": { "type": "string" }, "embedding_model": { "type": [ "string", "null" ] }, "words": { "type": "array", "items": { "type": "string" } }, "candidates": { "type": "integer" }, "tokens": { "type": "integer" } } }, "example": { "data": [ { "chunk_id": "knc_01j9s5p7r9t1v3x5z7b9d1f3h5", "source_id": "kns_01j9s3m5p7r9t1v3x5z7b9d1f3", "document_id": "knd_01j9s4n6q8s0u2w4y6a8c0e2g4", "kind": "FAQ", "version": 3, "title": "Yetkazib berish va to‘lov", "heading": "Yetkazib berish bormi?", "content": "## Yetkazib berish bormi?\n\nHa, Toshkent bo‘ylab ertasi kuni, 30 000 so‘m. 500 000 so‘mdan ortiq buyurtmalarga bepul.", "tokens": 44, "score": 0.8412, "why": "both", "lexical": 1, "vector": 0.7353 } ], "mode": "hybrid", "strategy": "exhaustive", "embedding_model": "text-embedding-3-small", "words": [ "yetkazib", "berish", "bormi" ], "candidates": 7, "tokens": 44 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/memory": { "get": { "operationId": "getAiMemory", "summary": "What the Seller remembers, most recently updated first: facts about customers (LONG_TERM), conversation notes (SHORT_TERM, MEDIUM_TERM), BUSINESS and SYSTEM memories, with importance, confidence and where each came from (source_type MESSAGE, EXECUTION, MANUAL or SYSTEM)", "description": "What the Seller remembers, most recently updated first: facts about customers (LONG_TERM), conversation notes (SHORT_TERM, MEDIUM_TERM), BUSINESS and SYSTEM memories, with importance, confidence and where each came from (source_type MESSAGE, EXECUTION, MANUAL or SYSTEM). status is ACTIVE by default; SUPERSEDED memories were replaced by a changed fact (superseded_by), EXPIRED ones are about to be deleted. type and status take several values separated by commas.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "recipient_id", "in": "query", "required": false, "description": "Filter by recipient ID.", "schema": { "type": "string" } }, { "name": "telegram_user_id", "in": "query", "required": false, "description": "Filter by telegram user ID.", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "required": false, "description": "Filter by conversation ID.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Event types separated by commas; campaign.* matches a prefix.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "recipient_id": { "type": "string" }, "telegram_user_id": { "type": "integer" }, "type": { "type": "string" }, "key": { "type": "string" }, "content": { "type": "string" }, "importance": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "source_type": { "type": "string" }, "source_id": { "type": "string" }, "embedding_model": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "superseded_by": { "type": [ "string", "null" ] }, "superseded_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "mry_01j9s6q8s0u2w4y6a8c0e2g4j6", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s7r9t1v3x5z7b9d1f3h5k7", "recipient_id": "rcp_01j9r5b3d5f7h9k1m3p5r7t9v1", "telegram_user_id": 5712093344, "type": "LONG_TERM", "key": "budget", "content": "Byudjeti taxminan 5 million so‘m.", "importance": 0.8, "confidence": 0.9, "source_type": "EXECUTION", "source_id": "aix_01j9s8s0u2w4y6a8c0e2g4j6m8", "embedding_model": null, "expires_at": null, "superseded_by": null, "superseded_at": null, "status": "ACTIVE", "created_at": "2026-09-25T14:02:11Z", "updated_at": "2026-09-26T09:30:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/memory/{id}": { "delete": { "operationId": "deleteAiMemoryById", "summary": "Forget a memory for good, with the older statements of the same fact it replaced: for a privacy request or a wrong fact", "description": "Forget a memory for good, with the older statements of the same fact it replaced: for a privacy request or a wrong fact. The deletion is kept in the audit log and the memory's history, without the content.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/research": { "post": { "operationId": "postAiResearch", "summary": "Start a research job for a business subject (company name + optional website)", "description": "Start a research job for a business subject (company name + optional website). The agent fetches the website, optionally queries a configured search provider, then calls the LLM to produce a structured report. Every fact cites an evidence URL that was actually fetched. The agent refuses private individuals (422 private_individual). Rate-limited to 20 per organization per hour. While the platform's research switch (ai_research_enabled, or AI as a whole) is off, nothing is created: 409 research_disabled. A job queued before the switch went off ends FAILED with the reason in error_message instead of staying PENDING. Audited.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject_name": { "type": "string" }, "subject_website": { "type": "string" }, "business_id": { "type": [ "string", "null" ] } } }, "example": { "subject_name": "Nexgen Solutions", "subject_website": "https://nexgen-solutions.example.com", "business_id": "biz_01j9..." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "subject_name": { "type": "string" }, "subject_website": { "type": "string" }, "status": { "type": "string" }, "requested_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "rsj_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "subject_name": "Nexgen Solutions", "subject_website": "https://nexgen-solutions.example.com", "status": "PENDING", "requested_by": "usr_01j9...", "created_at": "2026-09-27T12:00:00Z", "updated_at": "2026-09-27T12:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getAiResearch", "summary": "List research jobs for the organization, newest first", "description": "List research jobs for the organization, newest first. Supports ?limit=, ?offset= and ?status= (PENDING | RUNNING | SUCCEEDED | FAILED).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "subject_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "rsj_01j9...", "subject_name": "Nexgen Solutions", "status": "SUCCEEDED", "created_at": "2026-09-27T12:00:00Z" } ], "total": 1, "limit": 25, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/research/{id}": { "get": { "operationId": "getAiResearchById", "summary": "Get a research job and its report (when status is SUCCEEDED)", "description": "Get a research job and its report (when status is SUCCEEDED). The report contains a summary, a list of facts each with an evidence URL and confidence score, and a retrieved_at timestamp. Returns job even while PENDING or RUNNING.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "subject_name": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "report": { "type": "object", "properties": { "summary": { "type": "string" }, "facts": { "type": "array", "items": { "type": "object", "properties": { "claim": { "type": "string" }, "evidence_url": { "type": "string" }, "confidence": { "type": [ "number", "null" ] } } } }, "retrieved_at": { "type": "string", "format": "date-time" } } } } }, "example": { "job": { "id": "rsj_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "subject_name": "Nexgen Solutions", "status": "SUCCEEDED", "created_at": "2026-09-27T12:00:00Z", "completed_at": "2026-09-27T12:02:30Z" }, "report": { "summary": "Nexgen Solutions is a B2B software company founded in 2018, specializing in ERP integrations for mid-market manufacturers in Central Asia.", "facts": [ { "claim": "Founded in 2018", "evidence_url": "https://nexgen-solutions.example.com/about", "confidence": 0.95 }, { "claim": "Serves 120+ clients in Uzbekistan and Kazakhstan", "evidence_url": "https://nexgen-solutions.example.com/customers", "confidence": 0.87 } ], "retrieved_at": "2026-09-27T12:02:25Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/research/{id}/save-to-knowledge": { "post": { "operationId": "postAiResearchByIdSaveToKnowledge", "summary": "Save a completed research report as a TEXT knowledge source linked to a business", "description": "Save a completed research report as a TEXT knowledge source linked to a business. The report's summary and facts are formatted as readable text. Requires the job to be SUCCEEDED. Audited.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: knowledge and memory" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "title": { "type": "string" } } }, "example": { "business_id": "biz_01j9...", "title": "Research: Nexgen Solutions" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "ks_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9...", "kind": "TEXT", "title": "Research: Nexgen Solutions", "status": "PENDING", "created_at": "2026-09-27T12:03:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/jev": { "get": { "operationId": "getAiJev", "summary": "JEV settings: whether it's on, has_key and key_hint (the key itself is never returned), key_source (the key decisions use now: ORGANIZATION, PLATFORM when the platform provides one, or NONE), the effective per-field confidence thresholds with the defaults and your overrides, when data sharing was accepted, and disclosure, which lists what goes to TypeSafe", "description": "JEV settings: whether it's on, has_key and key_hint (the key itself is never returned), key_source (the key decisions use now: ORGANIZATION, PLATFORM when the platform provides one, or NONE), the effective per-field confidence thresholds with the defaults and your overrides, when data sharing was accepted, and disclosure, which lists what goes to TypeSafe.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: decisions" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "has_key": { "type": "boolean" }, "key_hint": { "type": [ "string", "null" ] }, "key_source": { "type": "string" }, "platform_key_available": { "type": "boolean" }, "thresholds": { "type": "object", "properties": { "intent": { "type": "number" }, "stage": { "type": "number" }, "advance_stage": { "type": "number" }, "next_action": { "type": "number" }, "interest": { "type": "number" }, "lead_quality": { "type": "number" }, "objection": { "type": "number" }, "human_handoff": { "type": "number" }, "calendar_intent": { "type": "number" }, "needs_knowledge": { "type": "number" }, "opt_out_request": { "type": "number" }, "is_asking_if_ai": { "type": "number" } } }, "default_thresholds": { "type": "object", "properties": { "intent": { "type": "number" }, "stage": { "type": "number" }, "advance_stage": { "type": "number" }, "next_action": { "type": "number" }, "interest": { "type": "number" }, "lead_quality": { "type": "number" }, "objection": { "type": "number" }, "human_handoff": { "type": "number" }, "calendar_intent": { "type": "number" }, "needs_knowledge": { "type": "number" }, "opt_out_request": { "type": "number" }, "is_asking_if_ai": { "type": "number" } } }, "threshold_overrides": { "type": "object", "properties": { "next_action": { "type": "number" } } }, "data_sharing_accepted_at": { "type": "string", "format": "date-time" }, "data_sharing_accepted_by": { "type": "string" }, "model": { "type": "string" }, "disclosure": { "type": "object", "properties": { "processor": { "type": "string" }, "endpoint": { "type": "string" }, "sent": { "type": "array", "items": { "type": "string" } }, "masked_before_sending": { "type": "array", "items": { "type": "string" } }, "never_sent": { "type": "array", "items": { "type": "string" } } } }, "updated_by": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "enabled": true, "has_key": true, "key_hint": "•••• 7c1e", "key_source": "ORGANIZATION", "platform_key_available": false, "thresholds": { "intent": 0.5, "stage": 0.5, "advance_stage": 0.6, "next_action": 0.7, "interest": 0.5, "lead_quality": 0.5, "objection": 0.5, "human_handoff": 0.6, "calendar_intent": 0.6, "needs_knowledge": 0.5, "opt_out_request": 0.6, "is_asking_if_ai": 0.6 }, "default_thresholds": { "intent": 0.5, "stage": 0.5, "advance_stage": 0.6, "next_action": 0.5, "interest": 0.5, "lead_quality": 0.5, "objection": 0.5, "human_handoff": 0.6, "calendar_intent": 0.6, "needs_knowledge": 0.5, "opt_out_request": 0.6, "is_asking_if_ai": 0.6 }, "threshold_overrides": { "next_action": 0.7 }, "data_sharing_accepted_at": "2026-09-27T08:12:00Z", "data_sharing_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "model": "jev-latest", "disclosure": { "processor": "TypeSafe (System One)", "endpoint": "https://api.typesafe.ai/v1/systemone", "sent": [ "latest_customer_message", "conversation_summary", "current_and_next_stage", "funnel_stage_objectives", "allowed_actions", "known_needs", "known_objections", "offer_names", "language", "decision_questions" ], "masked_before_sending": [ "card_numbers", "phone_numbers", "email_addresses", "key_like_strings" ], "never_sent": [ "conversation_history", "customer_profile", "telegram_ids", "organization_and_business_ids", "api_keys_and_secrets" ] }, "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_at": "2026-09-26T09:30:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAiJev", "summary": "Change the settings; fields you leave out keep their value", "description": "Change the settings; fields you leave out keep their value. Turning JEV on needs accept_data_sharing: true once, which records who accepted and when. api_key: a new TypeSafe key replaces the saved one, \"\" keeps it, null removes it (decisions then use the platform key, if provided). thresholds replaces your overrides: numbers from 0 to 1 per field; a field left out or null uses its default, and null for the whole object clears them. A choice or score's confidence is JEV's own; a yes/no field's is its distance from 0.5, doubled, so 0.6 needs a probability of at least 0.8 or at most 0.2.\n\nAudited as AI_JEV_SETTINGS_UPDATED, without the key. Turning JEV on without accepting data sharing is 422 with details.accept_data_sharing.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: decisions" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "accept_data_sharing": { "type": "boolean" }, "api_key": { "type": "string" }, "thresholds": { "type": "object", "properties": { "next_action": { "type": "number" } } } } }, "example": { "enabled": true, "accept_data_sharing": true, "api_key": "ts-…", "thresholds": { "next_action": 0.7 } } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "has_key": { "type": "boolean" }, "key_hint": { "type": [ "string", "null" ] }, "key_source": { "type": "string" }, "platform_key_available": { "type": "boolean" }, "thresholds": { "type": "object", "properties": { "intent": { "type": "number" }, "stage": { "type": "number" }, "advance_stage": { "type": "number" }, "next_action": { "type": "number" }, "interest": { "type": "number" }, "lead_quality": { "type": "number" }, "objection": { "type": "number" }, "human_handoff": { "type": "number" }, "calendar_intent": { "type": "number" }, "needs_knowledge": { "type": "number" }, "opt_out_request": { "type": "number" }, "is_asking_if_ai": { "type": "number" } } }, "default_thresholds": { "type": "object", "properties": { "intent": { "type": "number" }, "stage": { "type": "number" }, "advance_stage": { "type": "number" }, "next_action": { "type": "number" }, "interest": { "type": "number" }, "lead_quality": { "type": "number" }, "objection": { "type": "number" }, "human_handoff": { "type": "number" }, "calendar_intent": { "type": "number" }, "needs_knowledge": { "type": "number" }, "opt_out_request": { "type": "number" }, "is_asking_if_ai": { "type": "number" } } }, "threshold_overrides": { "type": "object", "properties": { "next_action": { "type": "number" } } }, "data_sharing_accepted_at": { "type": "string", "format": "date-time" }, "data_sharing_accepted_by": { "type": "string" }, "model": { "type": "string" }, "disclosure": { "type": "object", "properties": { "processor": { "type": "string" }, "endpoint": { "type": "string" }, "sent": { "type": "array", "items": { "type": "string" } }, "masked_before_sending": { "type": "array", "items": { "type": "string" } }, "never_sent": { "type": "array", "items": { "type": "string" } } } }, "updated_by": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "enabled": true, "has_key": true, "key_hint": "•••• 7c1e", "key_source": "ORGANIZATION", "platform_key_available": false, "thresholds": { "intent": 0.5, "stage": 0.5, "advance_stage": 0.6, "next_action": 0.7, "interest": 0.5, "lead_quality": 0.5, "objection": 0.5, "human_handoff": 0.6, "calendar_intent": 0.6, "needs_knowledge": 0.5, "opt_out_request": 0.6, "is_asking_if_ai": 0.6 }, "default_thresholds": { "intent": 0.5, "stage": 0.5, "advance_stage": 0.6, "next_action": 0.5, "interest": 0.5, "lead_quality": 0.5, "objection": 0.5, "human_handoff": 0.6, "calendar_intent": 0.6, "needs_knowledge": 0.5, "opt_out_request": 0.6, "is_asking_if_ai": 0.6 }, "threshold_overrides": { "next_action": 0.7 }, "data_sharing_accepted_at": "2026-09-27T08:12:00Z", "data_sharing_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "model": "jev-latest", "disclosure": { "processor": "TypeSafe (System One)", "endpoint": "https://api.typesafe.ai/v1/systemone", "sent": [ "latest_customer_message", "conversation_summary", "current_and_next_stage", "funnel_stage_objectives", "allowed_actions", "known_needs", "known_objections", "offer_names", "language", "decision_questions" ], "masked_before_sending": [ "card_numbers", "phone_numbers", "email_addresses", "key_like_strings" ], "never_sent": [ "conversation_history", "customer_profile", "telegram_ids", "organization_and_business_ids", "api_keys_and_secrets" ] }, "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_at": "2026-09-26T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/jev/test": { "post": { "operationId": "postAiJevTest", "summary": "Check a key with one decision on a synthetic customer message (\"Salom, narxi qancha?", "description": "Check a key with one decision on a synthetic customer message (\"Salom, narxi qancha? Yetkazib berish bormi?\") and a sample funnel: JEV only, whether or not JEV is on, since nothing of yours leaves Oqim. Uses the saved key, else the platform's; send api_key to try one before saving it. A failed check is still a 200: ok is false and error has the code (auth_failed, rate_limited, timeout, …) and message. The decision is stored in TEST mode.\n\nNo key to test is 409 jev_no_key. Counts toward the organization's 60 AI checks an hour (429 ai_rate_limited).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: decisions" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" } } }, "example": { "api_key": "ts-…" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "key_source": { "type": "string" }, "model": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "decision": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "intent": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "pricing_question": { "type": "integer" }, "human_request": { "type": "integer" }, "delivery": { "type": "integer" }, "product_question": { "type": "integer" }, "other": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "stage": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "greeting": { "type": "integer" }, "discovery": { "type": "number" }, "offer": { "type": "number" }, "closing": { "type": "integer" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "advance_stage": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "next_action": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "ANSWER_QUESTION": { "type": "number" }, "ASK_DISCOVERY": { "type": "number" }, "PRESENT_OFFER": { "type": "number" }, "HANDOFF": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "interest": { "type": "object", "properties": { "value": { "type": "number" }, "level": { "type": "string" }, "levels": { "type": "integer" }, "probabilities": { "type": "object", "properties": { "none": { "type": "number" }, "low": { "type": "integer" }, "moderate": { "type": "integer" }, "high": { "type": "integer" }, "very_high": { "type": "integer" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "lead_quality": { "type": "object", "properties": { "value": { "type": "number" }, "level": { "type": "string" }, "levels": { "type": "integer" }, "probabilities": { "type": "object", "properties": { "cold": { "type": "integer" }, "warm": { "type": "number" }, "hot": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "objection": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "none": { "type": "number" }, "price": { "type": "number" }, "other": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "human_handoff": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "calendar_intent": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "needs_knowledge": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "opt_out_request": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "is_asking_if_ai": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "jev_status": { "type": "string" }, "key_source": { "type": "string" }, "model": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] } } } } }, "example": { "ok": true, "key_source": "ORGANIZATION", "model": "jev-1.13.0", "latency_ms": 1416, "error": null, "decision": { "id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "source": "JEV", "intent": { "value": "pricing_question", "probabilities": { "pricing_question": 1, "human_request": 0, "delivery": 0, "product_question": 0, "other": 0 }, "confidence": 1, "threshold": 0.5, "trusted": true, "source": "JEV" }, "stage": { "value": "discovery", "probabilities": { "greeting": 0, "discovery": 0.92, "offer": 0.08, "closing": 0 }, "confidence": 0.89, "threshold": 0.5, "trusted": true, "source": "JEV" }, "advance_stage": { "value": false, "probability": 0.29, "confidence": 0.42, "threshold": 0.6, "trusted": false, "source": "JEV" }, "next_action": { "value": "ANSWER_QUESTION", "probabilities": { "ANSWER_QUESTION": 0.7, "ASK_DISCOVERY": 0.18, "PRESENT_OFFER": 0.1, "HANDOFF": 0.02 }, "confidence": 0.65, "threshold": 0.7, "trusted": false, "source": "JEV" }, "interest": { "value": 4, "level": "high", "levels": 5, "probabilities": { "none": 0, "low": 0, "moderate": 0, "high": 1, "very_high": 0 }, "confidence": 1, "threshold": 0.5, "trusted": true, "source": "JEV" }, "lead_quality": { "value": 2.06, "level": "warm", "levels": 3, "probabilities": { "cold": 0, "warm": 0.94, "hot": 0.06 }, "confidence": 0.92, "threshold": 0.5, "trusted": true, "source": "JEV" }, "objection": { "value": "none", "probabilities": { "none": 0.87, "price": 0.12, "other": 0.01 }, "confidence": 0.86, "threshold": 0.5, "trusted": true, "source": "JEV" }, "human_handoff": { "value": false, "probability": 0.04, "confidence": 0.92, "threshold": 0.6, "trusted": true, "source": "JEV" }, "calendar_intent": { "value": false, "probability": 0.02, "confidence": 0.96, "threshold": 0.6, "trusted": true, "source": "JEV" }, "needs_knowledge": { "value": true, "probability": 0.95, "confidence": 0.9, "threshold": 0.5, "trusted": true, "source": "JEV" }, "opt_out_request": { "value": false, "probability": 0.01, "confidence": 0.98, "threshold": 0.6, "trusted": true, "source": "JEV" }, "is_asking_if_ai": { "value": false, "probability": 0.01, "confidence": 0.98, "threshold": 0.6, "trusted": true, "source": "JEV" }, "jev_status": "OK", "key_source": "ORGANIZATION", "model": "jev-1.13.0", "latency_ms": 1416 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/jev/decisions/{id}": { "get": { "operationId": "getAiJevDecisionsById", "summary": "One stored decision: its mode (LIVE, PLAYGROUND, EVAL or TEST), source (JEV, LLM, MIXED or NONE), jev_status (OK, ERROR, DISABLED or NO_KEY), the questions asked, the answers (JEV's as received, the fallback model's normalized), the decision with every field's value, probabilities, confidence, threshold, trusted flag and source, the thresholds applied, the input's sizes (never its text), latency and tokens", "description": "One stored decision: its mode (LIVE, PLAYGROUND, EVAL or TEST), source (JEV, LLM, MIXED or NONE), jev_status (OK, ERROR, DISABLED or NO_KEY), the questions asked, the answers (JEV's as received, the fallback model's normalized), the decision with every field's value, probabilities, confidence, threshold, trusted flag and source, the thresholds applied, the input's sizes (never its text), latency and tokens.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: decisions" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "execution_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "mode": { "type": "string" }, "source": { "type": "string" }, "jev_status": { "type": "string" }, "key_source": { "type": "string" }, "model": { "type": "string" }, "questions": { "type": "object", "properties": { "intent": { "type": "object", "properties": { "type": { "type": "string" }, "instructions": { "type": "string" }, "criteria": { "type": "object", "properties": { "pricing_question": { "type": "string" } } } } }, "advance_stage": { "type": "object", "properties": { "type": { "type": "string" }, "instructions": { "type": "string" }, "criteria": { "type": "object", "properties": { "true": { "type": "string" }, "false": { "type": "string" } } } } } } }, "answers": { "type": "object", "properties": { "jev": { "type": "object", "properties": { "intent": { "type": "object", "properties": { "type": { "type": "string" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "properties": { "pricing_question": { "type": "integer" }, "delivery": { "type": "integer" } } }, "confidence": { "type": [ "number", "null" ] } } }, "interest": { "type": "object", "properties": { "type": { "type": "string" }, "score": { "type": "number" }, "legend": { "type": "object", "properties": { "0": { "type": "string" }, "3": { "type": "string" }, "4": { "type": "string" } } }, "probabilities": { "type": "object", "properties": { "0": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" } } }, "confidence": { "type": [ "number", "null" ] } } } } } } }, "decision": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "intent": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "pricing_question": { "type": "integer" }, "human_request": { "type": "integer" }, "delivery": { "type": "integer" }, "product_question": { "type": "integer" }, "other": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "stage": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "greeting": { "type": "integer" }, "discovery": { "type": "number" }, "offer": { "type": "number" }, "closing": { "type": "integer" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "advance_stage": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "next_action": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "ANSWER_QUESTION": { "type": "number" }, "ASK_DISCOVERY": { "type": "number" }, "PRESENT_OFFER": { "type": "number" }, "HANDOFF": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "interest": { "type": "object", "properties": { "value": { "type": "number" }, "level": { "type": "string" }, "levels": { "type": "integer" }, "probabilities": { "type": "object", "properties": { "none": { "type": "number" }, "low": { "type": "integer" }, "moderate": { "type": "integer" }, "high": { "type": "integer" }, "very_high": { "type": "integer" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "lead_quality": { "type": "object", "properties": { "value": { "type": "number" }, "level": { "type": "string" }, "levels": { "type": "integer" }, "probabilities": { "type": "object", "properties": { "cold": { "type": "integer" }, "warm": { "type": "number" }, "hot": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "objection": { "type": "object", "properties": { "value": { "type": "string" }, "probabilities": { "type": "object", "properties": { "none": { "type": "number" }, "price": { "type": "number" }, "other": { "type": "number" } } }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "human_handoff": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "calendar_intent": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "needs_knowledge": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "opt_out_request": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "is_asking_if_ai": { "type": "object", "properties": { "value": { "type": "boolean" }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "threshold": { "type": "number" }, "trusted": { "type": "boolean" }, "source": { "type": "string" } } }, "jev_status": { "type": "string" }, "key_source": { "type": "string" }, "model": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] } } }, "thresholds": { "type": "object", "properties": { "intent": { "type": "number" }, "stage": { "type": "number" }, "advance_stage": { "type": "number" }, "next_action": { "type": "number" }, "interest": { "type": "number" }, "lead_quality": { "type": "number" }, "objection": { "type": "number" }, "human_handoff": { "type": "number" }, "calendar_intent": { "type": "number" }, "needs_knowledge": { "type": "number" }, "opt_out_request": { "type": "number" }, "is_asking_if_ai": { "type": "number" } } }, "input": { "type": "object", "properties": { "message_chars": { "type": "integer" }, "summary_chars": { "type": "integer" }, "current_stage": { "type": "string" }, "stages": { "type": "integer" }, "allowed_actions": { "type": "integer" }, "needs": { "type": "integer" }, "objections": { "type": "integer" }, "offers": { "type": "integer" }, "language": { "type": "string" }, "masked": { "type": "integer" }, "truncated": { "type": "boolean" } } }, "fallback_fields": { "type": "array", "items": {} }, "llm_provider_id": { "type": [ "string", "null" ] }, "llm_model": { "type": [ "string", "null" ] }, "latency_ms": { "type": [ "integer", "null" ] }, "jev_latency_ms": { "type": "integer" }, "llm_latency_ms": { "type": [ "integer", "null" ] }, "jev_input_tokens": { "type": "integer" }, "jev_output_tokens": { "type": "integer" }, "llm_input_tokens": { "type": "integer" }, "llm_output_tokens": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": null, "execution_id": null, "conversation_id": null, "mode": "TEST", "source": "JEV", "jev_status": "OK", "key_source": "ORGANIZATION", "model": "jev-1.13.0", "questions": { "intent": { "type": "choice", "instructions": "What does the customer mainly want with their latest message? …", "criteria": { "pricing_question": "Asks about price, cost, discounts, payment terms or installments" } }, "advance_stage": { "type": "noul", "instructions": "The customer's latest message meets the objective of the current stage …", "criteria": { "true": "…", "false": "…" } } }, "answers": { "jev": { "intent": { "type": "choice", "choice": "pricing_question", "probabilities": { "pricing_question": 1, "delivery": 0 }, "confidence": 1 }, "interest": { "type": "score", "score": 3, "legend": { "0": "None: …", "3": "High: …", "4": "Very high: …" }, "probabilities": { "0": 0, "3": 1, "4": 0 }, "confidence": 1 } } }, "decision": { "id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "source": "JEV", "intent": { "value": "pricing_question", "probabilities": { "pricing_question": 1, "human_request": 0, "delivery": 0, "product_question": 0, "other": 0 }, "confidence": 1, "threshold": 0.5, "trusted": true, "source": "JEV" }, "stage": { "value": "discovery", "probabilities": { "greeting": 0, "discovery": 0.92, "offer": 0.08, "closing": 0 }, "confidence": 0.89, "threshold": 0.5, "trusted": true, "source": "JEV" }, "advance_stage": { "value": false, "probability": 0.29, "confidence": 0.42, "threshold": 0.6, "trusted": false, "source": "JEV" }, "next_action": { "value": "ANSWER_QUESTION", "probabilities": { "ANSWER_QUESTION": 0.7, "ASK_DISCOVERY": 0.18, "PRESENT_OFFER": 0.1, "HANDOFF": 0.02 }, "confidence": 0.65, "threshold": 0.7, "trusted": false, "source": "JEV" }, "interest": { "value": 4, "level": "high", "levels": 5, "probabilities": { "none": 0, "low": 0, "moderate": 0, "high": 1, "very_high": 0 }, "confidence": 1, "threshold": 0.5, "trusted": true, "source": "JEV" }, "lead_quality": { "value": 2.06, "level": "warm", "levels": 3, "probabilities": { "cold": 0, "warm": 0.94, "hot": 0.06 }, "confidence": 0.92, "threshold": 0.5, "trusted": true, "source": "JEV" }, "objection": { "value": "none", "probabilities": { "none": 0.87, "price": 0.12, "other": 0.01 }, "confidence": 0.86, "threshold": 0.5, "trusted": true, "source": "JEV" }, "human_handoff": { "value": false, "probability": 0.04, "confidence": 0.92, "threshold": 0.6, "trusted": true, "source": "JEV" }, "calendar_intent": { "value": false, "probability": 0.02, "confidence": 0.96, "threshold": 0.6, "trusted": true, "source": "JEV" }, "needs_knowledge": { "value": true, "probability": 0.95, "confidence": 0.9, "threshold": 0.5, "trusted": true, "source": "JEV" }, "opt_out_request": { "value": false, "probability": 0.01, "confidence": 0.98, "threshold": 0.6, "trusted": true, "source": "JEV" }, "is_asking_if_ai": { "value": false, "probability": 0.01, "confidence": 0.98, "threshold": 0.6, "trusted": true, "source": "JEV" }, "jev_status": "OK", "key_source": "ORGANIZATION", "model": "jev-1.13.0", "latency_ms": 1416 }, "thresholds": { "intent": 0.5, "stage": 0.5, "advance_stage": 0.6, "next_action": 0.7, "interest": 0.5, "lead_quality": 0.5, "objection": 0.5, "human_handoff": 0.6, "calendar_intent": 0.6, "needs_knowledge": 0.5, "opt_out_request": 0.6, "is_asking_if_ai": 0.6 }, "input": { "message_chars": 43, "summary_chars": 0, "current_stage": "discovery", "stages": 4, "allowed_actions": 3, "needs": 1, "objections": 0, "offers": 2, "language": "uz", "masked": 0, "truncated": false }, "fallback_fields": [], "llm_provider_id": null, "llm_model": null, "latency_ms": 1416, "jev_latency_ms": 1416, "llm_latency_ms": null, "jev_input_tokens": 2233, "jev_output_tokens": 471, "llm_input_tokens": 0, "llm_output_tokens": 0, "error": null, "created_at": "2026-09-26T09:30:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/feedback": { "post": { "operationId": "postAiFeedback", "summary": "Submit feedback on an AI reply: optional execution_id, conversation_id, message_id, labels (GOOD, WRONG_FACT, WRONG_TONE, TOO_LONG, MISSED_OPPORTUNITY, SHOULD_HANDOFF, UNSAFE, OTHER), rating (1–5), tags, explanation, corrected_reply, suggested_response", "description": "Submit feedback on an AI reply: optional execution_id, conversation_id, message_id, labels (GOOD, WRONG_FACT, WRONG_TONE, TOO_LONG, MISSED_OPPORTUNITY, SHOULD_HANDOFF, UNSAFE, OTHER), rating (1–5), tags, explanation, corrected_reply, suggested_response. Set request_review: true to request a human review immediately.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "execution_id": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "integer" }, "explanation": { "type": "string" }, "corrected_reply": { "type": "string" } } }, "example": { "execution_id": "aix_01j9...", "labels": [ "WRONG_FACT" ], "rating": 2, "explanation": "The price is 120,000, not 150,000.", "corrected_reply": "Our price is 120,000 UZS." } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "labels": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } }, "review_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "afb_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "labels": [ "WRONG_FACT" ], "rating": 2, "tags": [], "review_requested_at": null, "created_at": "2026-09-27T10:00:00Z", "updated_at": "2026-09-27T10:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getAiFeedback", "summary": "List feedback, most-recent first", "description": "List feedback, most-recent first. Optional execution_id and conversation_id filters.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "execution_id", "in": "query", "required": false, "description": "Filter by execution ID.", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "required": false, "description": "Filter by conversation ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "afb_01j9...", "labels": [ "GOOD" ], "rating": 5 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/feedback/{id}": { "get": { "operationId": "getAiFeedbackById", "summary": "One feedback item", "description": "One feedback item. The explanation, corrected_reply and suggested_response fields are unsealed and returned in plain text.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "integer" }, "explanation": { "type": "string" } } }, "example": { "id": "afb_01j9...", "labels": [ "WRONG_FACT" ], "rating": 2, "explanation": "The price is 120,000, not 150,000." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/feedback/{id}/review": { "post": { "operationId": "postAiFeedbackByIdReview", "summary": "Mark this feedback item as review-requested and enqueue a review card task", "description": "Mark this feedback item as review-requested and enqueue a review card task. Idempotent: a second call on an already-requested item is a no-op.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/eval-datasets": { "post": { "operationId": "postAiEvalDatasets", "summary": "Create an evaluation dataset: name (required), optional business_id and description", "description": "Create an evaluation dataset: name (required), optional business_id and description.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "business_id": { "type": [ "string", "null" ] } } }, "example": { "name": "Seller v2 — price objections", "description": "Items where the customer asked about price.", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "item_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "eds_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Seller v2 — price objections", "item_count": 0, "created_at": "2026-09-27T10:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getAiEvalDatasets", "summary": "List evaluation datasets, most-recent first", "description": "List evaluation datasets, most-recent first.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "item_count": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "eds_01j9...", "name": "Seller v2 — price objections", "item_count": 12 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/eval-datasets/{id}": { "get": { "operationId": "getAiEvalDatasetsById", "summary": "One evaluation dataset", "description": "One evaluation dataset.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "item_count": { "type": "integer" } } }, "example": { "id": "eds_01j9...", "name": "Seller v2 — price objections", "item_count": 12 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiEvalDatasetsById", "summary": "Delete a dataset and all its items", "description": "Delete a dataset and all its items. Refused while an evaluation referencing it is RUNNING.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/eval-datasets/{id}/items": { "post": { "operationId": "postAiEvalDatasetsByIdItems", "summary": "Add one item to the dataset: source (MANUAL or FEEDBACK), optional feedback_id, meta (topic, notes, tags), conversation (list of {direction, author, text} snapshots), reference_reply (the expected reply to score candidates against)", "description": "Add one item to the dataset: source (MANUAL or FEEDBACK), optional feedback_id, meta (topic, notes, tags), conversation (list of {direction, author, text} snapshots), reference_reply (the expected reply to score candidates against). The conversation and reference_reply are sealed at rest.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string" }, "reference_reply": { "type": "string" }, "conversation": { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string" }, "author": { "type": "string" }, "text": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "topic": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } }, "example": { "source": "MANUAL", "reference_reply": "Our standard delivery is 2–3 business days, 500 UZS.", "conversation": [ { "direction": "IN", "author": "CUSTOMER", "text": "Yetkazib berish qancha turadi?" } ], "meta": { "topic": "delivery", "tags": [ "price" ] } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "dataset_id": { "type": "string" }, "source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "edi_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "dataset_id": "eds_01j9...", "source": "MANUAL", "created_at": "2026-09-27T10:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getAiEvalDatasetsByIdItems", "summary": "List items in a dataset, oldest-first", "description": "List items in a dataset, oldest-first. The conversation and reference_reply are unsealed in the response.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "reference_reply": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "edi_01j9...", "source": "MANUAL", "reference_reply": "Our standard delivery is 2–3 business days, 500 UZS." } ], "total": 12, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/evaluations": { "post": { "operationId": "postAiEvaluations", "summary": "Create an evaluation run: dataset_id and name (both required), optional business_id (else the dataset's business) and candidate_config: prompt_version_id (a Seller version of any status: DRAFT and TESTING ones are what you try out), communication_profile_id, language_profile_id, autonomy_level (0–5), and provider_id and model (every replay is pinned to exactly that provider and model, with no fallback; provider_id alone uses the provider's own model, model alone the provider the Seller's chain starts with)", "description": "Create an evaluation run: dataset_id and name (both required), optional business_id (else the dataset's business) and candidate_config: prompt_version_id (a Seller version of any status: DRAFT and TESTING ones are what you try out), communication_profile_id, language_profile_id, autonomy_level (0–5), and provider_id and model (every replay is pinned to exactly that provider and model, with no fallback; provider_id alone uses the provider's own model, model alone the provider the Seller's chain starts with). Missing keys fall back to the business's live configuration; candidate_config that isn't an object, an autonomy_level outside 0–5, a provider_id that isn't one of the organization's providers or a malformed model id is 422 (details name candidate_config.). Status starts PENDING.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "dataset_id": { "type": "string" }, "candidate_config": { "type": "object", "properties": { "prompt_version_id": { "type": "string" } } } } }, "example": { "name": "Seller v2 baseline", "dataset_id": "eds_01j9...", "candidate_config": { "prompt_version_id": "prv_01j9..." } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "items_total": { "type": "integer" }, "items_scored": { "type": "integer" }, "items_skipped": { "type": "integer" }, "total_items": { "type": "integer" }, "scored_items": { "type": "integer" }, "skipped_items": { "type": "integer" }, "avg_score": { "type": [ "number", "null" ] }, "pass_rate": { "type": [ "number", "null" ] } } }, "example": { "id": "evl_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Seller v2 baseline", "status": "PENDING", "items_total": 0, "items_scored": 0, "items_skipped": 0, "total_items": 0, "scored_items": 0, "skipped_items": 0, "avg_score": null, "pass_rate": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getAiEvaluations", "summary": "List evaluation runs, most-recent first", "description": "List evaluation runs, most-recent first.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "items_total": { "type": "integer" }, "items_scored": { "type": "integer" }, "items_skipped": { "type": "integer" }, "avg_score": { "type": [ "number", "null" ] }, "pass_rate": { "type": [ "number", "null" ] } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "evl_01j9...", "name": "Seller v2 baseline", "status": "SUCCEEDED", "items_total": 24, "items_scored": 22, "items_skipped": 2, "avg_score": 0.87, "pass_rate": 0.92 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/evaluations/{id}": { "get": { "operationId": "getAiEvaluationsById", "summary": "One evaluation run with all fields", "description": "One evaluation run with all fields. items_total is items_scored + items_skipped; avg_score and pass_rate cover the scored items only (a skipped item has no reply to judge). The same three counters are also served as total_items, scored_items and skipped_items.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "items_total": { "type": "integer" }, "items_scored": { "type": "integer" }, "items_skipped": { "type": "integer" }, "total_items": { "type": "integer" }, "scored_items": { "type": "integer" }, "skipped_items": { "type": "integer" }, "avg_score": { "type": [ "number", "null" ] }, "pass_rate": { "type": [ "number", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "id": "evl_01j9...", "status": "SUCCEEDED", "items_total": 24, "items_scored": 22, "items_skipped": 2, "total_items": 24, "scored_items": 22, "skipped_items": 2, "avg_score": 0.87, "pass_rate": 0.92, "started_at": "2026-09-27T10:01:00Z", "finished_at": "2026-09-27T10:03:12Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/evaluations/{id}/run": { "post": { "operationId": "postAiEvaluationsByIdRun", "summary": "Enqueue the evaluation run", "description": "Enqueue the evaluation run. The run must be in PENDING status. The worker replays every dataset item through the real Seller pipeline in EVAL mode (the playground's dry run with the candidate_config: nothing is sent, drafted or stored for a customer; each replay is one run at /ai/ops/runs/{execution_id}), and the judge scores the reply against the reference — with the JUDGE prompt resolved for the business (the platform default in internal/prompts/defaults/judge.md unless the organization or business has its own active version), or JEV when the organization has it configured. One result is written per item. An item whose replay couldn't run or finish (the AI budget, the platform's switches, an unknown prompt version, a pinned model that failed, no customer message) is written as SKIPPED with its reason in error_code, isn't scored and doesn't count in pass_rate; when none could be scored, the evaluation ends FAILED with the reason in error. Returns 503 when the task queue is unavailable.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/evaluations/{id}/results": { "get": { "operationId": "getAiEvaluationsByIdResults", "summary": "One page of evaluation results, oldest-first: one row per dataset item", "description": "One page of evaluation results, oldest-first: one row per dataset item. status is SCORED or SKIPPED. judge_scores is a JSON map of dimension name to {score, source, explanation}. The reply is unsealed in the response. A SKIPPED row has error_code (no_customer_message, budget, blocked, invalid_candidate, replay_failed or no_business) and error instead of scores.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "item_id": { "type": "string" }, "status": { "type": "string" }, "overall_score": { "type": [ "number", "null" ] }, "pass": { "type": [ "boolean", "null" ] }, "judge_scores": { "type": "object", "properties": { "tone": { "type": "object", "properties": { "score": { "type": "number" }, "source": { "type": "string" } } }, "correctness": { "type": "object", "properties": { "score": { "type": "number" }, "source": { "type": "string" } } } } }, "reply": { "type": "string" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "evr_01j9...", "item_id": "edi_01j9...", "status": "SCORED", "overall_score": 0.92, "pass": true, "judge_scores": { "tone": { "score": 0.95, "source": "JEV" }, "correctness": { "score": 0.89, "source": "JEV" } }, "reply": "Yetkazib berish 2–3 ish kunida, 500 so'm." }, { "id": "evr_01j9q...", "item_id": "edi_01j9q...", "status": "SKIPPED", "error_code": "no_customer_message", "error": "The item's conversation has no customer message to answer.", "overall_score": null, "pass": null, "judge_scores": {} } ], "total": 24, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/experiments": { "post": { "operationId": "postAiExperiments", "summary": "Create an A/B experiment: dataset_id and name required, optional business_id and description", "description": "Create an A/B experiment: dataset_id and name required, optional business_id and description. Status starts DRAFT.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "dataset_id": { "type": "string" }, "description": { "type": "string" } } }, "example": { "name": "Seller v2 vs v3", "dataset_id": "eds_01j9...", "description": "Compare tone profiles." } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "winner_variant_id": { "type": [ "string", "null" ] } } }, "example": { "id": "exp_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Seller v2 vs v3", "status": "DRAFT", "winner_variant_id": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "operationId": "getAiExperiments", "summary": "List experiments, most-recent first", "description": "List experiments, most-recent first.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "winner_variant_id": { "type": [ "string", "null" ] } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "exp_01j9...", "name": "Seller v2 vs v3", "status": "SUCCEEDED", "winner_variant_id": "exv_01j9..." } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/experiments/{id}": { "get": { "operationId": "getAiExperimentsById", "summary": "One experiment with its variants and their linked evaluations", "description": "One experiment with its variants and their linked evaluations.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "winner_variant_id": { "type": [ "string", "null" ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "evaluation_id": { "type": "string" } } } } } }, "example": { "id": "exp_01j9...", "status": "SUCCEEDED", "winner_variant_id": "exv_01j9...", "variants": [ { "id": "exv_01j9...", "name": "Variant A", "evaluation_id": "evl_01j9..." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/experiments/{id}/variants": { "post": { "operationId": "postAiExperimentsByIdVariants", "summary": "Add a variant to an experiment: name required, optional candidate_config (the keys and checks of POST /ai/evaluations)", "description": "Add a variant to an experiment: name required, optional candidate_config (the keys and checks of POST /ai/evaluations).\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "candidate_config": { "type": "object", "properties": { "prompt_version_id": { "type": "string" } } } } }, "example": { "name": "Variant A", "candidate_config": { "prompt_version_id": "prv_01j9..." } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "experiment_id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "example": { "id": "exv_01j9...", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "experiment_id": "exp_01j9...", "name": "Variant A" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/experiments/{id}/winner": { "post": { "operationId": "postAiExperimentsByIdWinner", "summary": "Record the winning variant and set experiment status to SUCCEEDED", "description": "Record the winning variant and set experiment status to SUCCEEDED. variant_id required.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: quality" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_id": { "type": "string" } } }, "example": { "variant_id": "exv_01j9..." } } } }, "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/calendar": { "get": { "operationId": "getAiCalendar", "summary": "The calendar page: configured (the platform set up its Google client; false means nothing can connect), enabled (platform policy lets Calendar AI run), redirect_url (register it in the Google client), the connection (ACTIVE, or NEEDS_REAUTH when Google refused the stored access; null when none), tools (the Calendar agent's granted calendar tools and the writes among them), upcoming (the next 50 confirmed meetings Oqim booked, with their titles) and pending (proposals waiting for the customer or a person, and failed changes that can be retried)", "description": "The calendar page: configured (the platform set up its Google client; false means nothing can connect), enabled (platform policy lets Calendar AI run), redirect_url (register it in the Google client), the connection (ACTIVE, or NEEDS_REAUTH when Google refused the stored access; null when none), tools (the Calendar agent's granted calendar tools and the writes among them), upcoming (the next 50 confirmed meetings Oqim booked, with their titles) and pending (proposals waiting for the customer or a person, and failed changes that can be retried).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: calendar" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "enabled": { "type": "boolean" }, "redirect_url": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "connection": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "status": { "type": "string" }, "account_email": { "type": "string" }, "calendar_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_error": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "connected_by": { "type": "string" }, "disconnected_by": { "type": [ "string", "null" ] }, "disconnected_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "tools": { "type": "object", "properties": { "granted": { "type": "array", "items": { "type": "string" } }, "writes": { "type": "array", "items": { "type": "string" } } } }, "upcoming": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "connection_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "calendar_id": { "type": "string" }, "provider_event_id": { "type": "string" }, "status": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "time_zone": { "type": "string" }, "html_link": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "notes": { "type": "string" }, "conversation_title": { "type": "string" }, "business_name": { "type": "string" } } } }, "pending": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "connection_id": { "type": "string" }, "event_id": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "time_zone": { "type": "string" }, "extracted": { "type": "object", "properties": { "type": { "type": "string" }, "start": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "confidence": { "type": [ "number", "null" ] } } }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } } }, "failures": { "type": "array", "items": {} } } }, "result": { "type": "object", "properties": { "confirmed_in": { "type": "string" } } }, "gate": { "type": "string" }, "gate_reason": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "customer_confirmed": { "type": "boolean" }, "reply_to_message_id": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "agent_execution_id": { "type": "string" }, "jev_decision_id": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "prompt_version_id": { "type": "string" }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "business_name": { "type": "string" } } } } } }, "example": { "configured": true, "enabled": true, "redirect_url": "https://oqim.example.com/api/v1/ai/calendar/oauth/callback", "scopes": [ "openid", "email", "https://www.googleapis.com/auth/calendar.events", "https://www.googleapis.com/auth/calendar.freebusy" ], "connection": { "id": "cal_01j9s7a1c3e5g7j9m1p3r5t7w9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "provider": "GOOGLE", "status": "ACTIVE", "account_email": "bookings@silkroad.example", "calendar_id": "primary", "scopes": [ "openid", "email", "https://www.googleapis.com/auth/calendar.events", "https://www.googleapis.com/auth/calendar.freebusy" ], "last_error": null, "last_used_at": "2026-09-26T09:30:00Z", "connected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "disconnected_by": null, "disconnected_at": null, "created_at": "2026-09-26T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" }, "tools": { "granted": [ "calendar.check_availability", "calendar.find_events", "calendar.create_event" ], "writes": [ "calendar.create_event" ] }, "upcoming": [ { "id": "cev_01j9s7b2d4f6h8k0m2p4s6v8x0", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "connection_id": "cal_01j9s7a1c3e5g7j9m1p3r5t7w9", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "provider": "GOOGLE", "calendar_id": "primary", "provider_event_id": "oq6k9f2c1q8v0m3g5h7j2t4r6s8u0a1b3c5d7e9f0g2h4j6k8m0", "status": "CONFIRMED", "starts_at": "2026-09-29T06:00:00Z", "ends_at": "2026-09-29T06:30:00Z", "time_zone": "Asia/Tashkent", "html_link": "https://calendar.google.com/calendar/event?eid=…", "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z", "title": "Consultation — Aziza Karimova", "notes": "About the wedding package", "conversation_title": "Aziza Karimova", "business_name": "Silk Road Events" } ], "pending": [ { "id": "cac_01j9s7c3e5g7j9m1p3r5t7w9y1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "connection_id": "cal_01j9s7a1c3e5g7j9m1p3r5t7w9", "event_id": null, "type": "CREATE", "status": "PENDING", "starts_at": "2026-09-29T06:00:00Z", "ends_at": "2026-09-29T06:30:00Z", "time_zone": "Asia/Tashkent", "extracted": { "type": "CREATE", "start": "2026-09-29T11:00", "title": "Consultation", "notes": "About the wedding package", "confidence": 0.92 }, "validation": { "passed": true, "checks": [ { "name": "future", "passed": true }, { "name": "business_hours", "passed": true }, { "name": "free", "passed": true } ], "failures": [] }, "result": { "confirmed_in": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w" }, "gate": "PERSON", "gate_reason": "AUTONOMY", "confidence": 0.92, "customer_confirmed": true, "reply_to_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "agent_execution_id": "aix_01j9s7d4f6h8k0m2p4s6v8x0z2", "jev_decision_id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "model": "gpt-5.6", "prompt_version_id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "decided_by": null, "decided_at": null, "executed_at": null, "error_code": null, "error": null, "expires_at": "2026-09-29T06:00:00Z", "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z", "conversation_title": "Aziza Karimova", "business_name": "Silk Road Events" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/calendar/connect": { "post": { "operationId": "postAiCalendarConnect", "summary": "Start connecting: returns the Google consent screen's url for the signed-in person to open", "description": "Start connecting: returns the Google consent screen's url for the signed-in person to open. calendar_id is the calendar to book into: primary (the default) or another calendar's ID from its settings in Google Calendar. The sign-in state is signed, bound to the organization and the person, works once and expires after ten minutes; PKCE protects the code. Connecting again replaces the current connection (and revokes its access).\n\n409 calendar_not_configured until the platform sets GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET. API keys can't connect: a person does, in the console.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: calendar" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "calendar_id": { "type": "string" } } }, "example": { "calendar_id": "primary" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "calendar_id": { "type": "string" }, "redirect_url": { "type": "string" } } }, "example": { "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=…&code_challenge=…&state=…", "calendar_id": "primary", "redirect_url": "https://oqim.example.com/api/v1/ai/calendar/oauth/callback" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/calendar/oauth/callback": { "get": { "operationId": "getAiCalendarOauthCallback", "summary": "Where Google sends the person back (a browser navigation, with the session cookie)", "description": "Where Google sends the person back (a browser navigation, with the session cookie). The state must be valid, unexpired, unused and the signed-in person's, still allowed to manage the AI; then the code is exchanged, the granted scopes checked (both calendar scopes are required), the chosen calendar tried, and the tokens stored encrypted. Answers 302 to the console's /ai/calendar with ?calendar=connected, or ?calendar_error= signed_out, forbidden, invalid_state, state_expired, state_used, wrong_account, access_denied, missing_code, exchange_failed, scopes_missing, no_refresh_token, calendar_unavailable, not_configured or internal.\n\nAny signed-in person or API key.", "tags": [ "AI Seller: calendar" ], "x-oqim-permission": "Signed in", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "state", "in": "query", "required": false, "description": "Filter by state.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "description": "Filter by code.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Filter by error.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found: the Location header has the URL to follow.", "headers": { "Location": { "description": "The URL to follow.", "schema": { "type": "string", "format": "uri" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/calendar/disconnect": { "post": { "operationId": "postAiCalendarDisconnect", "summary": "Disconnect: Google's access is revoked, the tokens are deleted, and open proposals expire", "description": "Disconnect: Google's access is revoked, the tokens are deleted, and open proposals expire. The connection stays as history (status DISCONNECTED). 409 calendar_not_connected when there's none.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: calendar" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "provider": { "type": "string" }, "status": { "type": "string" }, "account_email": { "type": "string" }, "calendar_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_error": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "connected_by": { "type": "string" }, "disconnected_by": { "type": [ "string", "null" ] }, "disconnected_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cal_01j9s7a1c3e5g7j9m1p3r5t7w9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "provider": "GOOGLE", "status": "DISCONNECTED", "account_email": "bookings@silkroad.example", "calendar_id": "primary", "scopes": [ "openid", "email", "https://www.googleapis.com/auth/calendar.events", "https://www.googleapis.com/auth/calendar.freebusy" ], "last_error": null, "last_used_at": "2026-09-26T09:30:00Z", "connected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "disconnected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "disconnected_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-26T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/calendar/actions": { "get": { "operationId": "getAiCalendarActions", "summary": "The Calendar agent's actions, newest first, with their provenance and what the agent extracted", "description": "The Calendar agent's actions, newest first, with their provenance and what the agent extracted. Filter by status (AWAITING_CUSTOMER, PENDING, EXECUTING, COMPLETED, REJECTED, FAILED, EXPIRED), type (CREATE, UPDATE, CANCEL, FIND, CHECK_AVAILABILITY), conversation_id and business_id. validation lists the checks and their failure codes (TIME_MISSING, TIME_INVALID, TIME_ZONE_UNKNOWN, TIME_ZONE_MISMATCH, IN_THE_PAST, TOO_SOON, TOO_FAR, HOURS_NOT_SET, OUTSIDE_BUSINESS_HOURS, DURATION_TOO_SHORT, DURATION_TOO_LONG, DOUBLE_BOOKING, EVENT_NOT_FOUND, EVENT_PAST, UNCHANGED); result holds free times (alternatives on a refusal, free for CHECK_AVAILABILITY) or the bookings found. gate is AUTO, CUSTOMER, PERSON, REFUSED or READ.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: calendar" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Event types separated by commas; campaign.* matches a prefix.", "schema": { "type": "string" } }, { "name": "conversation_id", "in": "query", "required": false, "description": "Filter by conversation ID.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "connection_id": { "type": "string" }, "event_id": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "time_zone": { "type": "string" }, "extracted": { "type": "object", "properties": { "type": { "type": "string" }, "start": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "confidence": { "type": [ "number", "null" ] } } }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } } }, "failures": { "type": "array", "items": {} } } }, "result": { "type": "object", "properties": { "confirmed_in": { "type": "string" } } }, "gate": { "type": "string" }, "gate_reason": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "customer_confirmed": { "type": "boolean" }, "reply_to_message_id": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "agent_execution_id": { "type": "string" }, "jev_decision_id": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "prompt_version_id": { "type": "string" }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "business_name": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cac_01j9s7c3e5g7j9m1p3r5t7w9y1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "connection_id": "cal_01j9s7a1c3e5g7j9m1p3r5t7w9", "event_id": null, "type": "CREATE", "status": "PENDING", "starts_at": "2026-09-29T06:00:00Z", "ends_at": "2026-09-29T06:30:00Z", "time_zone": "Asia/Tashkent", "extracted": { "type": "CREATE", "start": "2026-09-29T11:00", "title": "Consultation", "notes": "About the wedding package", "confidence": 0.92 }, "validation": { "passed": true, "checks": [ { "name": "future", "passed": true }, { "name": "business_hours", "passed": true }, { "name": "free", "passed": true } ], "failures": [] }, "result": { "confirmed_in": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w" }, "gate": "PERSON", "gate_reason": "AUTONOMY", "confidence": 0.92, "customer_confirmed": true, "reply_to_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "agent_execution_id": "aix_01j9s7d4f6h8k0m2p4s6v8x0z2", "jev_decision_id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "model": "gpt-5.6", "prompt_version_id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "decided_by": null, "decided_at": null, "executed_at": null, "error_code": null, "error": null, "expires_at": "2026-09-29T06:00:00Z", "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z", "conversation_title": "Aziza Karimova", "business_name": "Silk Road Events" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/calendar/actions/{id}/confirm": { "post": { "operationId": "postAiCalendarActionsByIdConfirm", "summary": "Confirm a proposed booking, move or cancellation (AWAITING_CUSTOMER or PENDING), or retry a FAILED one: it's validated again against the calendar as it is now, then applied once", "description": "Confirm a proposed booking, move or cancellation (AWAITING_CUSTOMER or PENDING), or retry a FAILED one: it's validated again against the calendar as it is now, then applied once. A person's confirmation doesn't need the customer's; tell the customer in the conversation.\n\n409 calendar_action_not_pending (already decided, replaced or past), calendar_action_read_only (reads), calendar_not_connected, calendar_needs_reauth; 409 calendar_action_invalid with details.codes when the time can't be booked anymore (the action is REJECTED); 502 calendar_unavailable when Google refused or couldn't be reached (the action is FAILED and can be confirmed again). Audited as AI_CALENDAR_ACTION_CONFIRMED.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: calendar" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "connection_id": { "type": "string" }, "event_id": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "time_zone": { "type": "string" }, "extracted": { "type": "object", "properties": { "type": { "type": "string" }, "start": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "confidence": { "type": [ "number", "null" ] } } }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } } }, "failures": { "type": "array", "items": {} } } }, "result": { "type": "object", "properties": { "confirmed_in": { "type": "string" } } }, "gate": { "type": "string" }, "gate_reason": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "customer_confirmed": { "type": "boolean" }, "reply_to_message_id": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "agent_execution_id": { "type": "string" }, "jev_decision_id": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "prompt_version_id": { "type": "string" }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "business_name": { "type": "string" } } }, "example": { "id": "cac_01j9s7c3e5g7j9m1p3r5t7w9y1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "connection_id": "cal_01j9s7a1c3e5g7j9m1p3r5t7w9", "event_id": "cev_01j9s7b2d4f6h8k0m2p4s6v8x0", "type": "CREATE", "status": "COMPLETED", "starts_at": "2026-09-29T06:00:00Z", "ends_at": "2026-09-29T06:30:00Z", "time_zone": "Asia/Tashkent", "extracted": { "type": "CREATE", "start": "2026-09-29T11:00", "title": "Consultation", "notes": "About the wedding package", "confidence": 0.92 }, "validation": { "passed": true, "checks": [ { "name": "future", "passed": true }, { "name": "business_hours", "passed": true }, { "name": "free", "passed": true } ], "failures": [] }, "result": { "confirmed_in": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w" }, "gate": "PERSON", "gate_reason": "AUTONOMY", "confidence": 0.92, "customer_confirmed": true, "reply_to_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "agent_execution_id": "aix_01j9s7d4f6h8k0m2p4s6v8x0z2", "jev_decision_id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "model": "gpt-5.6", "prompt_version_id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "decided_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "decided_at": "2026-09-26T09:30:00Z", "executed_at": "2026-09-26T09:30:00Z", "error_code": null, "error": null, "expires_at": "2026-09-29T06:00:00Z", "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z", "conversation_title": "Aziza Karimova", "business_name": "Silk Road Events" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/calendar/actions/{id}/reject": { "post": { "operationId": "postAiCalendarActionsByIdReject", "summary": "Set a proposed action (or a failed one) aside: REJECTED, with you as decided_by", "description": "Set a proposed action (or a failed one) aside: REJECTED, with you as decided_by. Nothing reaches the calendar. 409 calendar_action_not_pending otherwise. Audited as AI_CALENDAR_ACTION_REJECTED.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: calendar" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "conversation_id": { "type": [ "string", "null" ] }, "connection_id": { "type": "string" }, "event_id": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "status": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "time_zone": { "type": "string" }, "extracted": { "type": "object", "properties": { "type": { "type": "string" }, "start": { "type": "string" }, "title": { "type": "string" }, "notes": { "type": "string" }, "confidence": { "type": [ "number", "null" ] } } }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "passed": { "type": "boolean" } } } }, "failures": { "type": "array", "items": {} } } }, "result": { "type": "object", "properties": { "confirmed_in": { "type": "string" } } }, "gate": { "type": "string" }, "gate_reason": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "customer_confirmed": { "type": "boolean" }, "reply_to_message_id": { "type": "string" }, "execution_id": { "type": [ "string", "null" ] }, "agent_execution_id": { "type": "string" }, "jev_decision_id": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "prompt_version_id": { "type": "string" }, "decided_by": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "conversation_title": { "type": "string" }, "business_name": { "type": "string" } } }, "example": { "id": "cac_01j9s7c3e5g7j9m1p3r5t7w9y1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "connection_id": "cal_01j9s7a1c3e5g7j9m1p3r5t7w9", "event_id": null, "type": "CREATE", "status": "REJECTED", "starts_at": "2026-09-29T06:00:00Z", "ends_at": "2026-09-29T06:30:00Z", "time_zone": "Asia/Tashkent", "extracted": { "type": "CREATE", "start": "2026-09-29T11:00", "title": "Consultation", "notes": "About the wedding package", "confidence": 0.92 }, "validation": { "passed": true, "checks": [ { "name": "future", "passed": true }, { "name": "business_hours", "passed": true }, { "name": "free", "passed": true } ], "failures": [] }, "result": { "confirmed_in": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w" }, "gate": "PERSON", "gate_reason": "REJECTED_BY_PERSON", "confidence": 0.92, "customer_confirmed": true, "reply_to_message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "execution_id": "aix_01j9rv0a2c4e6g8j0m2p4r6t8w", "agent_execution_id": "aix_01j9s7d4f6h8k0m2p4s6v8x0z2", "jev_decision_id": "jvd_01j9rs4w6y8a0c2e4g6j8m0p2r", "model": "gpt-5.6", "prompt_version_id": "prv_01j9rz2e4g6j8m0p2r4t6w8y0a", "decided_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "decided_at": "2026-09-26T09:30:00Z", "executed_at": null, "error_code": null, "error": null, "expires_at": "2026-09-29T06:00:00Z", "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z", "conversation_title": "Aziza Karimova", "business_name": "Silk Road Events" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/cases": { "get": { "operationId": "getAiBusinessesByIdCases", "summary": "A business's case catalog in display order (dimension, then position): every case not deleted", "description": "A business's case catalog in display order (dimension, then position): every case not deleted. dimension and status filter; dimension accepts the five conversation dimensions and the two topic dimensions CONTENT_TOPIC and COMMENT_TOPIC. conversations_30d counts the conversations classified into a case whose last message is within 30 days; for a topic, posts_30d or comments_30d counts its posts or its audience's comments of the last 30 days instead. The whole catalog comes by default (limit 500).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "dimension", "in": "query", "required": false, "description": "Filter by dimension.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "dimension": { "type": "string" }, "key": { "type": "string" }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "description": { "type": "string" }, "hint": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "status": { "type": "string" }, "source": { "type": "string" }, "position": { "type": "integer" }, "conversations_30d": { "type": "integer" }, "posts_30d": { "type": "integer" }, "comments_30d": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cas_01j9s7r1t3v5x7z9b1d3f5h7k9", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "dimension": "LOST_REASON", "key": "TOO_EXPENSIVE", "name": { "uz": "Narxi qimmatlik qildi", "ru": "Слишком дорого", "en": "Too expensive" }, "description": "Found the ticket price too high or above their budget, or wanted a group discount they didn't get.", "hint": { "uz": "Narxga nima kirishini ayting yoki kichikroq paket taklif qiling.", "ru": "Расскажите, что входит в цену, или предложите пакет поменьше.", "en": "Say what the price includes, or offer a smaller package." }, "status": "ACTIVE", "source": "LLM", "position": 0, "conversations_30d": 64, "posts_30d": 0, "comments_30d": 0, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z" }, { "id": "cas_01j9s7s2u4w6y8a0c2e4g6j8m0", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "dimension": "PURCHASE_OUTCOME", "key": "WENT_SILENT_AFTER_PRICE", "name": { "uz": "Narxni bilib, jim qoldi", "ru": "Пропал после цены", "en": "Went silent after the price" }, "description": "Stopped replying right after learning the price or the terms, without saying no.", "hint": null, "status": "ACTIVE", "source": "LLM", "position": 3, "conversations_30d": 51, "posts_30d": 0, "comments_30d": 0, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiBusinessesByIdCases", "summary": "Add a case (source MANUAL), last in its dimension (a conversation dimension or a topic: CONTENT_TOPIC or COMMENT_TOPIC)", "description": "Add a case (source MANUAL), last in its dimension (a conversation dimension or a topic: CONTENT_TOPIC or COMMENT_TOPIC). name needs uz, ru and en; description is English and is JEV's criterion for the case: say which conversations belong to it and where it stops. key is UPPER_SNAKE_CASE, derived from the English name when left out, unique in the dimension; NONE_APPLY, UNCLEAR and NOT_APPLICABLE are reserved. At most 30 cases per dimension.\n\nAudited as AI_CASE_CREATED. A key in use is 409 case_key_taken; a full dimension 409 case_limit.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dimension": { "type": "string" }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "description": { "type": "string" }, "hint": { "type": [ "object", "null" ], "properties": { "en": { "type": "string" } } } } }, "example": { "dimension": "DEMAND", "name": { "uz": "Chegirma soʻradi", "ru": "Просили скидку", "en": "Asked for a discount" }, "description": "Asked for a lower price, a promo code or a group discount.", "hint": { "en": "Say which discounts exist." } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "dimension": { "type": "string" }, "key": { "type": "string" }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "description": { "type": "string" }, "hint": { "type": [ "object", "null" ], "properties": { "en": { "type": "string" } } }, "status": { "type": "string" }, "source": { "type": "string" }, "position": { "type": "integer" }, "conversations_30d": { "type": "integer" }, "posts_30d": { "type": "integer" }, "comments_30d": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cas_01j9s7w6y8a0c2e4g6j8m0p2r4", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "dimension": "DEMAND", "key": "ASKED_FOR_A_DISCOUNT", "name": { "uz": "Chegirma soʻradi", "ru": "Просили скидку", "en": "Asked for a discount" }, "description": "Asked for a lower price, a promo code or a group discount.", "hint": { "en": "Say which discounts exist." }, "status": "ACTIVE", "source": "MANUAL", "position": 8, "conversations_30d": 0, "posts_30d": 0, "comments_30d": 0, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/cases/generate": { "post": { "operationId": "postAiBusinessesByIdCasesGenerate", "summary": "Write the business's catalog in the background: 6 to 12 cases per dimension (all, or the ones in dimensions), specific to its profile, offers and funnel, with names in Uzbek, Russian and English and English criteria", "description": "Write the business's catalog in the background: 6 to 12 cases per dimension (all, or the ones in dimensions), specific to its profile, offers and funnel, with names in Uzbek, Russian and English and English criteria. dimensions names the five conversation dimensions or the two topic dimensions (CONTENT_TOPIC, COMMENT_TOPIC); a topic run also reads the business's recent captions and video titles. Left out, the conversation dimensions are written. A sync whose business has no topics asks for them (and that is how a connected account gets its own topics without an owner asking), and posts or comments judged before the topics existed are judged on them once. replace: false (the default) only adds cases whose key is missing; replace: true rewrites the generated (LLM and TEMPLATE) cases and archives those the new set leaves out; people's cases stay. Each dimension is written separately; one whose answer was unusable (after a second try) gets the built-in templates, as does every dimension without a connected model. A business's first analysis writes its catalog by itself; cases added start the analysis of its past conversations.\n\nAudited as AI_CASES_GENERATION_STARTED and AI_CASES_GENERATED. A job already running is 409 generation_running. At most 10 an hour per business.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dimensions": { "type": "array", "items": { "type": "string" } }, "replace": { "type": "boolean" } } }, "example": { "dimensions": [ "LOST_REASON", "DEMAND" ], "replace": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" } } }, "example": { "job_id": "cgj_01j9s9v5x7z9b1d3f5h7k9m1p3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/businesses/{id}/cases/generation": { "get": { "operationId": "getAiBusinessesByIdCasesGeneration", "summary": "The business's latest catalog generation: IDLE, RUNNING, DONE or FAILED (with error)", "description": "The business's latest catalog generation: IDLE, RUNNING, DONE or FAILED (with error).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "status": "DONE", "finished_at": "2026-09-20T08:00:12Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/cases/{id}": { "patch": { "operationId": "patchAiCasesById", "summary": "Change a case's name (the languages given), description, hint (null removes it), status (ACTIVE or ARCHIVED: archived cases leave new analyses) or position", "description": "Change a case's name (the languages given), description, hint (null removes it), status (ACTIVE or ARCHIVED: archived cases leave new analyses) or position. The key never changes.\n\nAudited as AI_CASE_UPDATED.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "object", "null" ], "properties": { "en": { "type": "string" } } }, "status": { "type": "string" } } }, "example": { "name": { "en": "Price too high" }, "status": "ACTIVE" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "dimension": { "type": "string" }, "key": { "type": "string" }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "description": { "type": "string" }, "hint": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "status": { "type": "string" }, "source": { "type": "string" }, "position": { "type": "integer" }, "conversations_30d": { "type": "integer" }, "posts_30d": { "type": "integer" }, "comments_30d": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cas_01j9s7r1t3v5x7z9b1d3f5h7k9", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "dimension": "LOST_REASON", "key": "TOO_EXPENSIVE", "name": { "uz": "Narxi qimmatlik qildi", "ru": "Слишком дорого", "en": "Price too high" }, "description": "Found the ticket price too high or above their budget, or wanted a group discount they didn't get.", "hint": { "uz": "Narxga nima kirishini ayting yoki kichikroq paket taklif qiling.", "ru": "Расскажите, что входит в цену, или предложите пакет поменьше.", "en": "Say what the price includes, or offer a smaller package." }, "status": "ACTIVE", "source": "LLM", "position": 0, "conversations_30d": 64, "posts_30d": 0, "comments_30d": 0, "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteAiCasesById", "summary": "Remove a case from the catalog and from new analyses", "description": "Remove a case from the catalog and from new analyses. Conversations classified into it keep their history (boards and drill-downs still name it).\n\nAudited as AI_CASE_DELETED.\n\nNeeds `ai:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:manage", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/analysis": { "get": { "operationId": "getAiConversationsByIdAnalysis", "summary": "A conversation's analysis: analysis_mode (JEV, LLM or OFF), phase (LIVE, or FINAL once a FINAL analysis read the customer's last message; LIVE again when they write after it; null before any), scores, flags, the classification per dimension (kind CASE, UNCLEAR or NOT_APPLICABLE; source JEV, LLM or HUMAN), up to 20 past analyses, and the explanation in locale (the ?locale, else Accept-Language, else en)", "description": "A conversation's analysis: analysis_mode (JEV, LLM or OFF), phase (LIVE, or FINAL once a FINAL analysis read the customer's last message; LIVE again when they write after it; null before any), scores, flags, the classification per dimension (kind CASE, UNCLEAR or NOT_APPLICABLE; source JEV, LLM or HUMAN), up to 20 past analyses, and the explanation in locale (the ?locale, else Accept-Language, else en). explanation is null until asked for in that locale; its status is READY, PENDING, NOT_CLOSED (live conversations get none) or DISABLED (with error_code: ungrounded when the model wrote numbers the conversation doesn't hold, analysis_off, no_model, generation_failed, or the AI budget's code). Personal conversations are 404.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "description": "Filter by locale.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "analysis_mode": { "type": "string" }, "phase": { "type": "string" }, "analyzed_at": { "type": "string", "format": "date-time" }, "scores": { "type": "object", "properties": { "satisfaction": { "type": "number" }, "sentiment": { "type": "number" }, "purchase_intent": { "type": "number" }, "urgency": { "type": "number" }, "trust": { "type": "number" } } }, "flags": { "type": "object", "properties": { "unanswered_question": { "type": "number" }, "missed_opportunity": { "type": "number" }, "competitor_mentioned": { "type": "number" }, "unavailable_item_requested": { "type": "number" }, "complaint": { "type": "number" } } }, "cases": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "kind": { "type": "string" }, "case_id": { "type": [ "string", "null" ] }, "case_key": { "type": [ "string", "null" ] }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "source": { "type": "string" } } } }, "explanation": { "type": "object", "properties": { "status": { "type": "string" }, "locale": { "type": "string" }, "what_happened": { "type": "string" }, "why": { "type": "string" }, "key_moments": { "type": "array", "items": { "type": "object", "properties": { "message_id": { "type": [ "string", "null" ] }, "label": { "type": "string" } } } }, "generated_at": { "type": "string", "format": "date-time" } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "analysis_id": { "type": "string" }, "phase": { "type": "string" }, "mode": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "example": { "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "channel": "TELEGRAM", "analysis_mode": "JEV", "phase": "FINAL", "analyzed_at": "2026-09-27T12:00:00Z", "scores": { "satisfaction": 2.4, "sentiment": 2.1, "purchase_intent": 1.2, "urgency": 0.8, "trust": 1.5 }, "flags": { "unanswered_question": 0.82, "missed_opportunity": 0.71, "competitor_mentioned": 0.05, "unavailable_item_requested": 0.1, "complaint": 0.2 }, "cases": [ { "dimension": "PURCHASE_OUTCOME", "kind": "CASE", "case_id": "cas_01j9s7s2u4w6y8a0c2e4g6j8m0", "case_key": "WENT_SILENT_AFTER_PRICE", "name": { "uz": "Narxni bilib, jim qoldi", "ru": "Пропал после цены", "en": "Went silent after the price" }, "probability": 0.78, "confidence": 0.74, "source": "JEV" }, { "dimension": "LOST_REASON", "kind": "CASE", "case_id": "cas_01j9s7r1t3v5x7z9b1d3f5h7k9", "case_key": "TOO_EXPENSIVE", "name": { "uz": "Narxi qimmatlik qildi", "ru": "Слишком дорого", "en": "Too expensive" }, "probability": 0.81, "confidence": 0.81, "source": "LLM" }, { "dimension": "DISSATISFACTION", "kind": "NOT_APPLICABLE", "case_id": null, "case_key": null, "name": null, "probability": 0.9, "confidence": 0.9, "source": "JEV" }, { "dimension": "DEMAND", "kind": "CASE", "case_id": "cas_01j9s7t3v5x7z9b1d3f5h7k9m1", "case_key": "GROUP_TICKETS", "name": { "uz": "Guruh chiptalari", "ru": "Групповые билеты", "en": "Group tickets" }, "probability": 0.88, "confidence": 0.88, "source": "JEV" }, { "dimension": "SERVICE_QUALITY", "kind": "UNCLEAR", "case_id": null, "case_key": null, "name": null, "probability": 0.41, "confidence": 0.41, "source": "JEV" } ], "explanation": { "status": "READY", "locale": "ru", "what_happened": "Клиент спросил цену групповых билетов, получил цену и перестал отвечать.", "why": "Цена оказалась выше ожиданий, а скидку для группы клиенту не предложили.", "key_moments": [ { "message_id": "msg_01j9s4e1g3j5m7p9s1t3v5x7z9", "label": "Спросил цену для группы" }, { "message_id": "msg_01j9s4f2h4k6n8q0s2u4w6y8a0", "label": "Цена без предложения скидки" } ], "generated_at": "2026-09-27T12:05:00Z" }, "history": [ { "analysis_id": "can_01j9s8u4w6y8a0c2e4g6j8m0p2", "phase": "FINAL", "mode": "MIXED", "created_at": "2026-09-27T12:00:00Z" }, { "analysis_id": "can_01j9s8t3v5x7z9b1d3f5h7k9m1", "phase": "LIVE", "mode": "JEV", "created_at": "2026-09-26T18:20:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/analysis/refresh": { "post": { "operationId": "postAiConversationsByIdAnalysisRefresh", "summary": "Queue a LIVE analysis of the conversation now", "description": "Queue a LIVE analysis of the conversation now. It needs JEV: without it 409 jev_unavailable; with Conversation Intelligence off 409 analysis_off.\n\nAt most 10 an hour per conversation and 300 per organization (429 ai_rate_limited).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "conversation_id": { "type": [ "string", "null" ] } } }, "example": { "queued": true, "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/analysis/explain": { "post": { "operationId": "postAiConversationsByIdAnalysisExplain", "summary": "Write the explanation of a closed conversation's current analysis in a locale (uz, ru or en): what happened and why, with key moments that point at the conversation's own messages", "description": "Write the explanation of a closed conversation's current analysis in a locale (uz, ru or en): what happened and why, with key moments that point at the conversation's own messages. It's written from the conversation and its classification, checked (numbers must be ones the messages or the analysis hold; else written once more, then withheld), sealed and kept per conversation, locale and analysis; asking again changes nothing. A live conversation is 409 conversation_not_closed; one never analysed 409 not_analyzed.\n\nAt most 100 an hour per organization (429 ai_rate_limited).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string" } } }, "example": { "locale": "ru" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "conversation_id": { "type": [ "string", "null" ] }, "analysis_id": { "type": "string" }, "locale": { "type": "string" } } }, "example": { "queued": true, "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "analysis_id": "can_01j9s8u4w6y8a0c2e4g6j8m0p2", "locale": "ru" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/conversations/{id}/cases/{dimension}": { "put": { "operationId": "putAiConversationsByIdCasesByDimension", "summary": "Correct the conversation's classification on a dimension: case_id (a case of its business in that dimension), or case_id null with kind UNCLEAR or NOT_APPLICABLE", "description": "Correct the conversation's classification on a dimension: case_id (a case of its business in that dimension), or case_id null with kind UNCLEAR or NOT_APPLICABLE. The correction (source HUMAN) wins over later automatic analyses, except that a FINAL analysis replaces a correction made while the conversation was LIVE.\n\nAudited as AI_CASE_ASSIGNMENT_CORRECTED with the previous classification. A conversation without a business can only take a kind (409 no_business for a case).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "dimension", "in": "path", "required": true, "description": "The dimension.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": [ "string", "null" ] } } }, "example": { "case_id": "cas_01j9s7r1t3v5x7z9b1d3f5h7k9" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "dimension": { "type": "string" }, "kind": { "type": "string" }, "case_id": { "type": [ "string", "null" ] }, "case_key": { "type": [ "string", "null" ] }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "probability": { "type": "number" }, "confidence": { "type": [ "number", "null" ] }, "source": { "type": "string" }, "phase": { "type": "string" }, "assigned_by": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "dimension": "LOST_REASON", "kind": "CASE", "case_id": "cas_01j9s7r1t3v5x7z9b1d3f5h7k9", "case_key": "TOO_EXPENSIVE", "name": { "uz": "Narxi qimmatlik qildi", "ru": "Слишком дорого", "en": "Too expensive" }, "probability": 1, "confidence": 1, "source": "HUMAN", "phase": "FINAL", "assigned_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_at": "2026-09-26T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/insights/boards/{board}": { "get": { "operationId": "getAiInsightsBoardsByBoard", "summary": "An insight board: BUSINESS_HEALTH (every dimension, score and flag), SALES_OUTCOMES, LOST_REASONS, HAPPINESS, DEMAND or SERVICE_QUALITY (their dimensions with the scores and flags that explain them)", "description": "An insight board: BUSINESS_HEALTH (every dimension, score and flag), SALES_OUTCOMES, LOST_REASONS, HAPPINESS, DEMAND or SERVICE_QUALITY (their dimensions with the scores and flags that explain them). The period is from–to (YYYY-MM-DD in the organization's time zone, both included; the last 30 days by default, 366 at most); the previous period is as long, right before. A conversation belongs to the period of its last message. KPIs are observed (conversations, customers_replied, purchases = leads won, avg_first_reply_seconds, handoffs, opt_outs), derived (conversion) or estimated by the AI (avg_satisfaction), each with the previous period's value and the relative change. Per dimension, total counts the conversations it applied to (a case or UNCLEAR); each case has its count, share of total, previous count, change, average confidence and daily trend; with business_id, every active case of the business is listed, even at zero. Scores come with their average, distribution and daily trend; flags with the share of analysed conversations. channel (TELEGRAM, INSTAGRAM or FACEBOOK) narrows it; without it, by_channel compares the channels (rows add up to conversations). backfill shows the analysis of past conversations while it runs; narrative is null until asked for in the locale (READY, PENDING, STALE when the data changed since, with the old text, or DISABLED).\n\nAn unknown channel is 400 invalid_channel; an unknown board 404 board_not_found.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "description": "The board.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "Filter by channel.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "locale", "in": "query", "required": false, "description": "Filter by locale.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "board": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "analysis_mode": { "type": "string" }, "period": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" } } }, "previous_period": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" } } }, "updated_at": { "type": "string", "format": "date-time" }, "conversations": { "type": "integer" }, "analyzed": { "type": "integer" }, "coverage": { "type": "number" }, "kpis": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "number" }, "previous": { "type": "number" }, "change": { "type": "number" }, "kind": { "type": "string" } } } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "total": { "type": "integer" }, "unclear": { "type": "integer" }, "not_applicable": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "case_id": { "type": [ "string", "null" ] }, "case_key": { "type": [ "string", "null" ] }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "count": { "type": "integer" }, "share": { "type": "number" }, "previous_count": { "type": "integer" }, "change": { "type": "number" }, "avg_confidence": { "type": "number" }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer" } } } } } } } } } }, "scores": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "average": { "type": "number" }, "previous": { "type": "number" }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "integer" }, "count": { "type": "integer" } } } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "value": { "type": "number" } } } } } } }, "flags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer" }, "share": { "type": "number" }, "previous": { "type": "number" } } } }, "by_channel": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": [ "string", "null" ] }, "conversations": { "type": "integer" }, "analyzed": { "type": "integer" }, "purchases": { "type": "integer" }, "conversion": { "type": "number" }, "avg_satisfaction": { "type": "number" }, "avg_first_reply_seconds": { "type": "integer" }, "previous": { "type": "object", "properties": { "conversations": { "type": "integer" }, "purchases": { "type": "integer" }, "conversion": { "type": "number" }, "avg_satisfaction": { "type": "number" } } } } } }, "backfill": { "type": "object", "properties": { "status": { "type": "string" }, "total": { "type": "integer" }, "done": { "type": "integer" } } }, "narrative": { "type": "object", "properties": { "status": { "type": "string" }, "locale": { "type": "string" }, "headline": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "refs": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "case_id": { "type": [ "string", "null" ] } } } } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } } } }, "generated_at": { "type": "string", "format": "date-time" } } } } }, "example": { "board": "LOST_REASONS", "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "channel": null, "analysis_mode": "JEV", "period": { "from": "2026-08-29", "to": "2026-09-27" }, "previous_period": { "from": "2026-07-30", "to": "2026-08-28" }, "updated_at": "2026-09-27T12:00:00Z", "conversations": 412, "analyzed": 398, "coverage": 0.966, "kpis": [ { "key": "conversations", "value": 412, "previous": 380, "change": 0.084, "kind": "observed" }, { "key": "customers_replied", "value": 301, "previous": 290, "change": 0.038, "kind": "observed" }, { "key": "purchases", "value": 37, "previous": 31, "change": 0.194, "kind": "observed" }, { "key": "conversion", "value": 0.09, "previous": 0.082, "change": 0.098, "kind": "derived" }, { "key": "avg_first_reply_seconds", "value": 41, "previous": 55, "change": -0.255, "kind": "observed" }, { "key": "handoffs", "value": 22, "previous": 25, "change": -0.12, "kind": "observed" }, { "key": "opt_outs", "value": 6, "previous": 4, "change": 0.5, "kind": "observed" }, { "key": "avg_satisfaction", "value": 3.6, "previous": 3.9, "change": -0.077, "kind": "estimated" } ], "dimensions": [ { "dimension": "LOST_REASON", "total": 181, "unclear": 9, "not_applicable": 217, "items": [ { "case_id": "cas_01j9s7r1t3v5x7z9b1d3f5h7k9", "case_key": "TOO_EXPENSIVE", "name": { "uz": "Narxi qimmatlik qildi", "ru": "Слишком дорого", "en": "Too expensive" }, "count": 64, "share": 0.354, "previous_count": 41, "change": 0.561, "avg_confidence": 0.81, "trend": [ { "date": "2026-09-01", "count": 3 } ] } ] } ], "scores": [ { "key": "purchase_intent", "average": 1.9, "previous": 2.2, "distribution": [ { "bucket": 0, "count": 51 }, { "bucket": 1, "count": 102 }, { "bucket": 2, "count": 131 }, { "bucket": 3, "count": 80 }, { "bucket": 4, "count": 34 } ], "trend": [ { "date": "2026-09-01", "value": 2.1 } ] } ], "flags": [ { "key": "competitor_mentioned", "count": 57, "share": 0.143, "previous": 0.09 } ], "by_channel": [ { "channel": "TELEGRAM", "conversations": 300, "analyzed": 291, "purchases": 25, "conversion": 0.083, "avg_satisfaction": 3.7, "avg_first_reply_seconds": 41, "previous": { "conversations": 280, "purchases": 19, "conversion": 0.068, "avg_satisfaction": 3.8 } }, { "channel": "INSTAGRAM", "conversations": 112, "analyzed": 107, "purchases": 12, "conversion": 0.107, "avg_satisfaction": 3.4, "avg_first_reply_seconds": 44, "previous": { "conversations": 100, "purchases": 12, "conversion": 0.12, "avg_satisfaction": 4.1 } } ], "backfill": { "status": "RUNNING", "total": 1200, "done": 340 }, "narrative": { "status": "READY", "locale": "ru", "headline": "Каждый третий клиент уходит из-за цены", "findings": [ { "text": "«Слишком дорого» — 35% ушедших клиентов, на 56% больше, чем месяцем раньше.", "refs": [ { "dimension": "LOST_REASON", "case_id": "cas_01j9s7r1t3v5x7z9b1d3f5h7k9" } ] } ], "actions": [ { "text": "Предложите групповую скидку до того, как клиент спросит о цене." } ], "generated_at": "2026-09-27T12:10:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/insights/boards/{board}/narrative": { "post": { "operationId": "postAiInsightsBoardsByBoardNarrative", "summary": "Write the board's narrative in a locale, for a business and a channel (or all) and a period, from the board's numbers (never from messages): a headline, findings with the cases they're about, actions", "description": "Write the board's narrative in a locale, for a business and a channel (or all) and a period, from the board's numbers (never from messages): a headline, findings with the cases they're about, actions. Every number in it must be in the data (a share may be written as a percentage); otherwise it's written once more, then withheld (DISABLED, error_code ungrounded). Nothing is written while the stored narrative's data is unchanged (status READY); a narrative is written at most once an hour. ai.insights.narrative_ready announces it.\n\nWithin the hour: 429 narrative_rate_limited with Retry-After. At most 60 an hour per organization (429 ai_rate_limited).\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "description": "The board.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" }, "locale": { "type": "string" } } }, "example": { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "channel": null, "from": "2026-08-29", "to": "2026-09-27", "locale": "ru" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "status": { "type": "string" }, "board": { "type": "string" }, "locale": { "type": "string" } } }, "example": { "queued": true, "status": "PENDING", "board": "LOST_REASONS", "locale": "ru" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/insights/boards/{board}/cases/{case_id}/conversations": { "get": { "operationId": "getAiInsightsBoardsByBoardCasesByCaseIdConversations", "summary": "The conversations behind a case's number on the board: the period's conversations classified into it, newest first, with their channel, current phase, the classification's confidence, satisfaction and how they ended for the sale (outcome_case)", "description": "The conversations behind a case's number on the board: the period's conversations classified into it, newest first, with their channel, current phase, the classification's confidence, satisfaction and how they ended for the sale (outcome_case). The case must be in one of the board's dimensions.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "description": "The board.", "schema": { "type": "string" } }, { "name": "case_id", "in": "path", "required": true, "description": "The case id.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "description": "Filter by channel.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "conversation_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "last_message_at": { "type": "string", "format": "date-time" }, "phase": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "satisfaction": { "type": "number" }, "outcome_case": { "type": "object", "properties": { "case_id": { "type": [ "string", "null" ] }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } } } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "conversation_id": "cnv_01j9s3bh3k5m7p9s1t3v5x7z9b", "channel": "TELEGRAM", "title": "Aziza Karimova", "account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "last_message_at": "2026-09-26T17:58:00Z", "phase": "FINAL", "confidence": 0.81, "satisfaction": 2.4, "outcome_case": { "case_id": "cas_01j9s7s2u4w6y8a0c2e4g6j8m0", "name": { "uz": "Narxni bilib, jim qoldi", "ru": "Пропал после цены", "en": "Went silent after the price" } } } ], "total": 64, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/insights/backfill": { "get": { "operationId": "getAiInsightsBackfill", "summary": "The latest analysis of past conversations for a business (or, without business_id, the organization-wide one): status IDLE, RUNNING, DONE, FAILED or CANCELLED, the conversations it found (total) and has done, failed or skipped, the mode (JEV, or LLM when the language model was allowed without JEV), what it's expected to cost and has cost", "description": "The latest analysis of past conversations for a business (or, without business_id, the organization-wide one): status IDLE, RUNNING, DONE, FAILED or CANCELLED, the conversations it found (total) and has done, failed or skipped, the mode (JEV, or LLM when the language model was allowed without JEV), what it's expected to cost and has cost. IDLE says how many conversations wait and what analysing them would cost.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" }, "mode": { "type": "string" }, "estimated_cost_micros": { "type": "integer" }, "spent_cost_micros": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "status": "RUNNING", "total": 1200, "done": 340, "failed": 2, "skipped": 11, "mode": "JEV", "estimated_cost_micros": 192000, "spent_cost_micros": 53380, "started_at": "2026-09-27T11:00:00Z", "finished_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiInsightsBackfill", "summary": "Analyse past conversations: every conversation in scope (never personal ones) without an analysis that read its newest message, newest first, for a business and a channel (or all) and active since a date", "description": "Analyse past conversations: every conversation in scope (never personal ones) without an analysis that read its newest message, newest first, for a business and a channel (or all) and active since a date. Quiet ones (12 hours) get FINAL analyses, others LIVE. JEV only unless allow_llm, which also lets the language model analyse without JEV, capped by the AI budget (the job stops when the budget does). It runs at 5 conversations a second per organization, resumes by itself after a restart and never sends anything. It also starts by itself when a business gets its case catalog and when a history import finishes. ai.insights.backfill reports progress (at most every 5 seconds).\n\nAudited as AI_BACKFILL_STARTED. One runs at a time per business (409 backfill_running); without JEV and allow_llm 409 jev_unavailable; an unknown channel 400 invalid_channel. At most 20 an hour.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] }, "since": { "type": "string", "format": "date" }, "allow_llm": { "type": "boolean" } } }, "example": { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "channel": "INSTAGRAM", "since": "2026-06-01", "allow_llm": false } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" } } }, "example": { "job_id": "bfj_01j9sa05y7a9c1e3g5j7m9p1r3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/insights/backfill/cancel": { "post": { "operationId": "postAiInsightsBackfillCancel", "summary": "Stop the running analysis of past conversations for a business (business_id in the body), or the organization-wide one", "description": "Stop the running analysis of past conversations for a business (business_id in the body), or the organization-wide one. What it analysed stays.\n\nAudited as AI_BACKFILL_CANCELLED. Nothing running is 409 backfill_not_running.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "AI Seller: case analysis and insights" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] } } }, "example": { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "total": { "type": "integer" }, "done": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" }, "mode": { "type": "string" }, "estimated_cost_micros": { "type": "integer" }, "spent_cost_micros": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "example": { "status": "CANCELLED", "total": 1200, "done": 340, "failed": 2, "skipped": 11, "mode": "JEV", "estimated_cost_micros": 192000, "spent_cost_micros": 53380, "started_at": "2026-09-27T11:00:00Z", "finished_at": "2026-09-27T11:05:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/youtube/accounts": { "post": { "operationId": "postChannelsYoutubeAccounts", "summary": "Add a public YouTube channel by its link (youtube.com/@name, /channel/UC…, /user/…, /c/…, or a video link), its @handle or its channel id", "description": "Add a public YouTube channel by its link (youtube.com/@name, /channel/UC…, /user/…, /c/…, or a video link), its @handle or its channel id. The channel is resolved through the YouTube Data API (1 unit of the platform's quota; 2 for a video link) and stored with status PUBLIC and capability CONTENT; its first sync is queued. A channel the organization disconnected comes back.\n\n422 channel_not_found when there's no such channel or the text isn't a YouTube link, handle or id; 422 validation_failed without url; 409 already_added for a channel already added; 409 provider_not_configured without YOUTUBE_API_KEY; 503 youtube_quota_exhausted (with Retry-After) when the day's quota is used up. Audited as YOUTUBE_CHANNEL_ADDED. Fires channels.account.updated.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Social content" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } }, "example": { "url": "https://www.youtube.com/@silkroadevents" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "external_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "business_id": { "type": [ "string", "null" ] }, "ai_enabled": { "type": "boolean" }, "settings": { "type": "object", "properties": {} }, "connected_by": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "cha_01j9s7a1c3e5g7j9m1p3r5t7w9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "platform": "YOUTUBE", "external_id": "UCq7Rw3vZkLm9Np2Rs5Tu8Vy", "name": "Silk Road Events", "username": "@silkroadevents", "avatar_url": "https://yt3.ggpht.com/ytc/silkroad=s240-c-k", "status": "PUBLIC", "status_reason": null, "status_changed_at": "2026-09-26T09:30:00Z", "capabilities": [ "CONTENT" ], "scopes": [], "token_expires_at": null, "business_id": null, "ai_enabled": false, "settings": {}, "connected_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "last_sync_at": null, "created_at": "2026-09-26T09:30:00Z", "updated_at": "2026-09-26T09:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/youtube/connect": { "post": { "operationId": "postChannelsYoutubeConnect", "summary": "The Google consent URL to send the person to, so a YouTube channel's owner lets Oqim read that channel's private Analytics: watch time, average view duration, subscribers gained and lost, where viewers come from, and their age, gender and country", "description": "The Google consent URL to send the person to, so a YouTube channel's owner lets Oqim read that channel's private Analytics: watch time, average view duration, subscribers gained and lost, where viewers come from, and their age, gender and country. Scopes: youtube.readonly and yt-analytics.readonly. The state is signed, lasts 10 minutes and works once. A person signed in to the console connects accounts (API keys get 403 person_required); 409 provider_not_configured when the platform has no Google OAuth client.\n\nThe channel's public numbers still sync with the platform's YouTube API key without this; connecting adds the owner's own private numbers and the INSIGHTS capability. The callback is where Google returns.\n\nNeeds `accounts:manage`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Social content" ], "x-oqim-permission": "accounts:manage", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } } }, "example": { "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=8192…apps.googleusercontent.com&redirect_uri=https%3A%2F%2Fapp.example.com%2Fapi%2Fv1%2Fchannels%2Fyoutube%2Fcallback&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&access_type=offline&state=…" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/channels/youtube/callback": { "get": { "operationId": "getChannelsYoutubeCallback", "summary": "Where Google returns the browser (public; the state is verified and used once, and the browser must carry the console session of the person who started the flow, so nobody can be tricked into connecting their channel to another organization)", "description": "Where Google returns the browser (public; the state is verified and used once, and the browser must carry the console session of the person who started the flow, so nobody can be tricked into connecting their channel to another organization). The code is exchanged, the channel is read with the token, and the account goes from PUBLIC to CONNECTED with capabilities CONTENT and INSIGHTS; its access and refresh tokens are sealed on the account and refreshed by themselves, and its first sync is queued. Redirects (302) to PUBLIC_APP_URL/channels?connected=, or ?error= denied, state_invalid, state_expired, connected_elsewhere, not_configured or provider_error.\n\nNo authentication.", "tags": [ "Social content" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "Filter by code.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Filter by state.", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Filter by error.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found: the Location header has the URL to follow.", "headers": { "Location": { "description": "The URL to follow.", "schema": { "type": "string", "format": "uri" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/social/accounts/{id}/sync": { "get": { "operationId": "getAiSocialAccountsByIdSync", "summary": "An account's content sync: status IDLE, RUNNING, DONE, FAILED or QUOTA_EXHAUSTED (the platform's YouTube quota for today is used up; it continues after the reset), with what the latest (or running) sync did: posts read, new comments stored, posts and comments analysed", "description": "An account's content sync: status IDLE, RUNNING, DONE, FAILED or QUOTA_EXHAUSTED (the platform's YouTube quota for today is used up; it continues after the reset), with what the latest (or running) sync did: posts read, new comments stored, posts and comments analysed. error_code on FAILED: account_auth_required (the token stopped working: the account is now AUTH_REQUIRED and needs connecting again), rate_limited, missing_permissions, not_found, youtube_key_invalid or provider_error. analysis_mode is JEV, LLM or OFF; analysis_error says why some content waits unanalysed (JEV refused the key, the daily AI cap was reached, …). quota_used counts YouTube Data API units; analytics_requests counts the run's YouTube Analytics reports (its own quota), and analytics_error_code with analytics_error says why a report failed (the watch time and audience numbers are missing then, while the public numbers stay).\n\nNeeds `ai:read`, which API keys have.", "tags": [ "Social content" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "posts": { "type": "integer" }, "comments": { "type": "integer" }, "analyzed": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "analysis_mode": { "type": "string" }, "analysis_error": { "type": [ "string", "null" ] }, "quota_used": { "type": "integer" }, "analytics_requests": { "type": "integer" }, "analytics_error_code": { "type": [ "string", "null" ] }, "analytics_error": { "type": [ "string", "null" ] }, "trigger": { "type": "string" }, "requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_sync_at": { "type": "string", "format": "date-time" } } }, "example": { "account_id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "platform": "INSTAGRAM", "status": "DONE", "last_sync_at": "2026-09-26T09:30:00Z", "posts": 42, "comments": 318, "analyzed": 327, "error": null, "error_code": null, "analysis_mode": "JEV", "analysis_error": null, "quota_used": 0, "analytics_requests": 0, "analytics_error_code": null, "analytics_error": null, "trigger": "SCHEDULE", "requested_at": null, "started_at": "2026-09-26T09:24:02Z", "finished_at": "2026-09-26T09:29:57Z", "next_sync_at": "2026-09-26T15:29:57Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAiSocialAccountsByIdSync", "summary": "Sync an account now", "description": "Sync an account now. A sync already running isn't started twice; the response is the sync state.\n\n409 account_not_syncable for an account that is disconnected, waiting for a reconnect or without access to its content; 409 provider_not_configured for YouTube without a key; 429 ai_rate_limited after 6 requests an hour for one account. Audited as SOCIAL_SYNC_REQUESTED. ai.social.synced fires when it finishes.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "Social content" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "posts": { "type": "integer" }, "comments": { "type": "integer" }, "analyzed": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "analysis_mode": { "type": "string" }, "analysis_error": { "type": [ "string", "null" ] }, "quota_used": { "type": "integer" }, "analytics_requests": { "type": "integer" }, "analytics_error_code": { "type": [ "string", "null" ] }, "analytics_error": { "type": [ "string", "null" ] }, "trigger": { "type": "string" }, "requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_sync_at": { "type": "string", "format": "date-time" } } }, "example": { "account_id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "platform": "INSTAGRAM", "status": "RUNNING", "last_sync_at": "2026-09-26T09:30:00Z", "posts": 42, "comments": 318, "analyzed": 327, "error": null, "error_code": null, "analysis_mode": "JEV", "analysis_error": null, "quota_used": 0, "analytics_requests": 0, "analytics_error_code": null, "analytics_error": null, "trigger": "MANUAL", "requested_at": "2026-09-26T09:30:00Z", "started_at": "2026-09-26T09:24:02Z", "finished_at": null, "next_sync_at": "2026-09-26T15:29:57Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/social/boards/{board}": { "get": { "operationId": "getAiSocialBoardsByBoard", "summary": "A board: SOCIAL_OVERVIEW (every section), CONTENT (formats, top posts, caption signals, posting, trends), AUDIENCE (comment intents, flags, sentiment, trends) or GROWTH (trends and the accounts' daily metrics as account_metrics)", "description": "A board: SOCIAL_OVERVIEW (every section), CONTENT (formats, top posts, caption signals, posting, trends), AUDIENCE (comment intents, flags, sentiment, trends) or GROWTH (trends and the accounts' daily metrics as account_metrics). platform (INSTAGRAM, FACEBOOK or YOUTUBE), account_id and business_id narrow it; from and to are dates in the organization's time zone (default: the 30 days ending today) and the previous period is as long, right before. KPIs: followers, follower_growth, posts, views, engagement_rate, comments, unanswered_comments (a comment that needs a reply and got none within 24 hours), purchase_intent_comments, each observed, estimated (AI judgements) or derived; CONTENT and GROWTH also report watch_time_minutes and avg_view_duration_seconds (observed) when the channel's owner connected it, otherwise null. content_topics (engagement by the business's own content topics: posts, views, the mean engagement rate and the change against the previous period, with a daily trend), comment_topics (what the comments are about: count, share, the change and a daily trend) and traffic_sources (where viewers found the videos, from the owner's Analytics) are their own sections; NONE_APPLY and UNCLEAR appear as their own rows with a null case_id. engagement_rate is (likes + comments + shares + saves) / views, or / reach where the platform has no views; for a set of posts, the sums' ratio; avg_ rates are means of posts' rates. by_platform (only without platform) has one row per platform, in a fixed order, adding up to the KPIs. best_slots use ISO weekdays (1 Monday) and hours in the organization's time zone. narrative is null until requested for the locale (?locale=, else Accept-Language, else en): READY, PENDING, STALE (the data changed since; the old text stays) or DISABLED with error_code.\n\n404 board_not_found for another board; 400 invalid_platform, invalid_period (from after to, or over 366 days) or invalid_locale. Disconnected accounts are left out unless asked for by account_id.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "Social content" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "description": "The board.", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "Filter by account ID.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "locale", "in": "query", "required": false, "description": "Filter by locale.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "board": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "period": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" } } }, "previous_period": { "type": "object", "properties": { "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" } } }, "updated_at": { "type": "string", "format": "date-time" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "coverage": { "type": "object", "properties": { "posts": { "type": "integer" }, "posts_analyzed": { "type": "integer" }, "comments": { "type": "integer" }, "comments_analyzed": { "type": "integer" } } }, "kpis": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "number" }, "previous": { "type": "number" }, "change": { "type": "number" }, "kind": { "type": "string" } } } }, "by_platform": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": [ "string", "null" ] }, "followers": { "type": "integer" }, "posts": { "type": "integer" }, "views": { "type": "integer" }, "engagement_rate": { "type": "number" }, "comments": { "type": "integer" }, "previous": { "type": "object", "properties": { "followers": { "type": "integer" }, "posts": { "type": "integer" }, "views": { "type": "integer" }, "engagement_rate": { "type": "number" }, "comments": { "type": "integer" } } } } } }, "formats": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string" }, "posts": { "type": "integer" }, "avg_views": { "type": "integer" }, "avg_engagement_rate": { "type": "number" }, "previous_posts": { "type": "integer" }, "previous_avg_engagement_rate": { "type": "number" } } } }, "top_posts": { "type": "array", "items": { "type": "object", "properties": { "post_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "format": { "type": "string" }, "permalink": { "type": "string" }, "caption_excerpt": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "views": { "type": "integer" }, "reach": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "saves": { "type": "integer" }, "engagement_rate": { "type": "number" } } } }, "comment_intents": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer" }, "share": { "type": "number" }, "previous_count": { "type": "integer" }, "change": { "type": "number" }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer" } } } } } } }, "comment_flags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer" }, "share": { "type": "number" }, "previous": { "type": "number" } } } }, "sentiment": { "type": "object", "properties": { "average": { "type": "number" }, "previous": { "type": "number" }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "integer" }, "count": { "type": "integer" } } } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "value": { "type": "number" } } } } } }, "caption_signals": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "share_of_posts": { "type": "number" }, "engagement_with": { "type": "number" }, "engagement_without": { "type": "number" } } } }, "posting": { "type": "object", "properties": { "per_week": { "type": "number" }, "previous_per_week": { "type": "number" }, "best_slots": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "integer" }, "hour": { "type": "integer" }, "avg_engagement_rate": { "type": "number" }, "posts": { "type": "integer" } } } } } }, "trends": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "followers": { "type": "integer" }, "views": { "type": "integer" }, "engagement_rate": { "type": "number" }, "posts": { "type": "integer" }, "comments": { "type": "integer" } } } }, "content_topics": { "type": "array", "items": { "type": "object", "properties": { "case_id": { "type": [ "string", "null" ] }, "case_key": { "type": [ "string", "null" ] }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "posts": { "type": "integer" }, "views": { "type": "integer" }, "avg_engagement_rate": { "type": "number" }, "previous_posts": { "type": "integer" }, "previous_avg_engagement_rate": { "type": "number" }, "change": { "type": "number" }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer" } } } } } } }, "comment_topics": { "type": "array", "items": { "type": "object", "properties": { "case_id": { "type": [ "string", "null" ] }, "case_key": { "type": [ "string", "null" ] }, "name": { "type": [ "object", "null" ], "properties": { "uz": { "type": "string" }, "ru": { "type": "string" }, "en": { "type": "string" } } }, "count": { "type": "integer" }, "share": { "type": "number" }, "previous_count": { "type": "integer" }, "change": { "type": "number" }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "count": { "type": "integer" } } } } } } }, "traffic_sources": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "views": { "type": "integer" }, "share": { "type": "number" }, "previous_views": { "type": "integer" }, "change": { "type": "number" } } } }, "narrative": { "type": "object", "properties": { "status": { "type": "string" }, "locale": { "type": "string" }, "headline": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "refs": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string" }, "key": { "type": "string" } } } } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } } } }, "generated_at": { "type": "string", "format": "date-time" } } } } }, "example": { "board": "SOCIAL_OVERVIEW", "platform": null, "account_id": null, "business_id": null, "period": { "from": "2026-08-28", "to": "2026-09-26" }, "previous_period": { "from": "2026-07-29", "to": "2026-08-27" }, "updated_at": "2026-09-26T09:30:00Z", "accounts": [ { "id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "platform": "INSTAGRAM", "name": "Silk Road Events", "username": "silkroad.events", "status": "CONNECTED", "last_sync_at": "2026-09-26T09:30:00Z" }, { "id": "cha_01j9s7a1c3e5g7j9m1p3r5t7w9", "platform": "YOUTUBE", "name": "Silk Road Events", "username": "@silkroadevents", "status": "PUBLIC", "last_sync_at": "2026-09-26T09:30:00Z" } ], "coverage": { "posts": 51, "posts_analyzed": 51, "comments": 3400, "comments_analyzed": 3310 }, "kpis": [ { "key": "followers", "value": 12400, "previous": 11900, "change": 0.042, "kind": "observed" }, { "key": "follower_growth", "value": 500, "previous": 380, "change": 0.316, "kind": "derived" }, { "key": "posts", "value": 51, "previous": 44, "change": 0.159, "kind": "observed" }, { "key": "views", "value": 412000, "previous": 330000, "change": 0.248, "kind": "observed" }, { "key": "engagement_rate", "value": 0.0584, "previous": 0.0512, "change": 0.141, "kind": "derived" }, { "key": "comments", "value": 3400, "previous": 2900, "change": 0.172, "kind": "observed" }, { "key": "unanswered_comments", "value": 38, "previous": 61, "change": -0.377, "kind": "estimated" }, { "key": "purchase_intent_comments", "value": 402, "previous": 297, "change": 0.354, "kind": "estimated" } ], "by_platform": [ { "platform": "INSTAGRAM", "followers": 9100, "posts": 42, "views": 380000, "engagement_rate": 0.061, "comments": 2100, "previous": { "followers": 8800, "posts": 35, "views": 300000, "engagement_rate": 0.052, "comments": 1700 } }, { "platform": "YOUTUBE", "followers": 3300, "posts": 9, "views": 32000, "engagement_rate": 0.031, "comments": 1300, "previous": { "followers": 3100, "posts": 9, "views": 30000, "engagement_rate": 0.04, "comments": 1200 } } ], "formats": [ { "format": "REEL", "posts": 30, "avg_views": 5400, "avg_engagement_rate": 0.061, "previous_posts": 24, "previous_avg_engagement_rate": 0.048 } ], "top_posts": [ { "post_id": "spo_01j9s7c3e5g7j9m1p3r5t7w9y1", "account_id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "platform": "INSTAGRAM", "format": "REEL", "permalink": "https://www.instagram.com/reel/DAx2kLmN9pQ/", "caption_excerpt": "Silk Road Expo 14–16-oktyabr! Chiptalar 150 000 soʻmdan — Direct’ga yozing 👇", "published_at": "2026-09-19T14:05:00Z", "views": 21000, "reach": 15800, "likes": 1300, "comments": 96, "shares": 40, "saves": 120, "engagement_rate": 0.0743 } ], "comment_intents": [ { "key": "PRICE_QUESTION", "count": 410, "share": 0.124, "previous_count": 300, "change": 0.367, "trend": [ { "date": "2026-08-28", "count": 12 } ] } ], "comment_flags": [ { "key": "needs_reply", "count": 380, "share": 0.115, "previous": 0.08 } ], "sentiment": { "average": 3.9, "previous": 4.1, "distribution": [ { "bucket": 1, "count": 12 } ], "trend": [ { "date": "2026-08-28", "value": 4 } ] }, "caption_signals": [ { "key": "has_clear_cta", "share_of_posts": 0.4, "engagement_with": 0.07, "engagement_without": 0.04 } ], "posting": { "per_week": 11.9, "previous_per_week": 10.27, "best_slots": [ { "weekday": 3, "hour": 19, "avg_engagement_rate": 0.08, "posts": 4 } ] }, "trends": [ { "date": "2026-08-28", "followers": 12100, "views": 14000, "engagement_rate": 0.058, "posts": 1, "comments": 110 } ], "content_topics": [ { "case_id": "cas_01j9s7u4w6y8a0c2e4g6j8k0m2n", "case_key": "PRODUCT_SHOWCASE", "name": { "uz": "Mahsulot taqdimoti", "ru": "Показ продукта", "en": "Product showcase" }, "posts": 22, "views": 240000, "avg_engagement_rate": 0.062, "previous_posts": 18, "previous_avg_engagement_rate": 0.051, "change": 0.222, "trend": [ { "date": "2026-08-28", "count": 2 } ] } ], "comment_topics": [ { "case_id": "cas_01j9s7v5x7z9b1d3f5h7k9m1p3r", "case_key": "COMMENT_PRICE", "name": { "uz": "Narx haqida", "ru": "О цене", "en": "About the price" }, "count": 410, "share": 0.124, "previous_count": 300, "change": 0.367, "trend": [ { "date": "2026-08-28", "count": 12 } ] } ], "traffic_sources": [ { "key": "YT_SEARCH", "views": 18000, "share": 0.562, "previous_views": 14000, "change": 0.286 } ], "narrative": { "status": "READY", "locale": "ru", "headline": "Вовлечённость выросла благодаря Reels с призывом к действию.", "findings": [ { "text": "Reels дают вовлечённость 6,1% против 4,8% в прошлом периоде.", "refs": [ { "section": "formats", "key": "REEL" } ] }, { "text": "Чаще всего спрашивают о цене: 410 комментариев, 12% всех.", "refs": [ { "section": "comment_intents", "key": "PRICE_QUESTION" } ] } ], "actions": [ { "text": "Ответьте на 38 комментариев, которые ждут ответа больше суток." } ], "generated_at": "2026-09-26T09:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/social/boards/{board}/narrative": { "post": { "operationId": "postAiSocialBoardsByBoardNarrative", "summary": "Write (or refresh) a board's narrative in a locale: why engagement is rising or falling, what people ask in the comments, what content works", "description": "Write (or refresh) a board's narrative in a locale: why engagement is rising or falling, what people ask in the comments, what content works. Written by the organization's AI model from the board's numbers only; every number in it must be one of the board's (rounded at most), else it's written once more and then withheld (DISABLED, error_code ungrounded). Uzbek is written in Latin letters with ʻ and ʼ, Russian with «вы». The same board, filters, period and locale are written at most once an hour unless the data changed.\n\n422 validation_failed without locale; 429 ai_rate_limited after 30 requests an hour per organization. Fires ai.social.narrative_ready when it's ready or withheld.\n\nNeeds `ai:operate`, which API keys have.", "tags": [ "Social content" ], "x-oqim-permission": "ai:operate", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "board", "in": "path", "required": true, "description": "The board.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" }, "locale": { "type": "string" } } }, "example": { "platform": "INSTAGRAM", "from": "2026-08-28", "to": "2026-09-26", "locale": "ru" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "locale": { "type": "string" } } }, "example": { "status": "PENDING", "locale": "ru" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/social/posts": { "get": { "operationId": "getAiSocialPosts", "summary": "Posts and videos, newest first, or by engagement or views", "description": "Posts and videos, newest first, or by engagement or views. from and to are dates in the organization's time zone. engagement_rate as on the boards; analysis holds the caption's signals once judged.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "Social content" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "Filter by account ID.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "Filter by business ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "format", "in": "query", "required": false, "description": "Filter by format.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Filter by sort.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "format": { "type": "string" }, "permalink": { "type": "string" }, "caption_excerpt": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "views": { "type": "integer" }, "reach": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "saves": { "type": "integer" }, "watch_time_seconds": { "type": "integer" }, "engagement_rate": { "type": "number" }, "analysis": { "type": "object", "properties": { "has_clear_cta": { "type": "number" }, "mentions_offer_or_price": { "type": "number" }, "hook_strength": { "type": "number" }, "engine": { "type": "string" }, "analyzed_at": { "type": "string", "format": "date-time" } } }, "metrics_updated_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "spo_01j9s7c3e5g7j9m1p3r5t7w9y1", "account_id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "platform": "INSTAGRAM", "format": "REEL", "permalink": "https://www.instagram.com/reel/DAx2kLmN9pQ/", "caption_excerpt": "Silk Road Expo 14–16-oktyabr! Chiptalar 150 000 soʻmdan — Direct’ga yozing 👇", "published_at": "2026-09-19T14:05:00Z", "views": 21000, "reach": 15800, "likes": 1300, "comments": 96, "shares": 40, "saves": 120, "watch_time_seconds": 68400, "engagement_rate": 0.0743, "analysis": { "has_clear_cta": 0.94, "mentions_offer_or_price": 0.97, "hook_strength": 2.6, "engine": "JEV", "analyzed_at": "2026-09-26T09:30:00Z" }, "metrics_updated_at": "2026-09-26T09:30:00Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/social/posts/{id}": { "get": { "operationId": "getAiSocialPostsById", "summary": "One post: its full caption (or title and description), its analysis with probabilities, its metrics at each day's sync, and its comments by intent, flag and sentiment, with how many wait for an answer and how many replies the business wrote", "description": "One post: its full caption (or title and description), its analysis with probabilities, its metrics at each day's sync, and its comments by intent, flag and sentiment, with how many wait for an answer and how many replies the business wrote.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "Social content" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "format": { "type": "string" }, "permalink": { "type": "string" }, "caption_excerpt": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "views": { "type": "integer" }, "reach": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "saves": { "type": "integer" }, "watch_time_seconds": { "type": "integer" }, "engagement_rate": { "type": "number" }, "analysis": { "type": "object", "properties": { "has_clear_cta": { "type": "number" }, "mentions_offer_or_price": { "type": "number" }, "hook_strength": { "type": "number" }, "engine": { "type": "string" }, "analyzed_at": { "type": "string", "format": "date-time" } } }, "metrics_updated_at": { "type": "string", "format": "date-time" }, "caption": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "analysis_detail": { "type": "object", "properties": { "engine": { "type": "string" }, "model": { "type": "string" }, "has_clear_cta": { "type": "number" }, "mentions_offer_or_price": { "type": "number" }, "hook_strength": { "type": "object", "properties": { "value": { "type": "number" }, "level": { "type": "string" }, "confidence": { "type": [ "number", "null" ] } } }, "thresholds": { "type": "object", "properties": { "choice": { "type": "number" }, "flag": { "type": "number" } } } } }, "metrics_history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "views": { "type": "integer" }, "reach": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "saves": { "type": "integer" }, "watch_time_seconds": { "type": "integer" } } } }, "comment_breakdown": { "type": "object", "properties": { "total": { "type": "integer" }, "analyzed": { "type": "integer" }, "unanswered": { "type": "integer" }, "owner_replies": { "type": "integer" }, "intents": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer" }, "share": { "type": "number" } } } }, "flags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer" }, "share": { "type": "number" } } } }, "sentiment": { "type": "object", "properties": { "average": { "type": "number" }, "distribution": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "integer" }, "count": { "type": "integer" } } } } } } } } } }, "example": { "id": "spo_01j9s7c3e5g7j9m1p3r5t7w9y1", "account_id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "platform": "INSTAGRAM", "format": "REEL", "permalink": "https://www.instagram.com/reel/DAx2kLmN9pQ/", "caption_excerpt": "Silk Road Expo 14–16-oktyabr! Chiptalar 150 000 soʻmdan — Direct’ga yozing 👇", "published_at": "2026-09-19T14:05:00Z", "views": 21000, "reach": 15800, "likes": 1300, "comments": 96, "shares": 40, "saves": 120, "watch_time_seconds": 68400, "engagement_rate": 0.0743, "analysis": { "has_clear_cta": 0.94, "mentions_offer_or_price": 0.97, "hook_strength": 2.6, "engine": "JEV", "analyzed_at": "2026-09-26T09:30:00Z" }, "metrics_updated_at": "2026-09-26T09:30:00Z", "caption": "Silk Road Expo 14–16-oktyabr! Chiptalar 150 000 soʻmdan — Direct’ga yozing 👇", "title": "", "description": "", "analysis_detail": { "engine": "JEV", "model": "jev-1.13.0", "has_clear_cta": 0.94, "mentions_offer_or_price": 0.97, "hook_strength": { "value": 2.6, "level": "strong", "confidence": 0.71 }, "thresholds": { "choice": 0.5, "flag": 0.6 } }, "metrics_history": [ { "date": "2026-09-26", "views": 21000, "reach": 15800, "likes": 1300, "comments": 96, "shares": 40, "saves": 120, "watch_time_seconds": 68400 } ], "comment_breakdown": { "total": 96, "analyzed": 96, "unanswered": 4, "owner_replies": 31, "intents": [ { "key": "PRICE_QUESTION", "count": 38, "share": 0.396 } ], "flags": [ { "key": "needs_reply", "count": 44, "share": 0.458 } ], "sentiment": { "average": 3.8, "distribution": [ { "bucket": 4, "count": 40 } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ai/social/comments": { "get": { "operationId": "getAiSocialComments", "summary": "The audience's comments, newest first (the business's own count as its replies instead)", "description": "The audience's comments, newest first (the business's own count as its replies instead). intent filters by an intent key or UNCLEAR; flag by needs_reply, purchase_signal, competitor_mentioned or toxic (probability at least 0.6), or unanswered. flags are the probabilities; permalink points at the comment on YouTube, at its post elsewhere.\n\nNeeds `ai:read`, which API keys have.", "tags": [ "Social content" ], "x-oqim-permission": "ai:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "post_id", "in": "query", "required": false, "description": "Filter by post ID.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "Filter by account ID.", "schema": { "type": "string" } }, { "name": "platform", "in": "query", "required": false, "description": "Filter by platform.", "schema": { "type": "string" } }, { "name": "intent", "in": "query", "required": false, "description": "Filter by intent.", "schema": { "type": "string" } }, { "name": "flag", "in": "query", "required": false, "description": "Filter by flag.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "post_id": { "type": "string" }, "account_id": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "author_name": { "type": "string" }, "text": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" }, "like_count": { "type": "integer" }, "intent": { "type": "string" }, "intent_confidence": { "type": "number" }, "sentiment": { "type": "number" }, "flags": { "type": "object", "properties": { "needs_reply": { "type": "number" }, "purchase_signal": { "type": "number" }, "competitor_mentioned": { "type": "number" }, "toxic": { "type": "number" } } }, "engine": { "type": "string" }, "owner_replied": { "type": "boolean" }, "owner_replied_at": { "type": [ "string", "null" ], "format": "date-time" }, "permalink": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "sco_01j9s7d4f6h8k0m2p4s6v8x0z2", "post_id": "spo_01j9s7c3e5g7j9m1p3r5t7w9y1", "account_id": "cha_01j9s7b2d4f6h8k0m2p4s6v8x0", "platform": "INSTAGRAM", "parent_id": null, "author_name": "@dilnoza.t", "text": "Narxi qancha? Toshkentga yetkazib berasizmi?", "published_at": "2026-09-19T15:12:44Z", "like_count": 2, "intent": "PRICE_QUESTION", "intent_confidence": 0.91, "sentiment": 3.4, "flags": { "needs_reply": 0.93, "purchase_signal": 0.88, "competitor_mentioned": 0.02, "toxic": 0.01 }, "engine": "JEV", "owner_replied": false, "owner_replied_at": null, "permalink": "https://www.instagram.com/reel/DAx2kLmN9pQ/" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/audit-logs": { "get": { "operationId": "getAuditLogs", "summary": "Audit entries, newest first", "description": "Audit entries, newest first. from and to take a time or a date; a plain date as to includes that whole day.\n\nNeeds `audit:read`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Audit log and notifications" ], "x-oqim-permission": "audit:read", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "action", "in": "query", "required": false, "description": "Filter by action.", "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "description": "Filter by actor ID.", "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "required": false, "description": "Filter by target ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "organization_id": { "type": [ "string", "null" ] }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "actor_label": { "type": "string" }, "action": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "ip": { "type": "string" }, "user_agent": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "recipients": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": 88412, "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "actor_type": "USER", "actor_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "actor_label": "dilnoza@silkroad.example", "action": "CAMPAIGN_STARTED", "target_type": "campaign", "target_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "ip": "203.0.113.24", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6)", "metadata": { "name": "Expo reminder, day before", "recipients": 1840 }, "created_at": "2026-09-29T14:02:11Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/organization/support-sessions": { "get": { "operationId": "getOrganizationSupportSessions", "summary": "Who has looked at this organization as Oqim support, and why: every session, newest first, with the administrator, the reason they gave, when it began and ended, and how many requests it made", "description": "Who has looked at this organization as Oqim support, and why: every session, newest first, with the administrator, the reason they gave, when it began and ended, and how many requests it made. An organization can always see this.\n\nNeeds `audit:read`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Audit log and notifications" ], "x-oqim-permission": "audit:read", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "admin_user_id": { "type": "string" }, "admin_email": { "type": "string" }, "admin_name": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_by": { "type": [ "string", "null" ] }, "entered_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "request_count": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "sps_01m3v8k2q5r7t9w1y3b5d7f9h1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "organization_name": "Silk Road Events", "admin_user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "admin_email": "support@oqim.example.com", "admin_name": "Oqim support", "reason": "The customer reports replies stop after the third message; checking their conversation settings.", "created_at": "2026-09-26T09:30:00Z", "expires_at": "2026-10-01T12:30:00Z", "ended_at": null, "ended_by": null, "entered_at": "2026-09-26T09:30:00Z", "status": "ACTIVE", "request_count": 41 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/organization/support-sessions/{id}/accesses": { "get": { "operationId": "getOrganizationSupportSessionsByIdAccesses", "summary": "Every request one support session made against this organization, oldest first, refused ones included", "description": "Every request one support session made against this organization, oldest first, refused ones included. Another organization's session is 404, the same as one that doesn't exist.\n\nNeeds `audit:read`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Audit log and notifications" ], "x-oqim-permission": "audit:read", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "support_session_id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "method": { "type": "string" }, "status": { "type": "integer" }, "path": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": 1207, "support_session_id": "sps_01m3v8k2q5r7t9w1y3b5d7f9h1", "at": "2026-09-26T09:30:00Z", "method": "GET", "status": 200, "path": "/api/v1/ai/conversations" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/support/enter": { "get": { "operationId": "getSupportEnter", "summary": "The one-time link an administrator opens to start a support session on this hostname (a browser navigation)", "description": "The one-time link an administrator opens to start a support session on this hostname (a browser navigation). The ticket works once and expires after two minutes; unknown, used, expired and ended all look the same. On success it sets the session cookie, which expires with the session, and answers 302 to the console's /. Otherwise 302 to /login?support=invalid.\n\nNo authentication.", "tags": [ "Audit log and notifications" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "ticket", "in": "query", "required": false, "description": "Filter by ticket.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Found: the Location header has the URL to follow.", "headers": { "Location": { "description": "The URL to follow.", "schema": { "type": "string", "format": "uri" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/notifications": { "get": { "operationId": "getNotifications", "summary": "Recent notifications and the unread count", "description": "Recent notifications and the unread count.\n\nNeeds `org:read`, which API keys have.", "tags": [ "Audit log and notifications" ], "x-oqim-permission": "org:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "severity": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "link": { "type": "string" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } } }, "unread_count": { "type": "integer" } } }, "example": { "data": [ { "id": "ntf_01j9rm2r4t6w8y0a2c4e6g8j0m", "kind": "account_restricted", "severity": "CRITICAL", "title": "Expo Desk was restricted by Telegram", "body": "Its campaigns are paused. Open @SpamBot from the account to see why.", "link": "/accounts", "read_at": null, "created_at": "2026-09-26T09:30:00Z" } ], "unread_count": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/notifications/read": { "post": { "operationId": "postNotificationsRead", "summary": "Mark notifications read: the given ids, or all of them when ids is omitted", "description": "Mark notifications read: the given ids, or all of them when ids is omitted.\n\nNeeds `org:read`, which API keys have.", "tags": [ "Audit log and notifications" ], "x-oqim-permission": "org:read", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } } }, "example": { "ids": [ "ntf_01j9rm2r4t6w8y0a2c4e6g8j0m" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "type": "integer" }, "unread_count": { "type": "integer" } } }, "example": { "updated": 1, "unread_count": 0 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/public/opt-out/{token}": { "get": { "operationId": "getPublicOptOutByToken", "summary": "Describe an opt-out link: the organization, the recipient (partly masked) and whether they already opted out", "description": "Describe an opt-out link: the organization, the recipient (partly masked) and whether they already opted out. An altered or incomplete token is 404 invalid_link.\n\nNo authentication.", "tags": [ "Public" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The token from the opt-out link.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_name": { "type": "string" }, "recipient": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "opted_out": { "type": "boolean" } } }, "example": { "organization_name": "Silk Road Events", "recipient": { "name": "Az***", "username": "@az***" }, "opted_out": false } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postPublicOptOutByToken", "summary": "Confirm the opt-out", "description": "Confirm the opt-out. Takes effect immediately for every campaign of that organization; repeating it is harmless.\n\nNo authentication.", "tags": [ "Public" ], "x-oqim-permission": "Public", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "The token from the opt-out link.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_name": { "type": "string" }, "recipient": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "opted_out": { "type": "boolean" } } }, "example": { "organization_name": "Silk Road Events", "recipient": { "name": "Az***", "username": "@az***" }, "opted_out": true } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/public/inbox/attachments/{attachment_id}": { "get": { "operationId": "getPublicInboxAttachmentsByAttachmentId", "summary": "Meta fetches a reply's file itself, so Oqim hands it out on a signed, short-lived URL (exp and sig query parameters, no session and no credentials in the URL)", "description": "Meta fetches a reply's file itself, so Oqim hands it out on a signed, short-lived URL (exp and sig query parameters, no session and no credentials in the URL). The signature covers the organization, the file and the expiry, so it opens that one file only. Streams with HTTP Range; an invalid, expired or tampered link answers 403 link_expired.\n\nNeeds `Public (signed link)`, which API keys don't have: call it as a signed-in person whose role has it.", "tags": [ "Public" ], "x-oqim-permission": "Public (signed link)", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "attachment_id", "in": "path", "required": true, "description": "The attachment id.", "schema": { "type": "string" } }, { "name": "exp", "in": "query", "required": false, "description": "Filter by exp.", "schema": { "type": "string" } }, { "name": "sig", "in": "query", "required": false, "description": "Filter by sig.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } }, "example": { "status": "the file's bytes" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/public/config": { "get": { "operationId": "getPublicConfig", "summary": "Deployment settings the console needs before sign-in, including every webhook event type and whether the platform is in maintenance", "description": "Deployment settings the console needs before sign-in, including every webhook event type and whether the platform is in maintenance.\n\nNo authentication.", "tags": [ "Public" ], "x-oqim-permission": "Public", "security": [], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signups_enabled": { "type": "boolean" }, "maintenance_mode": { "type": "boolean" }, "policy_version": { "type": "string" }, "require_opt_out_link": { "type": "boolean" }, "allow_unknown_consent": { "type": "boolean" }, "telegram_driver": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string" } } }, "example": { "signups_enabled": true, "maintenance_mode": false, "policy_version": "2026-09", "require_opt_out_link": false, "allow_unknown_consent": false, "telegram_driver": "mtproto", "event_types": [ "campaign.scheduled", "campaign.started", "campaign.paused", "campaign.resumed", "campaign.completed", "campaign.cancelled", "campaign.repeat_stopped", "message.delivered", "message.failed", "account.connected", "account.restricted", "account.auth_required", "account.disconnected", "recipient.opted_out" ], "version": "0.1.0" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/openapi.json": { "get": { "operationId": "getOpenapiJson", "summary": "Redirect (302) to the OpenAPI 3.1 document for this API, which the docs serve at /docs/openapi.json", "description": "Redirect (302) to the OpenAPI 3.1 document for this API, which the docs serve at /docs/openapi.json. It's generated from this reference: point client generators, Postman or an HTTP client at it. Not rate limited.\n\nNo authentication.", "tags": [ "Public" ], "x-oqim-permission": "Public", "security": [], "responses": { "302": { "description": "Found: the Location header has the URL to follow.", "headers": { "Location": { "description": "The URL to follow.", "schema": { "type": "string", "format": "uri" } }, "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } } } } }, "/admin/overview": { "get": { "operationId": "getAdminOverview", "summary": "Platform KPIs, 14 days of delivery outcomes (UTC days), the five newest open abuse reports and worker health counts", "description": "Platform KPIs, 14 days of delivery outcomes (UTC days), the five newest open abuse reports and worker health counts. kpis.workers counts workers that are online; system_errors counts failed tasks today plus failed send jobs in the last 24 hours; unreachable_proxies counts proxies whose last health check couldn't reach them.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "kpis": { "type": "object", "properties": { "organizations": { "type": "integer" }, "active_users": { "type": "integer" }, "telegram_accounts": { "type": "integer" }, "running_campaigns": { "type": "integer" }, "queue_depth": { "type": "integer" }, "workers": { "type": "integer" }, "restricted_accounts": { "type": "integer" }, "system_errors": { "type": "integer" }, "unreachable_proxies": { "type": "integer" } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" } } } }, "recent_abuse_reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "severity": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "object", "properties": { "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" }, "attempts": { "type": "integer" }, "failure_rate": { "type": "number" }, "threshold": { "type": "number" }, "min_sample": { "type": "integer" }, "since_previous_pause": { "type": "boolean" } } }, "reported_by": { "type": "string" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "organization_name": { "type": "string" } } } }, "workers": { "type": "object", "properties": { "total": { "type": "integer" }, "online": { "type": "integer" }, "degraded": { "type": "integer" }, "offline": { "type": "integer" } } } } }, "example": { "kpis": { "organizations": 42, "active_users": 118, "telegram_accounts": 97, "running_campaigns": 6, "queue_depth": 1480, "workers": 2, "restricted_accounts": 1, "system_errors": 0, "unreachable_proxies": 3 }, "series": [ { "date": "2026-09-25", "delivered": 18204, "failed": 131, "unavailable": 402 } ], "recent_abuse_reports": [ { "id": "abr_01j9rn5s7v9x1z3b5d7f9h1k3m", "organization_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0", "campaign_id": "cmp_01j9s1b3d5f7h9k1m3p5r7t9v1", "account_id": null, "kind": "HIGH_FAILURE_RATE", "severity": "MEDIUM", "status": "OPEN", "summary": "Campaign \"Autumn sale\" paused: 41% of 120 recent sends failed", "details": { "delivered": 71, "failed": 9, "unavailable": 40, "attempts": 120, "failure_rate": 0.408, "threshold": 0.35, "min_sample": 40, "since_previous_pause": false }, "reported_by": "SYSTEM", "resolved_by": null, "resolution_note": null, "created_at": "2026-09-26T08:02:00Z", "updated_at": "2026-09-26T08:02:00Z", "resolved_at": null, "organization_name": "Bright Deals Ltd" } ], "workers": { "total": 3, "online": 2, "degraded": 0, "offline": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations": { "get": { "operationId": "getAdminOrganizations", "summary": "All organizations, newest first, with their size, active campaigns and 30-day volume", "description": "All organizations, newest first, with their size, active campaigns and 30-day volume. q matches the name, slug or ID.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "plan", "in": "query", "required": false, "description": "Filter by plan.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "accounts": { "type": "integer" }, "members": { "type": "integer" }, "campaigns": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "messages_30d": { "type": "integer" }, "api_requests_30d": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "timezone": "Asia/Tashkent", "suspended_reason": null, "suspended_at": null, "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z", "accounts": 3, "members": 4, "campaigns": 18, "active_campaigns": 3, "messages_30d": 21904, "api_requests_30d": 4120 } ], "total": 42, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAdminOrganizations", "summary": "Create an organization on a plan (FREE by default) with an existing user as its owner", "description": "Create an organization on a plan (FREE by default) with an existing user as its owner. An unknown owner_email is a 422: they sign up first.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "owner_email": { "type": "string" } } }, "example": { "name": "Samarkand Tourism Board", "plan": "BUSINESS", "timezone": "Asia/Samarkand", "owner_email": "owner@samarkand-tourism.example" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "org_01j9s8j0m2p4r6t8w0y2a4c6e8", "name": "Samarkand Tourism Board", "slug": "samarkand-tourism-board", "status": "ACTIVE", "plan": "BUSINESS", "timezone": "Asia/Samarkand", "suspended_reason": null, "suspended_at": null, "aup_version": null, "aup_accepted_at": null, "aup_accepted_by": null, "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations/{id}": { "get": { "operationId": "getAdminOrganizationsById", "summary": "One organization: usage against its plan limits, members, account and campaign counts by status, and its latest 20 audit entries", "description": "One organization: usage against its plan limits, members, account and campaign counts by status, and its latest 20 audit entries.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "usage": { "type": "object", "properties": { "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "members": { "type": "integer" }, "webhooks": { "type": "integer" } } }, "limits": { "type": "object", "properties": { "plan": { "type": "string" }, "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "team_members": { "type": "integer" }, "webhooks": { "type": "integer" }, "api_access": { "type": "boolean" }, "analytics": { "type": "string" }, "price_monthly_usd": { "type": "integer" } } }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "user_id": { "type": "string" }, "role": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "user_name": { "type": "string" }, "user_email": { "type": "string" }, "last_login_at": { "type": "string", "format": "date-time" }, "mfa_enabled": { "type": "boolean" } } } }, "accounts": { "type": "object", "properties": { "ACTIVE": { "type": "integer" } } }, "campaigns": { "type": "object", "properties": { "RUNNING": { "type": "integer" }, "SCHEDULED": { "type": "integer" }, "COMPLETED": { "type": "integer" }, "CANCELLED": { "type": "integer" } } }, "recent_audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "organization_id": { "type": [ "string", "null" ] }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "actor_label": { "type": "string" }, "action": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "ip": { "type": "string" }, "user_agent": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "recipients": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "example": { "organization": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "timezone": "Asia/Tashkent", "suspended_reason": null, "suspended_at": null, "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" }, "usage": { "accounts": 3, "active_campaigns": 1, "recipients": 4210, "members": 4, "webhooks": 1 }, "limits": { "plan": "PRO", "accounts": 10, "active_campaigns": 10, "recipients": 50000, "team_members": 5, "webhooks": 5, "api_access": true, "analytics": "basic", "price_monthly_usd": 49 }, "members": [ { "id": "mem_01j9rk9p1s3v5x7z9b1d3f5h7k", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "role": "OWNER", "created_at": "2026-09-01T10:00:00Z", "user_name": "Dilnoza Yusupova", "user_email": "dilnoza@silkroad.example", "last_login_at": "2026-09-26T07:58:10Z", "mfa_enabled": true } ], "accounts": { "ACTIVE": 3 }, "campaigns": { "RUNNING": 1, "SCHEDULED": 2, "COMPLETED": 14, "CANCELLED": 1 }, "recent_audit": [ { "id": 88412, "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "actor_type": "USER", "actor_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "actor_label": "dilnoza@silkroad.example", "action": "CAMPAIGN_STARTED", "target_type": "campaign", "target_id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "ip": "203.0.113.24", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6)", "metadata": { "name": "Expo reminder, day before", "recipients": 1840 }, "created_at": "2026-09-29T14:02:11Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "patch": { "operationId": "patchAdminOrganizationsById", "summary": "Rename an organization, or change its plan or time zone", "description": "Rename an organization, or change its plan or time zone. A new plan's limits apply at once.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" } } }, "example": { "plan": "BUSINESS" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "BUSINESS", "timezone": "Asia/Tashkent", "suspended_reason": null, "suspended_at": null, "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations/{id}/suspend": { "post": { "operationId": "postAdminOrganizationsByIdSuspend", "summary": "Suspend an organization: its running and scheduled campaigns pause, messaging stops, members get read-only access and a notification with the reason, which is required", "description": "Suspend an organization: its running and scheduled campaigns pause, messaging stops, members get read-only access and a notification with the reason, which is required.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "Messages sent to people without a recorded basis for contact (abuse report abr_01j9rn5s…)." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "SUSPENDED", "plan": "PRO", "timezone": "Asia/Tashkent", "suspended_reason": "Messages sent to people without a recorded basis for contact (abuse report abr_01j9rn5s…).", "suspended_at": "2026-09-26T09:30:00Z", "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations/{id}/reactivate": { "post": { "operationId": "postAdminOrganizationsByIdReactivate", "summary": "Lift a suspension", "description": "Lift a suspension. Campaigns paused by it stay paused until the organization resumes them.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "status": { "type": "string" }, "plan": { "type": "string" }, "timezone": { "type": "string" }, "suspended_reason": { "type": [ "string", "null" ] }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_version": { "type": [ "string", "null" ] }, "aup_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "aup_accepted_by": { "type": [ "string", "null" ] }, "conversation_intelligence_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "slug": "silk-road-events", "status": "ACTIVE", "plan": "PRO", "timezone": "Asia/Tashkent", "suspended_reason": null, "suspended_at": null, "aup_version": "2026-09", "aup_accepted_at": "2026-09-02T08:12:44Z", "aup_accepted_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "conversation_intelligence_enabled": true, "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-02T08:12:44Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/users": { "get": { "operationId": "getAdminUsers", "summary": "Users across all organizations, with how many organizations each belongs to", "description": "Users across all organizations, with how many organizations each belongs to. q matches the email, name or ID.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "organizations": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z", "organizations": 1 } ], "total": 118, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/users/{id}/disable": { "post": { "operationId": "postAdminUsersByIdDisable", "summary": "Disable a user: they can't sign in and their sessions end at once", "description": "Disable a user: they can't sign in and their sessions end at once. You can't disable yourself (409 cannot_disable_self).\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User ID (usr_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "DISABLED", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/users/{id}/enable": { "post": { "operationId": "postAdminUsersByIdEnable", "summary": "Let a disabled user sign in again", "description": "Let a disabled user sign in again.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "User ID (usr_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "is_platform_admin": { "type": "boolean" }, "status": { "type": "string" }, "mfa_enabled": { "type": "boolean" }, "last_login_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "email": "dilnoza@silkroad.example", "name": "Dilnoza Yusupova", "is_platform_admin": false, "status": "ACTIVE", "mfa_enabled": true, "last_login_at": "2026-09-26T07:58:10Z", "created_at": "2026-09-01T10:00:00Z", "updated_at": "2026-09-20T12:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/accounts": { "get": { "operationId": "getAdminAccounts", "summary": "Telegram accounts across all organizations, most recently changed first", "description": "Telegram accounts across all organizations, most recently changed first. q matches the name, username, masked phone, organization or ID.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" }, "organization_name": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1, "organization_name": "Silk Road Events" } ], "total": 97, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/accounts/{id}/disable": { "post": { "operationId": "postAdminAccountsByIdDisable", "summary": "Stop an account from sending, for example one that appears compromised", "description": "Stop an account from sending, for example one that appears compromised. Campaigns using it pause and the organization is notified; it can't resume the account itself (409 disabled_by_admin). The optional note goes to the audit log.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string" } } }, "example": { "note": "Owner reported the phone stolen on 26 Sep." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } }, "example": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "PAUSED", "status_reason": "Disabled by platform administrator", "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/accounts/{id}/enable": { "post": { "operationId": "postAdminAccountsByIdEnable", "summary": "Restore an account a platform administrator disabled, so it can send again, and notify the organization", "description": "Restore an account a platform administrator disabled, so it can send again, and notify the organization. Campaigns paused because of it stay paused until the organization resumes them. Any other account is 409 not_disabled_by_admin.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Telegram account ID (acc_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "telegram_user_id": { "type": "integer" }, "display_name": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "phone_masked": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": "string", "format": "date-time" }, "proxy_id": { "type": [ "string", "null" ] }, "daily_limit": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "cooldown_until": { "type": [ "string", "null" ], "format": "date-time" }, "next_send_at": { "type": "string", "format": "date-time" }, "sent_today": { "type": "integer" }, "sent_today_date": { "type": "string", "format": "date-time" }, "total_sent": { "type": "integer" }, "total_failed": { "type": "integer" }, "consecutive_errors": { "type": "integer" }, "last_seen_at": { "type": "string", "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "inbound_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "proxy_name": { "type": [ "string", "null" ] }, "active_campaigns": { "type": "integer" } } }, "example": { "id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "telegram_user_id": 5712093344, "display_name": "Silk Road Support", "username": "silkroad_support", "phone_masked": "+998 •• ••• 45 17", "status": "ACTIVE", "status_reason": null, "status_changed_at": "2026-09-03T06:41:12Z", "proxy_id": null, "daily_limit": 150, "min_interval_seconds": 8, "cooldown_until": null, "next_send_at": "2026-09-26T09:30:08Z", "sent_today": 42, "sent_today_date": "2026-09-26T00:00:00Z", "total_sent": 3180, "total_failed": 12, "consecutive_errors": 0, "last_seen_at": "2026-09-26T09:29:51Z", "last_error": null, "inbound_enabled": false, "created_at": "2026-09-03T06:40:00Z", "updated_at": "2026-09-26T09:30:00Z", "proxy_name": null, "active_campaigns": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/proxies": { "get": { "operationId": "getAdminProxies", "summary": "Proxies across all organizations, newest first, with the organization, how many accounts use each one, and failed health checks over the last 24 hours", "description": "Proxies across all organizations, newest first, with the organization, how many accounts use each one, and failed health checks over the last 24 hours. q matches the name, host, organization or ID; organization_id (or org) picks one organization. Credentials are never returned.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "protocol", "in": "query", "required": false, "description": "Filter by protocol.", "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "required": false, "description": "Filter by organization ID.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "assigned_accounts": { "type": "integer" }, "failed_checks_24h": { "type": "integer" }, "last_failed_at": { "type": "string", "format": "date-time" }, "last_failure": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "ACTIVE", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support", "organization_name": "Silk Road Events", "assigned_accounts": 1, "failed_checks_24h": 1, "last_failed_at": "2026-09-26T07:40:00Z", "last_failure": "dial tcp 203.0.113.8:1080: i/o timeout" } ], "total": 57, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/proxies/{id}": { "get": { "operationId": "getAdminProxiesById", "summary": "One proxy from any organization, with its latest 50 health checks, newest first", "description": "One proxy from any organization, with its latest 50 health checks, newest first.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "assigned_accounts": { "type": "integer" }, "failed_checks_24h": { "type": "integer" }, "last_failed_at": { "type": "string", "format": "date-time" }, "last_failure": { "type": "string" }, "recent_checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "proxy_id": { "type": [ "string", "null" ] }, "organization_id": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "checked_at": { "type": "string", "format": "date-time" } } } } } }, "example": { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "ACTIVE", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support", "organization_name": "Silk Road Events", "assigned_accounts": 1, "failed_checks_24h": 1, "last_failed_at": "2026-09-26T07:40:00Z", "last_failure": "dial tcp 203.0.113.8:1080: i/o timeout", "recent_checks": [ { "id": 5521, "proxy_id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "status": "ACTIVE", "latency_ms": 84, "error": null, "checked_at": "2026-09-26T09:30:00Z" }, { "id": 5498, "proxy_id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "status": "UNREACHABLE", "latency_ms": null, "error": "dial tcp 203.0.113.8:1080: i/o timeout", "checked_at": "2026-09-26T07:40:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/proxies/{id}/check": { "post": { "operationId": "postAdminProxiesByIdCheck", "summary": "Queue a health check, like the organization's bulk check; the result lands on the proxy within seconds", "description": "Queue a health check, like the organization's bulk check; the result lands on the proxy within seconds. A check already queued in the last minute counts. A disabled proxy isn't checked (409 proxy_disabled).\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "integer" } } }, "example": { "queued": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/proxies/{id}/disable": { "post": { "operationId": "postAdminProxiesByIdDisable", "summary": "Stop Oqim connecting through a proxy, for example an open proxy that's being abused", "description": "Stop Oqim connecting through a proxy, for example an open proxy that's being abused. The reason is required; the organization sees it on the proxy and in a notification. An account using the proxy stops sending, as it would on its next send: it moves to ERROR (PROXY_UNAVAILABLE) and its running and scheduled campaigns pause. It never falls back to a direct connection. The organization can't check, change or reassign the proxy until you enable it.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "Open proxy listed on spam blocklists; reported by Telegram on 26 Sep." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "assigned_accounts": { "type": "integer" }, "failed_checks_24h": { "type": "integer" }, "last_failed_at": { "type": "string", "format": "date-time" }, "last_failure": { "type": "string" } } }, "example": { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "DISABLED", "latency_ms": 84, "last_checked_at": "2026-09-26T09:30:00Z", "last_error": null, "disabled_reason": "Open proxy listed on spam blocklists; reported by Telegram on 26 Sep.", "disabled_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support", "organization_name": "Silk Road Events", "assigned_accounts": 1, "failed_checks_24h": 1, "last_failed_at": "2026-09-26T07:40:00Z", "last_failure": "dial tcp 203.0.113.8:1080: i/o timeout" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/proxies/{id}/enable": { "post": { "operationId": "postAdminProxiesByIdEnable", "summary": "Enable a disabled proxy and queue a health check; it shows as not checked until the result arrives", "description": "Enable a disabled proxy and queue a health check; it shows as not checked until the result arrives. An account stopped because of the proxy stays stopped until the organization resumes it.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proxy ID (prx_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": "string" }, "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "has_credentials": { "type": "boolean" }, "assigned_account_id": { "type": [ "string", "null" ] }, "assigned_account_name": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "assigned_accounts": { "type": "integer" }, "failed_checks_24h": { "type": "integer" }, "last_failed_at": { "type": "string", "format": "date-time" }, "last_failure": { "type": "string" } } }, "example": { "id": "prx_01j9ra2c4e6g8j0m2p4r6t8w0y", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Tashkent office", "protocol": "SOCKS5", "host": "proxy.silkroad.example", "port": 1080, "username": "oqim", "status": "ACTIVE", "latency_ms": null, "last_checked_at": null, "last_error": null, "disabled_reason": null, "disabled_at": null, "created_at": "2026-09-03T06:20:00Z", "updated_at": "2026-09-26T09:30:00Z", "has_credentials": true, "assigned_account_id": "acc_01j9r3a8f2k5m7p9s1t3v5x7z9", "assigned_account_name": "Silk Road Support", "organization_name": "Silk Road Events", "assigned_accounts": 1, "failed_checks_24h": 1, "last_failed_at": "2026-09-26T07:40:00Z", "last_failure": "dial tcp 203.0.113.8:1080: i/o timeout" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/campaigns": { "get": { "operationId": "getAdminCampaigns", "summary": "Campaigns across all organizations", "description": "Campaigns across all organizations. status takes several values separated by commas.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "organization_id", "in": "query", "required": false, "description": "Filter by organization ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "organization_name": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "RUNNING", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z", "organization_name": "Silk Road Events" } ], "total": 311, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/campaigns/{id}": { "get": { "operationId": "getAdminCampaignsById", "summary": "One campaign from any organization", "description": "One campaign from any organization.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "organization_name": { "type": "string" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "RUNNING", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z", "organization_name": "Silk Road Events" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/campaigns/{id}/pause": { "post": { "operationId": "postAdminCampaignsByIdPause", "summary": "Pause any organization's running or scheduled campaign", "description": "Pause any organization's running or scheduled campaign. The organization is notified and can't resume it (409 paused_by_admin).\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "organization_name": { "type": "string" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "PAUSED", "status_reason": "Paused by platform administrator", "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": "2026-09-26T09:30:00Z", "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z", "organization_name": "Silk Road Events" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/campaigns/{id}/resume": { "post": { "operationId": "postAdminCampaignsByIdResume", "summary": "Resume a campaign a platform administrator paused: back to RUNNING if it had started, otherwise SCHEDULED", "description": "Resume a campaign a platform administrator paused: back to RUNNING if it had started, otherwise SCHEDULED. The organization is notified. A campaign paused for any other reason is 409 not_paused_by_admin; its organization resumes it.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "organization_name": { "type": "string" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "RUNNING", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 1215, "in_flight_count": 3, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": null, "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z", "organization_name": "Silk Road Events" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/campaigns/{id}/cancel": { "post": { "operationId": "postAdminCampaignsByIdCancel", "summary": "Cancel any organization's unfinished campaign", "description": "Cancel any organization's unfinished campaign. The organization is notified; a cancelled campaign can't be restarted.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID (cmp_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string" }, "status_reason": { "type": [ "string", "null" ] }, "message_text": { "type": "string" }, "parse_mode": { "type": "string" }, "disable_link_preview": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "audience": { "type": "object", "properties": { "list_ids": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "recipient_ids": { "type": "array", "items": { "type": "string" } } } }, "account_ids": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "string" }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "window_start": { "type": "integer" }, "window_end": { "type": "integer" }, "window_days": { "type": "array", "items": { "type": "integer" } }, "recurrence": { "type": [ "object", "null" ], "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer" }, "weekdays": { "type": "array", "items": { "type": "string" } }, "ends": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } }, "series_id": { "type": [ "string", "null" ] }, "occurrence": { "type": [ "integer", "null" ] }, "auto_launch_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "total_recipients": { "type": "integer" }, "delivered_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "unavailable_count": { "type": "integer" }, "skipped_count": { "type": "integer" }, "pending_count": { "type": "integer" }, "in_flight_count": { "type": "integer" }, "launched_by": { "type": [ "string", "null" ] }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "paused_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "organization_name": { "type": "string" } } }, "example": { "id": "cmp_01j9r4c6e8g0j2m4p6r8t0w2y4", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Expo reminder, day before", "description": "", "status": "CANCELLED", "status_reason": null, "message_text": "Hi {{first_name|there}}! Tashkent Expo opens tomorrow at 10:00 in {{location}}.\n\nNo longer want these messages? {{opt_out_url}}", "parse_mode": "MARKDOWN", "disable_link_preview": true, "attachment_id": null, "audience": { "list_ids": [ "lst_01j9r5e2g4j6m8p0r2t4w6y8a0" ], "tags": [], "recipient_ids": [] }, "account_ids": [ "acc_01j9r3a8f2k5m7p9s1t3v5x7z9" ], "timezone": "Asia/Tashkent", "start_at": "2026-09-30T05:00:00Z", "end_at": "2026-09-30T15:00:00Z", "window_start": 600, "window_end": 1200, "window_days": [ 1, 2, 3, 4, 5 ], "recurrence": null, "series_id": null, "occurrence": null, "auto_launch_at": null, "next_run_at": null, "total_recipients": 1840, "delivered_count": 612, "failed_count": 4, "unavailable_count": 9, "skipped_count": 0, "pending_count": 0, "in_flight_count": 0, "launched_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "launched_at": "2026-09-29T14:02:11Z", "started_at": "2026-09-30T05:00:02Z", "paused_at": null, "completed_at": null, "cancelled_at": "2026-09-26T09:30:00Z", "created_at": "2026-09-28T10:15:00Z", "updated_at": "2026-09-30T08:14:10Z", "organization_name": "Silk Road Events" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/workers": { "get": { "operationId": "getAdminWorkers", "summary": "Worker and scheduler processes", "description": "Worker and scheduler processes. health is ONLINE (heartbeat under 20 s old), DEGRADED (under 90 s, or failing more than 20% of 50+ tasks) or OFFLINE.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "host": { "type": "string" }, "version": { "type": "string" }, "concurrency": { "type": "integer" }, "active_jobs": { "type": "integer" }, "processed_total": { "type": "integer" }, "failed_total": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_heartbeat_at": { "type": "string", "format": "date-time" }, "meta": { "type": "object", "properties": { "queues": { "type": "object", "properties": { "messages": { "type": "integer" }, "webhooks": { "type": "integer" }, "maintenance": { "type": "integer" } } }, "driver": { "type": "string" } } }, "health": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "worker-worker-01-4172", "kind": "WORKER", "host": "worker-01", "version": "0.1.0", "concurrency": 20, "active_jobs": 6, "processed_total": 184220, "failed_total": 312, "started_at": "2026-09-24T02:10:00Z", "last_heartbeat_at": "2026-09-26T09:29:58Z", "meta": { "queues": { "messages": 6, "webhooks": 3, "maintenance": 1 }, "driver": "mtproto" }, "health": "ONLINE" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues": { "get": { "operationId": "getAdminQueues", "summary": "Every queue: counts, today's processed and failed tasks (UTC), latency_ms (age of the oldest pending task) and seven days of history", "description": "Every queue: counts, today's processed and failed tasks (UTC), latency_ms (age of the oldest pending task) and seven days of history. exists is false until a queue receives its first task.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "exists": { "type": "boolean" }, "info": { "type": "object", "properties": { "size": { "type": "integer" }, "groups": { "type": "integer" }, "pending": { "type": "integer" }, "active": { "type": "integer" }, "scheduled": { "type": "integer" }, "retry": { "type": "integer" }, "archived": { "type": "integer" }, "completed": { "type": "integer" }, "aggregating": { "type": "integer" }, "processed": { "type": "integer" }, "failed": { "type": "integer" }, "processed_total": { "type": "integer" }, "failed_total": { "type": "integer" }, "latency_ms": { "type": [ "integer", "null" ] }, "paused": { "type": "boolean" }, "memory_usage": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "processed": { "type": "integer" }, "failed": { "type": "integer" } } } } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "name": "messages", "exists": true, "info": { "size": 1480, "groups": 0, "pending": 1452, "active": 6, "scheduled": 18, "retry": 4, "archived": 0, "completed": 9120, "aggregating": 0, "processed": 9344, "failed": 62, "processed_total": 184220, "failed_total": 312, "latency_ms": 1840, "paused": false, "memory_usage": 2811904, "timestamp": "2026-09-26T09:30:00Z" }, "history": [ { "date": "2026-09-25", "processed": 18335, "failed": 131 } ] } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues/{name}/pause": { "post": { "operationId": "postAdminQueuesByNamePause", "summary": "Stop workers taking tasks from a queue; tasks wait and nothing is dropped", "description": "Stop workers taking tasks from a queue; tasks wait and nothing is dropped. Returns the queue. A queue that hasn't received a task yet can't be paused (409 queue_not_started).\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Queue name, such as messages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "exists": { "type": "boolean" }, "info": { "type": "object", "properties": { "pending": { "type": "integer" }, "active": { "type": "integer" }, "paused": { "type": "boolean" } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "analysis_id": { "type": "string" }, "phase": { "type": "string" }, "mode": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "example": { "name": "messages", "exists": true, "info": { "pending": 1452, "active": 0, "paused": true }, "history": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues/{name}/resume": { "post": { "operationId": "postAdminQueuesByNameResume", "summary": "Resume a paused queue", "description": "Resume a paused queue. Returns the queue.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Queue name, such as messages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "exists": { "type": "boolean" }, "info": { "type": "object", "properties": { "pending": { "type": "integer" }, "active": { "type": "integer" }, "paused": { "type": "boolean" } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "analysis_id": { "type": "string" }, "phase": { "type": "string" }, "mode": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "example": { "name": "messages", "exists": true, "info": { "pending": 1452, "active": 6, "paused": false }, "history": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues/{name}/tasks": { "get": { "operationId": "getAdminQueuesByNameTasks", "summary": "The tasks in one state of a queue, to find the ones that are stuck", "description": "The tasks in one state of a queue, to find the ones that are stuck. state is pending, active, scheduled, retry, archived or completed (default archived: the ones that failed every retry). Each task is described by its metadata only (type, attempts, last error, when it runs next, payload size); the payload itself is never returned, because it carries customers' message text. Pages are whole pages: offset must be a multiple of limit.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Queue name, such as messages.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Filter by state.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "queue": { "type": "string" }, "type": { "type": "string" }, "state": { "type": "string" }, "retried": { "type": "integer" }, "max_retry": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "last_failed_at": { "type": "string", "format": "date-time" }, "next_process_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ] }, "is_orphaned": { "type": "boolean" }, "payload_bytes": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "b7d2f6e0-3a51-4c8e-9d04-2a8f1c6e7b19", "queue": "messages", "type": "campaign:send", "state": "archived", "retried": 5, "max_retry": 5, "last_error": "telegram: FLOOD_WAIT_600", "last_failed_at": "2026-09-26T09:30:00Z", "next_process_at": null, "completed_at": null, "deadline": null, "is_orphaned": false, "payload_bytes": 412 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues/{name}/tasks/{task}/retry": { "post": { "operationId": "postAdminQueuesByNameTasksByTaskRetry", "summary": "Put one archived, retrying or scheduled task back in line to run now", "description": "Put one archived, retrying or scheduled task back in line to run now. Retrying loses nothing, so it needs no reason, but it is audited (QUEUE_TASK_RETRIED). A task in any other state is 409 task_not_retryable; one that finished or was removed since the list loaded is 404 task_not_found.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Queue name, such as messages.", "schema": { "type": "string" } }, { "name": "task", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "queue": { "type": "string" }, "type": { "type": "string" }, "state": { "type": "string" }, "retried": { "type": "integer" }, "max_retry": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "last_failed_at": { "type": "string", "format": "date-time" }, "next_process_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "deadline": { "type": [ "string", "null" ] }, "is_orphaned": { "type": "boolean" }, "payload_bytes": { "type": "integer" } } }, "example": { "id": "b7d2f6e0-3a51-4c8e-9d04-2a8f1c6e7b19", "queue": "messages", "type": "campaign:send", "state": "archived", "retried": 5, "max_retry": 5, "last_error": "telegram: FLOOD_WAIT_600", "last_failed_at": "2026-09-26T09:30:00Z", "next_process_at": null, "completed_at": null, "deadline": null, "is_orphaned": false, "payload_bytes": 412 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues/{name}/tasks/{task}/drop": { "post": { "operationId": "postAdminQueuesByNameTasksByTaskDrop", "summary": "Delete one task", "description": "Delete one task. This cannot be undone, so a reason of at least 10 characters is required and is kept in the audit log beside what was dropped (QUEUE_TASK_DROPPED). A task that is running right now is 409 task_active: let the worker finish it, or pause the queue first. 204 on success.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Queue name, such as messages.", "schema": { "type": "string" } }, { "name": "task", "in": "path", "required": true, "description": "The task.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "Campaign was cancelled; its sends can never be delivered." } } } }, "responses": { "204": { "description": "No Content", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues/{name}/retry-archived": { "post": { "operationId": "postAdminQueuesByNameRetryArchived", "summary": "Re-run every archived task in a queue", "description": "Re-run every archived task in a queue. Returns how many were put back in line. Audited (QUEUE_ARCHIVED_RETRIED).\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Queue name, such as messages.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" } } }, "example": { "count": 12 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/queues/{name}/drop-archived": { "post": { "operationId": "postAdminQueuesByNameDropArchived", "summary": "Delete every archived task in a queue, clearing its backlog of failures", "description": "Delete every archived task in a queue, clearing its backlog of failures. Only the dead ones: nothing still waiting, scheduled or running is touched, because dropping a queued send would silently lose a customer's message. Returns how many were deleted. A reason of at least 10 characters is required and is audited (QUEUE_ARCHIVED_DROPPED).\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Queue name, such as messages.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } }, "example": { "reason": "Clearing failures from the Telegram outage on 2026-09-26; all were reviewed." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" } } }, "example": { "count": 12 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/system": { "get": { "operationId": "getAdminSystem", "summary": "What this deployment is: the build, the database schema it is on against the one this build expects, and whether Postgres and Redis answer", "description": "What this deployment is: the build, the database schema it is on against the one this build expects, and whether Postgres and Redis answer. schema.up_to_date is false when the database is behind the binary, which means a start that did not finish its migrations.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string" }, "environment": { "type": "string" }, "telegram_driver": { "type": "string" }, "maintenance_mode": { "type": "boolean" }, "schema": { "type": "object", "properties": { "expected": { "type": "integer" }, "current": { "type": "integer" }, "applied_at": { "type": "string", "format": "date-time" }, "up_to_date": { "type": "boolean" } } }, "database": { "type": "object", "properties": { "ok": { "type": "boolean" }, "latency_ms": { "type": [ "integer", "null" ] } } }, "redis": { "type": "object", "properties": { "ok": { "type": "boolean" }, "latency_ms": { "type": [ "integer", "null" ] } } } } }, "example": { "version": "0.1.0", "environment": "production", "telegram_driver": "mtproto", "maintenance_mode": false, "schema": { "expected": 27, "current": 27, "applied_at": "2026-09-26T09:30:00Z", "up_to_date": true }, "database": { "ok": true, "latency_ms": 2 }, "redis": { "ok": true, "latency_ms": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations/{id}/support-sessions": { "post": { "operationId": "postAdminOrganizationsByIdSupportSessions", "summary": "Open a read-only support session on one organization, to debug a customer's problem", "description": "Open a read-only support session on one organization, to debug a customer's problem. A reason of at least 10 characters is required and the organization can read it; minutes (default 30, between 5 and 240) is a hard limit. The organization's notification feed and audit log both record it (SUPPORT_SESSION_STARTED). The response carries enter_url, which opens the session in the customer console's own hostname: it works once, for two minutes, and is returned only here. The session acts as a read-only role, every request under it is recorded, and it cannot reach this administration API.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" }, "minutes": { "type": "integer" } } }, "example": { "reason": "The customer reports replies stop after the third message; checking their conversation settings.", "minutes": 30 } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "admin_user_id": { "type": "string" }, "admin_email": { "type": "string" }, "admin_name": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_by": { "type": [ "string", "null" ] }, "entered_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "request_count": { "type": "integer" }, "enter_url": { "type": "string" } } }, "example": { "id": "sps_01m3v8k2q5r7t9w1y3b5d7f9h1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "organization_name": "Silk Road Events", "admin_user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "admin_email": "support@oqim.example.com", "admin_name": "Oqim support", "reason": "The customer reports replies stop after the third message; checking their conversation settings.", "created_at": "2026-09-26T09:30:00Z", "expires_at": "2026-10-01T12:30:00Z", "ended_at": null, "ended_by": null, "entered_at": null, "status": "ACTIVE", "request_count": 0, "enter_url": "https://oqim.example.com/api/v1/support/enter?ticket=…" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/support-sessions": { "get": { "operationId": "getAdminSupportSessions", "summary": "Support sessions across every organization, newest first", "description": "Support sessions across every organization, newest first. status is ACTIVE, ENDED or EXPIRED.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": false, "description": "Filter by organization ID.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "admin_user_id": { "type": "string" }, "admin_email": { "type": "string" }, "admin_name": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_by": { "type": [ "string", "null" ] }, "entered_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "request_count": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "sps_01m3v8k2q5r7t9w1y3b5d7f9h1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "organization_name": "Silk Road Events", "admin_user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "admin_email": "support@oqim.example.com", "admin_name": "Oqim support", "reason": "The customer reports replies stop after the third message; checking their conversation settings.", "created_at": "2026-09-26T09:30:00Z", "expires_at": "2026-10-01T12:30:00Z", "ended_at": null, "ended_by": null, "entered_at": "2026-09-26T09:30:00Z", "status": "ACTIVE", "request_count": 41 } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/support-sessions/{id}/end": { "post": { "operationId": "postAdminSupportSessionsByIdEnd", "summary": "End a session now", "description": "End a session now. Any platform administrator may end any session: it is a safety valve, not a privilege of whoever opened it. Access stops at once, because the browser session it ran as is deleted with it. The organization is told (SUPPORT_SESSION_ENDED). Ending one that already ended is harmless.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "admin_user_id": { "type": "string" }, "admin_email": { "type": "string" }, "admin_name": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_by": { "type": [ "string", "null" ] }, "entered_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "request_count": { "type": "integer" } } }, "example": { "id": "sps_01m3v8k2q5r7t9w1y3b5d7f9h1", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "organization_name": "Silk Road Events", "admin_user_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "admin_email": "support@oqim.example.com", "admin_name": "Oqim support", "reason": "The customer reports replies stop after the third message; checking their conversation settings.", "created_at": "2026-09-26T09:30:00Z", "expires_at": "2026-10-01T12:30:00Z", "ended_at": "2026-09-26T09:30:00Z", "ended_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "entered_at": "2026-09-26T09:30:00Z", "status": "ENDED", "request_count": 41 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/support-sessions/{id}/accesses": { "get": { "operationId": "getAdminSupportSessionsByIdAccesses", "summary": "Every request made under one session, oldest first, refused ones included", "description": "Every request made under one session, oldest first, refused ones included. The path only, never the query string, because a query can hold what someone searched for.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "support_session_id": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "method": { "type": "string" }, "status": { "type": "integer" }, "path": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": 1207, "support_session_id": "sps_01m3v8k2q5r7t9w1y3b5d7f9h1", "at": "2026-09-26T09:30:00Z", "method": "GET", "status": 200, "path": "/api/v1/ai/conversations" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations/{id}/limits": { "get": { "operationId": "getAdminOrganizationsByIdLimits", "summary": "What one organization may do, where that comes from, and how much of it is used: the plan's limits, the overrides the platform owner has set on top, the effective result, and current usage", "description": "What one organization may do, where that comes from, and how much of it is used: the plan's limits, the overrides the platform owner has set on top, the effective result, and current usage. A limit of 0 means unlimited.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" }, "plan_limits": { "type": "object", "properties": { "plan": { "type": "string" }, "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "team_members": { "type": "integer" }, "webhooks": { "type": "integer" }, "webhooks_enabled": { "type": "boolean" }, "api_access": { "type": "boolean" }, "analytics": { "type": "string" }, "price_monthly_usd": { "type": "integer" } } }, "overrides": { "type": "object", "properties": { "team_members": { "type": "integer" }, "webhooks_enabled": { "type": "boolean" }, "webhooks": { "type": "integer" } } }, "effective": { "type": "object", "properties": { "plan": { "type": "string" }, "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "team_members": { "type": "integer" }, "webhooks": { "type": "integer" }, "webhooks_enabled": { "type": "boolean" }, "api_access": { "type": "boolean" }, "analytics": { "type": "string" }, "price_monthly_usd": { "type": "integer" } } }, "usage": { "type": "object", "properties": { "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "members": { "type": "integer" }, "webhooks": { "type": "integer" } } } } }, "example": { "plan": "FREE", "plan_limits": { "plan": "FREE", "accounts": 1, "active_campaigns": 1, "recipients": 1000, "team_members": 2, "webhooks": 0, "webhooks_enabled": false, "api_access": true, "analytics": "basic", "price_monthly_usd": 0 }, "overrides": { "team_members": 5, "webhooks_enabled": true, "webhooks": 2 }, "effective": { "plan": "FREE", "accounts": 1, "active_campaigns": 1, "recipients": 1000, "team_members": 5, "webhooks": 2, "webhooks_enabled": true, "api_access": true, "analytics": "basic", "price_monthly_usd": 0 }, "usage": { "accounts": 1, "active_campaigns": 0, "recipients": 214, "members": 2, "webhooks": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAdminOrganizationsByIdLimits", "summary": "Set one organization's limits on top of its plan, for a customer who needs more (or less) than their tier without moving to another", "description": "Set one organization's limits on top of its plan, for a customer who needs more (or less) than their tier without moving to another. accounts, active_campaigns, recipients, team_members and webhooks take a whole number from 0 (unlimited) to 10,000,000; webhooks_enabled and api_access take a boolean. A limit you leave out follows the plan, and the whole set is replaced, so {\"overrides\": {}} clears them all. A field this API doesn't know is refused rather than ignored. A reason of at least 10 characters is required and is kept in the organization's audit log (ORGANIZATION_LIMITS_UPDATED) with the previous overrides. Lowering a limit below current usage deletes nothing: it only stops the organization adding more. Changing the plan leaves overrides in place.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overrides": { "type": "object", "properties": { "team_members": { "type": "integer" }, "webhooks_enabled": { "type": "boolean" }, "webhooks": { "type": "integer" } } }, "reason": { "type": "string" } } }, "example": { "overrides": { "team_members": 5, "webhooks_enabled": true, "webhooks": 2 }, "reason": "Pilot customer: five seats and webhooks while they evaluate." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string" }, "plan_limits": { "type": "object", "properties": { "plan": { "type": "string" }, "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "team_members": { "type": "integer" }, "webhooks": { "type": "integer" }, "webhooks_enabled": { "type": "boolean" }, "api_access": { "type": "boolean" }, "analytics": { "type": "string" }, "price_monthly_usd": { "type": "integer" } } }, "overrides": { "type": "object", "properties": { "team_members": { "type": "integer" }, "webhooks_enabled": { "type": "boolean" }, "webhooks": { "type": "integer" } } }, "effective": { "type": "object", "properties": { "plan": { "type": "string" }, "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "team_members": { "type": "integer" }, "webhooks": { "type": "integer" }, "webhooks_enabled": { "type": "boolean" }, "api_access": { "type": "boolean" }, "analytics": { "type": "string" }, "price_monthly_usd": { "type": "integer" } } }, "usage": { "type": "object", "properties": { "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "members": { "type": "integer" }, "webhooks": { "type": "integer" } } } } }, "example": { "plan": "FREE", "plan_limits": { "plan": "FREE", "accounts": 1, "active_campaigns": 1, "recipients": 1000, "team_members": 2, "webhooks": 0, "webhooks_enabled": false, "api_access": true, "analytics": "basic", "price_monthly_usd": 0 }, "overrides": { "team_members": 5, "webhooks_enabled": true, "webhooks": 2 }, "effective": { "plan": "FREE", "accounts": 1, "active_campaigns": 1, "recipients": 1000, "team_members": 5, "webhooks": 2, "webhooks_enabled": true, "api_access": true, "analytics": "basic", "price_monthly_usd": 0 }, "usage": { "accounts": 1, "active_campaigns": 0, "recipients": 214, "members": 2, "webhooks": 0 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations/{id}/ai/budgets": { "get": { "operationId": "getAdminOrganizationsByIdAiBudgets", "summary": "One organization's AI budgets (daily and monthly, each null when unset) with this period's spending, and their combined state", "description": "One organization's AI budgets (daily and monthly, each null when unset) with this period's spending, and their combined state. The same shape the organization sees at GET /ai/budgets.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "daily": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "messages_sent": { "type": "integer" }, "api_requests": { "type": "integer" } } } }, "monthly": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "period": { "type": "string" }, "limit_micros": { "type": "integer" }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "hard_stop": { "type": "boolean" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "limit_usd": { "type": "integer" }, "spent_micros": { "type": "integer" }, "spent_usd": { "type": "number" }, "ratio": { "type": "number" }, "state": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "resets_at": { "type": "string", "format": "date-time" } } } } }, "example": { "state": "SOFT_ALERT", "daily": null, "monthly": { "id": "abg_01j9s15f7h9k1m3p5r7t9v1x3z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "period": "MONTHLY", "limit_micros": 50000000, "alert_thresholds": [ 80, 100 ], "hard_stop": true, "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z", "limit_usd": 50, "spent_micros": 41200000, "spent_usd": 41.2, "ratio": 0.824, "state": "SOFT_ALERT", "period_start": "2026-09-01T00:00:00Z", "resets_at": "2026-10-01T00:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAdminOrganizationsByIdAiBudgets", "summary": "Set one organization's AI budgets, with the same body as the organization's own PUT /ai/budgets (daily and monthly each take {limit_usd, alert_thresholds, hard_stop}, null removes that budget, a period you leave out stays as it is) plus a reason of at least 10 characters", "description": "Set one organization's AI budgets, with the same body as the organization's own PUT /ai/budgets (daily and monthly each take {limit_usd, alert_thresholds, hard_stop}, null removes that budget, a period you leave out stays as it is) plus a reason of at least 10 characters. The change is audited against the organization as a platform administrator's, with the reason and the previous budgets (AI_BUDGET_UPDATED).\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthly": { "type": "object", "properties": { "limit_usd": { "type": "integer" }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "hard_stop": { "type": "boolean" } } }, "reason": { "type": "string" } } }, "example": { "monthly": { "limit_usd": 25, "alert_thresholds": [ 80, 100 ], "hard_stop": true }, "reason": "Runaway spend from a misconfigured loop; capped while we investigate." } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" }, "daily": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "messages_sent": { "type": "integer" }, "api_requests": { "type": "integer" } } } }, "monthly": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "period": { "type": "string" }, "limit_micros": { "type": "integer" }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "hard_stop": { "type": "boolean" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "limit_usd": { "type": "integer" }, "spent_micros": { "type": "integer" }, "spent_usd": { "type": "number" }, "ratio": { "type": "number" }, "state": { "type": "string" }, "period_start": { "type": "string", "format": "date-time" }, "resets_at": { "type": "string", "format": "date-time" } } } } }, "example": { "state": "ALLOWED", "daily": null, "monthly": { "id": "abg_01j9s15f7h9k1m3p5r7t9v1x3z", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "period": "MONTHLY", "limit_micros": 25000000, "alert_thresholds": [ 80, 100 ], "hard_stop": true, "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-20T08:00:00Z", "limit_usd": 25, "spent_micros": 3100000, "spent_usd": 3.1, "ratio": 0.124, "state": "ALLOWED", "period_start": "2026-09-01T00:00:00Z", "resets_at": "2026-10-01T00:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/organizations/{id}/ai/costs": { "get": { "operationId": "getAdminOrganizationsByIdAiCosts", "summary": "What one organization has spent on AI for period today, week (the last 7 UTC days) or month (the calendar month so far, the default): in total and by business, agent (the capability), provider, model and mode, plus a day-by-day series", "description": "What one organization has spent on AI for period today, week (the last 7 UTC days) or month (the calendar month so far, the default): in total and by business, agent (the capability), provider, model and mode, plus a day-by-day series. The same report the organization sees at GET /ai/costs.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Organization ID (org_…).", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "Filter by period.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string" }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "basis": { "type": "object", "properties": { "requests": { "type": "string" }, "tokens": { "type": "string" }, "cost": { "type": "string" } } }, "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } }, "by_business": { "type": "array", "items": { "type": "object", "properties": { "business_id": { "type": [ "string", "null" ] }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_agent": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_provider": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "string" }, "provider_kind": { "type": "string" }, "provider_name": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_model": { "type": "array", "items": { "type": "object", "properties": { "provider_kind": { "type": "string" }, "model": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "by_mode": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } }, "daily": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } } } } }, "example": { "period": "month", "from": "2026-09-01", "to": "2026-09-26", "currency": "USD", "basis": { "requests": "observed", "tokens": "observed", "cost": "derived" }, "totals": { "requests": 1840, "failed_requests": 1, "input_tokens": 3496000, "output_tokens": 202400, "embed_tokens": 25760, "cost_micros": 6412300, "cost_usd": 6.4123, "unpriced_requests": 0, "estimated_requests": 0 }, "by_business": [ { "business_id": "biz_01j9s28g0j2m4p6r8t0w2y4a6c", "requests": 1790, "failed_requests": 1, "input_tokens": 3401000, "output_tokens": 196900, "embed_tokens": 25060, "cost_micros": 6231000, "cost_usd": 6.231, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_agent": [ { "agent": "SELLER", "requests": 1210, "failed_requests": 1, "input_tokens": 2299000, "output_tokens": 133100, "embed_tokens": 16940, "cost_micros": 5102000, "cost_usd": 5.102, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_provider": [ { "provider_id": "aip_01j9rp8t0w2y4a6c8e0g2j4m6p", "provider_kind": "OPENAI", "provider_name": "OpenAI", "requests": 1840, "failed_requests": 1, "input_tokens": 3496000, "output_tokens": 202400, "embed_tokens": 25760, "cost_micros": 6412300, "cost_usd": 6.4123, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_model": [ { "provider_kind": "OPENAI", "model": "gpt-5.6", "requests": 1210, "failed_requests": 1, "input_tokens": 2299000, "output_tokens": 133100, "embed_tokens": 16940, "cost_micros": 5102000, "cost_usd": 5.102, "unpriced_requests": 0, "estimated_requests": 0 } ], "by_mode": [ { "mode": "LIVE", "requests": 1760, "failed_requests": 1, "input_tokens": 3344000, "output_tokens": 193600, "embed_tokens": 24640, "cost_micros": 6201000, "cost_usd": 6.201, "unpriced_requests": 0, "estimated_requests": 0 } ], "daily": [ { "date": "2026-09-26", "requests": 84, "failed_requests": 1, "input_tokens": 159600, "output_tokens": 9240, "embed_tokens": 1176, "cost_micros": 301400, "cost_usd": 0.3014, "unpriced_requests": 0, "estimated_requests": 0 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/abuse-reports": { "get": { "operationId": "getAdminAbuseReports", "summary": "Abuse reports, newest first", "description": "Abuse reports, newest first. Oqim files HIGH_FAILURE_RATE reports when it pauses a campaign for failures, OPT_OUT_SPIKE when it pauses one because recipients opt out right after receiving it, and ACCOUNT_RESTRICTIONS when an organization has three or more restricted accounts (at most one a day); administrators file MANUAL ones.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "severity": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "object", "properties": { "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" }, "attempts": { "type": "integer" }, "failure_rate": { "type": "number" }, "threshold": { "type": "number" }, "min_sample": { "type": "integer" }, "since_previous_pause": { "type": "boolean" } } }, "reported_by": { "type": "string" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "organization_name": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "abr_01j9rn5s7v9x1z3b5d7f9h1k3m", "organization_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0", "campaign_id": "cmp_01j9s1b3d5f7h9k1m3p5r7t9v1", "account_id": null, "kind": "HIGH_FAILURE_RATE", "severity": "MEDIUM", "status": "OPEN", "summary": "Campaign \"Autumn sale\" paused: 41% of 120 recent sends failed", "details": { "delivered": 71, "failed": 9, "unavailable": 40, "attempts": 120, "failure_rate": 0.408, "threshold": 0.35, "min_sample": 40, "since_previous_pause": false }, "reported_by": "SYSTEM", "resolved_by": null, "resolution_note": null, "created_at": "2026-09-26T08:02:00Z", "updated_at": "2026-09-26T08:02:00Z", "resolved_at": null, "organization_name": "Bright Deals Ltd" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAdminAbuseReports", "summary": "File a report by hand, optionally tied to one of the organization's campaigns or accounts", "description": "File a report by hand, optionally tied to one of the organization's campaigns or accounts. The summary is up to 500 characters; details takes any JSON object.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": [ "string", "null" ] }, "severity": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "object", "properties": { "source": { "type": "string" } } } } }, "example": { "organization_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0", "severity": "MEDIUM", "summary": "Recipient emailed support: three promotional messages without ever signing up.", "details": { "source": "support ticket 4412" } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "severity": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "object", "properties": { "source": { "type": "string" } } }, "reported_by": { "type": "string" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "organization_name": { "type": "string" } } }, "example": { "id": "abr_01j9rn5s7v9x1z3b5d7f9h1k3m", "organization_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0", "campaign_id": null, "account_id": null, "kind": "MANUAL", "severity": "MEDIUM", "status": "OPEN", "summary": "Recipient emailed support: three promotional messages without ever signing up.", "details": { "source": "support ticket 4412" }, "reported_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "resolved_by": null, "resolution_note": null, "created_at": "2026-09-26T08:02:00Z", "updated_at": "2026-09-26T08:02:00Z", "resolved_at": null, "organization_name": "Bright Deals Ltd" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/abuse-reports/{id}": { "patch": { "operationId": "patchAdminAbuseReportsById", "summary": "Set a report's status (OPEN, REVIEWING, RESOLVED or DISMISSED) and resolution note, and optionally suspend its organization in the same call", "description": "Set a report's status (OPEN, REVIEWING, RESOLVED or DISMISSED) and resolution note, and optionally suspend its organization in the same call.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Abuse report ID (abr_…).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "resolution_note": { "type": [ "string", "null" ] }, "suspend_organization": { "type": "boolean" } } }, "example": { "status": "RESOLVED", "resolution_note": "Confirmed a purchased contact list. Organization suspended.", "suspend_organization": true } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "campaign_id": { "type": [ "string", "null" ] }, "account_id": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "severity": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "object", "properties": { "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "unavailable": { "type": "integer" }, "attempts": { "type": "integer" }, "failure_rate": { "type": "number" }, "threshold": { "type": "number" }, "min_sample": { "type": "integer" }, "since_previous_pause": { "type": "boolean" } } }, "reported_by": { "type": "string" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "organization_name": { "type": "string" } } }, "example": { "id": "abr_01j9rn5s7v9x1z3b5d7f9h1k3m", "organization_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0", "campaign_id": "cmp_01j9s1b3d5f7h9k1m3p5r7t9v1", "account_id": null, "kind": "HIGH_FAILURE_RATE", "severity": "MEDIUM", "status": "RESOLVED", "summary": "Campaign \"Autumn sale\" paused: 41% of 120 recent sends failed", "details": { "delivered": 71, "failed": 9, "unavailable": 40, "attempts": 120, "failure_rate": 0.408, "threshold": 0.35, "min_sample": 40, "since_previous_pause": false }, "reported_by": "SYSTEM", "resolved_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "resolution_note": "Confirmed a purchased contact list. Organization suspended.", "created_at": "2026-09-26T08:02:00Z", "updated_at": "2026-09-26T08:02:00Z", "resolved_at": "2026-09-26T09:30:00Z", "organization_name": "Bright Deals Ltd" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/audit-logs": { "get": { "operationId": "getAdminAuditLogs", "summary": "Audit entries from every organization plus platform-level ones, filtered like the organization audit log", "description": "Audit entries from every organization plus platform-level ones, filtered like the organization audit log.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": false, "description": "Filter by organization ID.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Filter by action.", "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "description": "Filter by actor ID.", "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "required": false, "description": "Filter by target ID.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Entries from this RFC 3339 time or date.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Entries up to this time; a plain date includes that whole day.", "schema": { "type": "string", "anyOf": [ { "format": "date-time" }, { "format": "date" } ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "organization_id": { "type": [ "string", "null" ] }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "actor_label": { "type": "string" }, "action": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "ip": { "type": "string" }, "user_agent": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string" }, "paused_campaigns": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": 88412, "organization_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0", "actor_type": "PLATFORM_ADMIN", "actor_id": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "actor_label": "ops@oqim.example", "action": "ORGANIZATION_SUSPENDED", "target_type": "organization", "target_id": "org_01j9s0a2c4e6g8j0m2p4r6t8w0", "ip": "203.0.113.24", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6)", "metadata": { "reason": "Purchased contact list", "paused_campaigns": 2 }, "created_at": "2026-09-29T14:02:11Z" } ], "total": 1, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/settings": { "get": { "operationId": "getAdminSettings", "summary": "Platform settings", "description": "Platform settings.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signups_enabled": { "type": "boolean" }, "allow_unknown_consent": { "type": "boolean" }, "require_opt_out_link": { "type": "boolean" }, "default_daily_limit": { "type": "integer" }, "max_daily_limit": { "type": "integer" }, "default_interval_seconds": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "max_flood_wait_seconds": { "type": "integer" }, "failure_rate_pause_threshold": { "type": "number" }, "failure_rate_min_sample": { "type": "integer" }, "opt_out_spike_threshold": { "type": "number" }, "opt_out_spike_min_count": { "type": "integer" }, "max_recipients_per_campaign": { "type": "integer" }, "aup_version": { "type": [ "string", "null" ] }, "maintenance_mode": { "type": "boolean" }, "ai_allow_private_endpoints": { "type": "boolean" }, "ai_enabled": { "type": "boolean" }, "ai_seller_enabled": { "type": "boolean" }, "ai_conversation_intelligence_enabled": { "type": "boolean" }, "ai_calendar_enabled": { "type": "boolean" }, "ai_research_enabled": { "type": "boolean" }, "ai_jev_enabled": { "type": "boolean" }, "jev_platform_key_enabled": { "type": "boolean" } } }, "example": { "signups_enabled": true, "allow_unknown_consent": false, "require_opt_out_link": false, "default_daily_limit": 150, "max_daily_limit": 500, "default_interval_seconds": 8, "min_interval_seconds": 4, "max_flood_wait_seconds": 900, "failure_rate_pause_threshold": 0.35, "failure_rate_min_sample": 40, "opt_out_spike_threshold": 0.05, "opt_out_spike_min_count": 5, "max_recipients_per_campaign": 50000, "aup_version": "2026-09", "maintenance_mode": false, "ai_allow_private_endpoints": false, "ai_enabled": true, "ai_seller_enabled": true, "ai_conversation_intelligence_enabled": true, "ai_calendar_enabled": true, "ai_research_enabled": true, "ai_jev_enabled": true, "jev_platform_key_enabled": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "putAdminSettings", "summary": "Update platform settings", "description": "Update platform settings. Keys you leave out keep their value. failure_rate_pause_threshold and opt_out_spike_threshold are fractions between 0 and 1; a campaign pauses when at least opt_out_spike_min_count recipients opt out after receiving it and they make up opt_out_spike_threshold of its deliveries. Services pick changes up within about five seconds.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "require_opt_out_link": { "type": "boolean" } } }, "example": { "require_opt_out_link": true } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "signups_enabled": { "type": "boolean" }, "allow_unknown_consent": { "type": "boolean" }, "require_opt_out_link": { "type": "boolean" }, "default_daily_limit": { "type": "integer" }, "max_daily_limit": { "type": "integer" }, "default_interval_seconds": { "type": "integer" }, "min_interval_seconds": { "type": "integer" }, "max_flood_wait_seconds": { "type": "integer" }, "failure_rate_pause_threshold": { "type": "number" }, "failure_rate_min_sample": { "type": "integer" }, "opt_out_spike_threshold": { "type": "number" }, "opt_out_spike_min_count": { "type": "integer" }, "max_recipients_per_campaign": { "type": "integer" }, "aup_version": { "type": [ "string", "null" ] }, "maintenance_mode": { "type": "boolean" }, "ai_allow_private_endpoints": { "type": "boolean" }, "ai_enabled": { "type": "boolean" }, "ai_seller_enabled": { "type": "boolean" }, "ai_conversation_intelligence_enabled": { "type": "boolean" }, "ai_calendar_enabled": { "type": "boolean" }, "ai_research_enabled": { "type": "boolean" }, "ai_jev_enabled": { "type": "boolean" }, "jev_platform_key_enabled": { "type": "boolean" } } }, "example": { "signups_enabled": true, "allow_unknown_consent": false, "require_opt_out_link": true, "default_daily_limit": 150, "max_daily_limit": 500, "default_interval_seconds": 8, "min_interval_seconds": 4, "max_flood_wait_seconds": 900, "failure_rate_pause_threshold": 0.35, "failure_rate_min_sample": 40, "opt_out_spike_threshold": 0.05, "opt_out_spike_min_count": 5, "max_recipients_per_campaign": 50000, "aup_version": "2026-09", "maintenance_mode": false, "ai_allow_private_endpoints": false, "ai_enabled": true, "ai_seller_enabled": true, "ai_conversation_intelligence_enabled": true, "ai_calendar_enabled": true, "ai_research_enabled": true, "ai_jev_enabled": true, "jev_platform_key_enabled": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/billing": { "get": { "operationId": "getAdminBilling", "summary": "Plan limits, organizations per plan, and a page of organizations with their usage over 30 days", "description": "Plan limits, organizations per plan, and a page of organizations with their usage over 30 days.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "plan", "in": "query", "required": false, "description": "Filter by plan.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string" }, "accounts": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "recipients": { "type": "integer" }, "team_members": { "type": "integer" }, "webhooks": { "type": "integer" }, "api_access": { "type": "boolean" }, "analytics": { "type": "string" }, "price_monthly_usd": { "type": "integer" } } } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": "string" }, "status": { "type": "string" }, "accounts": { "type": "integer" }, "members": { "type": "integer" }, "active_campaigns": { "type": "integer" }, "messages_30d": { "type": "integer" }, "api_requests_30d": { "type": "integer" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "totals_by_plan": { "type": "object", "properties": { "FREE": { "type": "integer" }, "PRO": { "type": "integer" }, "BUSINESS": { "type": "integer" }, "ENTERPRISE": { "type": "integer" } } } } }, "example": { "plans": [ { "plan": "PRO", "accounts": 10, "active_campaigns": 10, "recipients": 50000, "team_members": 5, "webhooks": 5, "api_access": true, "analytics": "basic", "price_monthly_usd": 49 } ], "organizations": [ { "id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "name": "Silk Road Events", "plan": "PRO", "status": "ACTIVE", "accounts": 3, "members": 4, "active_campaigns": 1, "messages_30d": 21904, "api_requests_30d": 4120 } ], "total": 42, "limit": 50, "offset": 0, "totals_by_plan": { "FREE": 29, "PRO": 9, "BUSINESS": 3, "ENTERPRISE": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/ai/overview": { "get": { "operationId": "getAdminAiOverview", "summary": "AI across the platform: the AI switches, usage and cost today and this month, the tenants with the most spending over 30 days (with their failed and blocked runs of the last 24 hours), runs by agent over 24 hours, models used without a price, and provider health: attempts, failures and latency per provider over 24 hours, and the provider connections cooling off now after repeated failures", "description": "AI across the platform: the AI switches, usage and cost today and this month, the tenants with the most spending over 30 days (with their failed and blocked runs of the last 24 hours), runs by agent over 24 hours, models used without a price, and provider health: attempts, failures and latency per provider over 24 hours, and the provider connections cooling off now after repeated failures.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "switches": { "type": "object", "properties": { "ai_enabled": { "type": "boolean" }, "ai_seller_enabled": { "type": "boolean" }, "ai_conversation_intelligence_enabled": { "type": "boolean" }, "ai_calendar_enabled": { "type": "boolean" }, "ai_research_enabled": { "type": "boolean" }, "ai_jev_enabled": { "type": "boolean" }, "jev_platform_key_enabled": { "type": "boolean" } } }, "today": { "type": "object", "properties": { "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } }, "month": { "type": "object", "properties": { "requests": { "type": "integer" }, "failed_requests": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "embed_tokens": { "type": "integer" }, "cost_micros": { "type": "integer" }, "cost_usd": { "type": "number" }, "unpriced_requests": { "type": "integer" }, "estimated_requests": { "type": "integer" } } }, "tenants": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "requests_today": { "type": "integer" }, "cost_micros_today": { "type": "integer" }, "requests_30d": { "type": "integer" }, "failed_requests_30d": { "type": "integer" }, "cost_micros_30d": { "type": "integer" }, "cost_usd_30d": { "type": "number" }, "unpriced_requests_30d": { "type": "integer" }, "executions_24h": { "type": "integer" }, "failed_executions_24h": { "type": "integer" }, "blocked_executions_24h": { "type": "integer" } } } }, "agents_24h": { "type": "array", "items": { "type": "object", "properties": { "agent": { "type": "string" }, "executions": { "type": "integer" }, "failed": { "type": "integer" }, "blocked": { "type": "integer" } } } }, "unpriced_models": { "type": "array", "items": { "type": "object", "properties": { "provider_kind": { "type": "string" }, "model": { "type": "string" }, "requests_30d": { "type": "integer" } } } }, "providers": { "type": "array", "items": { "type": "object", "properties": { "provider_kind": { "type": "string" }, "requests_24h": { "type": "integer" }, "failures_24h": { "type": "integer" }, "error_rate": { "type": "number" }, "avg_latency_ms": { "type": "integer" } } } }, "cooling": { "type": "array", "items": { "type": "object", "properties": { "provider_id": { "type": "string" }, "model": { "type": "string" }, "until": { "type": [ "string", "null" ], "format": "date-time" }, "failures": { "type": "integer" }, "last_error_code": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "organization_name": { "type": "string" }, "provider_name": { "type": "string" }, "provider_kind": { "type": "string" } } } } } }, "example": { "switches": { "ai_enabled": true, "ai_seller_enabled": true, "ai_conversation_intelligence_enabled": true, "ai_calendar_enabled": true, "ai_research_enabled": true, "ai_jev_enabled": true, "jev_platform_key_enabled": true }, "today": { "requests": 3120, "failed_requests": 1, "input_tokens": 5928000, "output_tokens": 343200, "embed_tokens": 43680, "cost_micros": 10412000, "cost_usd": 10.412, "unpriced_requests": 0, "estimated_requests": 0 }, "month": { "requests": 71840, "failed_requests": 1, "input_tokens": 136496000, "output_tokens": 7902400, "embed_tokens": 1005760, "cost_micros": 248331000, "cost_usd": 248.331, "unpriced_requests": 0, "estimated_requests": 0 }, "tenants": [ { "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "organization_name": "Silk Road Events", "requests_today": 84, "cost_micros_today": 301400, "requests_30d": 1840, "failed_requests_30d": 3, "cost_micros_30d": 6412300, "cost_usd_30d": 6.4123, "unpriced_requests_30d": 0, "executions_24h": 91, "failed_executions_24h": 1, "blocked_executions_24h": 0 } ], "agents_24h": [ { "agent": "SELLER", "executions": 2210, "failed": 14, "blocked": 0 } ], "unpriced_models": [ { "provider_kind": "CUSTOM", "model": "qwen3:8b", "requests_30d": 312 } ], "providers": [ { "provider_kind": "OPENAI", "requests_24h": 2980, "failures_24h": 21, "error_rate": 0.007, "avg_latency_ms": 1840 } ], "cooling": [ { "provider_id": "aip_01j9rq1v3x5z7b9d1f3h5k7m9p", "model": "qwen3:8b", "until": "2026-09-26T09:30:30Z", "failures": 3, "last_error_code": "timeout", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "organization_name": "Silk Road Events", "provider_name": "Office GPU server", "provider_kind": "CUSTOM" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/ai/models": { "get": { "operationId": "getAdminAiModels", "summary": "The whole model registry: platform entries first, then organization entries with their organization's name", "description": "The whole model registry: platform entries first, then organization entries with their organization's name. organization_id filters (platform for platform entries only); q matches the model ID or name.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "organization_id", "in": "query", "required": false, "description": "Filter by organization ID.", "schema": { "type": "string" } }, { "name": "provider_kind", "in": "query", "required": false, "description": "Filter by provider kind.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search text.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "How many items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "provider_kind": { "type": "string" }, "model_id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "context_window": { "type": "integer" }, "price_in_per_mtok": { "type": [ "number", "null" ] }, "price_out_per_mtok": { "type": [ "integer", "null" ] }, "price_embed_per_mtok": { "type": [ "number", "null" ] }, "enabled": { "type": "boolean" }, "created_by": { "type": [ "string", "null" ] }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "priced": { "type": "boolean" }, "organization_name": { "type": "string" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "example": { "data": [ { "id": "aim_01j9rs4w6y8a0c2e4g6j8m0p2r", "organization_id": null, "provider_kind": "OPENAI", "model_id": "gpt-5.6", "display_name": "GPT-5.6", "capabilities": [ "CHAT", "STRUCTURED" ], "context_window": 400000, "price_in_per_mtok": 1.25, "price_out_per_mtok": 10, "price_embed_per_mtok": null, "enabled": true, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "scope": "PLATFORM", "priced": true }, { "id": "aim_01j9s8fp1s3v5x7z9b1d3f5h7k", "organization_id": "org_01j9r2m6k4n8q3v5w7x9y1z2a3", "provider_kind": "OPENAI", "model_id": "gpt-5.6", "display_name": "GPT-5.6", "capabilities": [ "CHAT", "STRUCTURED" ], "context_window": 400000, "price_in_per_mtok": 1, "price_out_per_mtok": 8, "price_embed_per_mtok": null, "enabled": true, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "scope": "ORGANIZATION", "priced": true, "organization_name": "Silk Road Events" } ], "total": 2, "limit": 50, "offset": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postAdminAiModels", "summary": "Register a model: provider_kind and model_id as the provider lists it, capabilities (CHAT, STRUCTURED, EMBEDDINGS; default CHAT and STRUCTURED), context_window, and prices in USD per million tokens for input, output and embedding tokens (null when not known: calls are then unpriced)", "description": "Register a model: provider_kind and model_id as the provider lists it, capabilities (CHAT, STRUCTURED, EMBEDDINGS; default CHAT and STRUCTURED), context_window, and prices in USD per million tokens for input, output and embedding tokens (null when not known: calls are then unpriced). With organization_id the entry applies to that organization only, over the platform's. Nothing is pre-filled: enter the provider's current prices.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider_kind": { "type": "string" }, "model_id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "context_window": { "type": "integer" }, "price_in_per_mtok": { "type": [ "number", "null" ] }, "price_out_per_mtok": { "type": [ "integer", "null" ] } } }, "example": { "provider_kind": "OPENAI", "model_id": "gpt-5.6", "display_name": "GPT-5.6", "capabilities": [ "CHAT", "STRUCTURED" ], "context_window": 400000, "price_in_per_mtok": 1.25, "price_out_per_mtok": 10 } } } }, "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "provider_kind": { "type": "string" }, "model_id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "context_window": { "type": "integer" }, "price_in_per_mtok": { "type": [ "number", "null" ] }, "price_out_per_mtok": { "type": [ "integer", "null" ] }, "price_embed_per_mtok": { "type": [ "number", "null" ] }, "enabled": { "type": "boolean" }, "created_by": { "type": [ "string", "null" ] }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "priced": { "type": "boolean" } } }, "example": { "id": "aim_01j9rs4w6y8a0c2e4g6j8m0p2r", "organization_id": null, "provider_kind": "OPENAI", "model_id": "gpt-5.6", "display_name": "GPT-5.6", "capabilities": [ "CHAT", "STRUCTURED" ], "context_window": 400000, "price_in_per_mtok": 1.25, "price_out_per_mtok": 10, "price_embed_per_mtok": null, "enabled": true, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "scope": "PLATFORM", "priced": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/admin/ai/models/{id}": { "patch": { "operationId": "patchAdminAiModelsById", "summary": "Change a registry entry's name, capabilities, context window, prices or enabled (a disabled model is hidden from organizations but still prices past and running usage)", "description": "Change a registry entry's name, capabilities, context window, prices or enabled (a disabled model is hidden from organizations but still prices past and running usage). Its scope, provider and model ID don't change. New prices apply to calls from then on, within a minute everywhere.\n\nPlatform administrators only, in a console session with two-factor authentication verified. API keys are refused.", "tags": [ "Administration API" ], "x-oqim-permission": "Platform admin", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price_in_per_mtok": { "type": [ "number", "null" ] }, "price_out_per_mtok": { "type": [ "integer", "null" ] } } }, "example": { "price_in_per_mtok": 1.1, "price_out_per_mtok": 9 } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organization_id": { "type": [ "string", "null" ] }, "provider_kind": { "type": "string" }, "model_id": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "context_window": { "type": "integer" }, "price_in_per_mtok": { "type": [ "number", "null" ] }, "price_out_per_mtok": { "type": [ "integer", "null" ] }, "price_embed_per_mtok": { "type": [ "number", "null" ] }, "enabled": { "type": "boolean" }, "created_by": { "type": [ "string", "null" ] }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "priced": { "type": "boolean" } } }, "example": { "id": "aim_01j9rs4w6y8a0c2e4g6j8m0p2r", "organization_id": null, "provider_kind": "OPENAI", "model_id": "gpt-5.6", "display_name": "GPT-5.6", "capabilities": [ "CHAT", "STRUCTURED" ], "context_window": 400000, "price_in_per_mtok": 1.1, "price_out_per_mtok": 9, "price_embed_per_mtok": null, "enabled": true, "created_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "updated_by": "usr_01j9r2n0d5c7b9a1e3f5g7h9jk", "created_at": "2026-09-20T08:00:00Z", "updated_at": "2026-09-26T09:30:00Z", "scope": "PLATFORM", "priced": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (oqk_…) or access token (oqat_…)", "description": "An API key (oqk_…), or a one-hour access token (oqat_…) from POST /auth/token. Either acts as the API_CLIENT role in the key's organization." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "oqim_session", "description": "The console session, set by POST /auth/login. Requests that change data with it must come from an allowed origin (origin_rejected otherwise)." } }, "schemas": { "Error": { "type": "object", "description": "Every error has this envelope. Branch on code; show message to people. A few errors add fields next to error, such as validation on campaign_invalid.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable and machine-readable. See /docs/errors.", "examples": [ "validation_failed" ] }, "message": { "type": "string", "description": "A sentence written for people. It may change, so don't parse it." }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "description": "With validation_failed only: each invalid request field and its message." } } } } } }, "responses": { "BadRequest": { "description": "The body isn't valid JSON, or an upload couldn't be read.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_json": { "value": { "error": { "code": "invalid_json", "message": "Request body is not valid JSON: unexpected EOF" } } } } } } }, "Unauthorized": { "description": "No credential, a wrong one, or a session still waiting for its two-factor code.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "unauthenticated": { "value": { "error": { "code": "unauthenticated", "message": "Sign in to continue." } } } } } } }, "Forbidden": { "description": "The role lacks the permission, the organization is suspended or hasn't accepted the policy, or a plan limit is reached.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "forbidden": { "value": { "error": { "code": "forbidden", "message": "Your role (VIEWER) can't do this. It needs campaigns:manage." } } } } } } }, "NotFound": { "description": "No such object in this organization.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "That resource doesn't exist or you don't have access to it." } } } } } } }, "Conflict": { "description": "The object's state doesn't allow this, or it conflicts with an existing record.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_state": { "value": { "error": { "code": "invalid_state", "message": "This campaign already finished, so there's nothing to cancel." } } } } } } }, "Gone": { "description": "The invitation was used, revoked or expired.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invitation_expired": { "value": { "error": { "code": "invitation_expired", "message": "This invitation has expired. Ask for a new one." } } } } } } }, "PayloadTooLarge": { "description": "The upload is over its size limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "file_too_large": { "value": { "error": { "code": "file_too_large", "message": "Attachments can be up to 20 MB." } } } } } } }, "ValidationFailed": { "description": "Some fields are invalid; details maps each one to a message.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": { "code": "validation_failed", "message": "Some fields need attention.", "details": { "name": "Give the campaign a name.", "window_days": "Choose at least one day." } } } } } } } }, "TooManyRequests": { "description": "Too many requests: wait for Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "Too many requests. Slow down and retry shortly." } } } } } } }, "InternalError": { "description": "Something failed on Oqim's side. It was logged; retrying a read is safe.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "value": { "error": { "code": "internal_error", "message": "Something went wrong on our side. The error was logged." } } } } } } } }, "headers": { "RequestId": { "description": "The request's ID, as logged by the API: the X-Request-Id you sent, or one it generated. Quote it when reporting a problem.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying: the rate-limit window.", "schema": { "type": "integer" } }, "RateLimitLimit": { "description": "Requests allowed in the window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } } } } }