AI Agent API

Check the token

GET /api/v1/me

Returns the token name, permissions and expiry, and the agent it is bound to. Use it to check an integration: works with any permission.

Permission: any

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/me

Response

{
  "token": {
    "id": "6f1c2a9e-4b7d-4f0e-9a51-0c3d2e8b7a10",
    "name": "CRM",
    "prefix": "usv_agt_Ab3x",
    "scopes": ["read", "ask"],
    "createdAt": "2026-10-25T09:12:44.000Z",
    "expiresAt": "2027-01-23T09:12:44.000Z"
  },
  "agent": { "id": "1a2b3c4d-…", "name": "Store assistant" }
}

Agent and its channels

GET /api/v1/agents/{agentId}

Agent name, instance state and connected messengers. Channel statuses come from the database without polling the agent, so the call is fast.

Permission: read

Response fields

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID

Response

{
  "id": "1a2b3c4d-…",
  "name": "Store assistant",
  "status": "ACTIVE",
  "instanceStatus": "RUNNING",
  "channels": [
    { "messenger": "TELEGRAM", "status": "CONNECTED", "account": null, "updatedAt": "2026-10-20T08:00:00.000Z" }
  ]
}

Channels with a live login check

GET /api/v1/agents/{agentId}/channels

Like the channels above, but a running agent also verifies that the messenger account is actually logged in. Slower — use it when you need the exact status.

Permission: read

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/channels

Response

{ "channels": [ { "messenger": "VK", "status": "CONNECTED", "account": null, "updatedAt": "…" } ] }

Agent state

GET /api/v1/agents/{agentId}/instance

Whether the agent instance is running. Messenger replies, ask and sending work only in the RUNNING state.

Permission: read

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/instance

Response

{ "status": "RUNNING", "error": null }

Start, stop or restart

POST /api/v1/agents/{agentId}/instance

Agent uptime is billed at the rate shown in your account: starting checks the owner's balance. The agent takes 1–3 minutes to come up — poll the state until it is RUNNING.

Permission: manage

Request body (JSON)

Request

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"action":"start"}' https://usveree.ru/api/v1/agents/$AGENT_ID/instance

Response

{ "status": "STARTING" }

Possible errors: INSUFFICIENT_BALANCE, INSTANCE_BUSY, INSTANCE_LIMIT_REACHED, START_FAILED

Statistics

GET /api/v1/agents/{agentId}/stats

Total uptime, number of starts, start/stop log, message volume for 7 and 30 days, and AI usage (tokens and charges in kopecks).

Permission: read

• messages.out7d and out30d count only the agent's replies — not manual messages or messages sent via the API.

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/stats

Response

{
  "instance": { "status": "RUNNING", "totalUptimeSeconds": 864000, "starts": 4 },
  "messages": { "in7d": 312, "out7d": 280, "in30d": 1290, "out30d": 1144, "chats": 87 },
  "events": [ { "kind": "START", "detail": null, "at": "2026-10-20T08:00:00.000Z" } ],
  "ai": {
    "keySource": "SERVICE",
    "tokens": {
      "today": { "prompt": 41000, "completion": 5200, "calls": 38 },
      "d7": { "prompt": 302000, "completion": 39000, "calls": 290 },
      "d30": { "prompt": 1250000, "completion": 160000, "calls": 1180 }
    },
    "costKop": { "today": 210, "d7": 1580, "d30": 6400 }
  }
}

Messenger chats

GET /api/v1/agents/{agentId}/chats

Chats visible to the account plus chats the agent knows from history. The chatId from here works for chat history and for sending a message.

Permission: read

Query parameters

Response fields

• The call queries the messenger account and may take up to 30 seconds.

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  "https://usveree.ru/api/v1/agents/$AGENT_ID/chats?messenger=TELEGRAM"

Response

{
  "chats": [
    {
      "chatId": "512345678",
      "userId": "512345678",
      "title": "Anna",
      "type": "PERSONAL",
      "url": "https://t.me/anna_example",
      "messages": 14,
      "autoReply": "AUTO",
      "autoReplyDefault": true,
      "pausedUntil": null,
      "sendBlocked": false,
      "available": true,
      "leftAt": null
    }
  ],
  "liveAvailable": true
}

Conversation feed

GET /api/v1/agents/{agentId}/conversations

All agent messages across chats, newest first — like the Conversations tab: incoming messages with their outcome, agent replies, manual messages, messages sent via the API and comments under posts.

Permission: read

Query parameters

Response fields

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  "https://usveree.ru/api/v1/agents/$AGENT_ID/conversations?show=unanswered&limit=20"

Response

{
  "entries": [
    {
      "id": "0b9e…",
      "kind": "MESSAGE",
      "direction": "IN",
      "at": "2026-10-25T10:02:11.000Z",
      "messenger": "TELEGRAM",
      "chatId": "512345678",
      "chatTitle": "Anna",
      "chatType": "PERSONAL",
      "chatUrl": "https://t.me/anna_example",
      "senderName": "Anna",
      "text": "Hi! Do you deliver to Kazan?",
      "author": null,
      "reply": "PENDING",
      "context": null,
      "deleted": false
    }
  ],
  "nextCursor": "2026-10-25T10:02:11.123456Z|0b9e…"
}

Chat history

GET /api/v1/agents/{agentId}/messages

Messages of one chat in chronological order (oldest first). Messenger service messages are not returned.

Permission: read

Query parameters

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  "https://usveree.ru/api/v1/agents/$AGENT_ID/messages?messenger=TELEGRAM&chatId=512345678&limit=20"

Response

{
  "messages": [
    { "id": "…", "direction": "IN", "author": null, "senderId": "512345678", "senderName": "Anna", "text": "Hi! Do you deliver to Kazan?", "at": "2026-10-25T10:02:11.000Z" },
    { "id": "…", "direction": "OUT", "author": "AGENT", "senderId": null, "senderName": null, "text": "Hi Anna! Yes, we deliver to Kazan in 2–3 days. Shall I check the price?", "at": "2026-10-25T10:02:48.000Z" }
  ],
  "hasMore": true,
  "nextBefore": "2026-10-24T18:40:05.000Z"
}

Get the agent's answer to a text

POST /api/v1/agents/{agentId}/ask

The agent answers the same way as in a live chat: using its prompt, behaviour rules and tools (site search, catalog). Nothing is sent to messengers or saved to conversations. Works even with auto-replies off; the agent must be running. AI usage is counted and billed as usual.

Permission: ask

Request body (JSON)

Response fields

• The answer may take up to 170 seconds when the agent calls tools. Set a client timeout of at least 180 seconds.
• Keep the dialogue history on your side and pass it in history — the server does not store it.

Request

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  --max-time 180 \
  -d '{"text":"How much is delivery to Kazan?","history":[{"role":"user","text":"Hello"}]}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/ask

Response

{
  "shouldRespond": true,
  "message": "Delivery to Kazan is 390 ₽, free over 5,000 ₽.",
  "reason": "delivery question",
  "action": null,
  "deliverTo": "chat",
  "toolCalls": [ { "tool": "search_site", "status": "OK", "errorCode": null, "durationMs": 820 } ]
}

Possible errors: NO_BALANCE, AI_NOT_CONNECTED, AGENT_OUTDATED, INSTANCE_NOT_RUNNING, AGENT_UNAVAILABLE

Moderation queue

GET /api/v1/agents/{agentId}/pending-replies

Replies awaiting a decision: the incoming message and the reply prepared by the agent.

Permission: moderate

Query parameters

Response fields

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/pending-replies

Response

{
  "replies": [
    {
      "id": "c7d1…",
      "messenger": "TELEGRAM",
      "chatId": "512345678",
      "chatTitle": "Anna",
      "chatType": "PERSONAL",
      "chatUrl": "https://t.me/anna_example",
      "messageUrl": null,
      "sender": { "id": "512345678", "name": "Anna" },
      "incomingText": "Hi! Do you deliver to Kazan?",
      "replyText": "Hi Anna! Yes, we deliver to Kazan in 2–3 days. Shall I check the price?",
      "suggestedDeliverTo": "chat",
      "reason": "MANUAL",
      "kind": "MESSAGE",
      "createdAt": "2026-10-25T10:02:12.000Z",
      "fromPreviousAccount": false
    }
  ]
}

Send a queued reply

POST /api/v1/agents/{agentId}/pending-replies/{replyId}/send

Sends the prepared reply — as is or edited. Without deliverTo it goes where the agent suggested.

Permission: moderate

Request body (JSON)

Request

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"text":"Hi Anna! Yes, we deliver to Kazan in 2–3 days. Shall I check the price?"}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/pending-replies/$REPLY_ID/send

Response

{ "sent": true }

Possible errors: REPLY_NOT_FOUND, REPLY_ALREADY_DECIDED, CHAT_NOT_JOINED, TARGET_OFF, ACCOUNT_PAUSED, SEND_FAILED, CHANNEL_UNAVAILABLE

Reject a queued reply

POST /api/v1/agents/{agentId}/pending-replies/{replyId}/ignore

The reply is not sent and leaves the queue.

Permission: moderate

Request

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/pending-replies/$REPLY_ID/ignore

Response

{ "ok": true }

Possible errors: REPLY_NOT_FOUND, REPLY_ALREADY_DECIDED

Send a message to a chat

POST /api/v1/agents/{agentId}/messages

The message is sent on behalf of the connected account to a chat the agent already knows: it is in the chat list or in the conversations. In the Conversations tab it is labelled API and becomes part of the agent's context as its own turn.

Permission: send

Request body (JSON)

• Anti-ban protection applies as for agent replies: a switched-off recipient or a paused messenger blocks sending.
• Messages sent via the API count towards the agent's replies-per-hour limit.

Request

curl -s -X POST -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"messenger":"TELEGRAM","chatId":"512345678","text":"Your order #1024 has been shipped."}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/messages

Response

{ "sent": true, "messageId": "5e0f…" }

Possible errors: CHAT_NOT_FOUND, DAILY_LIMIT, CHAT_NOT_JOINED, TARGET_OFF, ACCOUNT_PAUSED, SEND_FAILED, CHANNEL_UNAVAILABLE, AGENT_OUTDATED, INSTANCE_NOT_RUNNING

Prompts

GET /api/v1/agents/{agentId}/prompts

Prompts by messenger (ALL — shared) and chat type: PERSONAL — direct chats, GROUP — groups, COMMENT — comments under posts. The trigger describes when the agent should react, the reaction — how to answer.

Permission: manage

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/prompts

Response

{
  "prompts": [
    {
      "id": "…",
      "messenger": "ALL",
      "scope": "PERSONAL",
      "triggerText": "Answer questions about products and delivery.",
      "reactionText": "Polite and short. Offer to place an order.",
      "allowDm": false,
      "autoRespond": true,
      "enabled": true,
      "replyAsQuote": true,
      "updatedAt": "2026-10-20T08:00:00.000Z"
    }
  ]
}

Update a prompt

PATCH /api/v1/agents/{agentId}/prompts

Creates or updates the prompt of one messenger + chat type pair. Omitted fields keep their values. The agent picks up changes immediately.

Permission: manage

Request body (JSON)

Request

curl -s -X PATCH -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"scope":"PERSONAL","reactionText":"Answer briefly and kindly."}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/prompts

Response

{ "prompt": { "id": "…", "messenger": "ALL", "scope": "PERSONAL", "…": "…" } }

Possible errors: UNKNOWN_FIELD, INVALID_FIELD

Agent settings

GET /api/v1/agents/{agentId}/settings

Auto-send, reply delay and limit, schedule, operator handover, behaviour rules and anti-ban protection.

Permission: manage

Request

curl -s -H "Authorization: Bearer $USVEREE_TOKEN" \
  https://usveree.ru/api/v1/agents/$AGENT_ID/settings

Response

{
  "settings": {
    "autoSend": true,
    "maxRepliesPerHour": 40,
    "replyDelaySeconds": 30,
    "scheduleEnabled": false,
    "scheduleMode": "SILENT",
    "scheduleDays": [1, 2, 3, 4, 5, 6, 7],
    "scheduleStart": "09:00",
    "scheduleEnd": "21:00",
    "scheduleTz": "Europe/Moscow",
    "offHoursPolicy": "IGNORE",
    "handoverEnabled": true,
    "handoverPauseMinutes": 60,
    "ruleHideInternals": true,
    "ruleFactsOnly": true,
    "ruleAbuseBlock": true,
    "ruleBotQuestion": "DEFLECT",
    "ruleHumanHandoff": true,
    "rulePromptGuard": true,
    "ruleStopTopics": true,
    "botDisplayName": "",
    "burstWaitSeconds": 15,
    "memoryEnabled": true,
    "strikeAutoBlock": true,
    "accountGuard": true
  }
}

Update settings

PATCH /api/v1/agents/{agentId}/settings

Send only the fields you change. An out-of-range value is rejected with an error rather than silently adjusted.

Permission: manage

Request body (JSON)

Request

curl -s -X PATCH -H "Authorization: Bearer $USVEREE_TOKEN" -H "Content-Type: application/json" \
  -d '{"autoSend":false,"replyDelaySeconds":20}' \
  https://usveree.ru/api/v1/agents/$AGENT_ID/settings

Response

{ "settings": { "autoSend": false, "replyDelaySeconds": 20, "…": "…" } }

Possible errors: UNKNOWN_FIELD, INVALID_FIELD