A profile (name, handle, instructions, model, avatar) plus allowed connectors and skills. A chat with an agent runs under that profile and reaches only the agent's connectors and the connected accounts switched on for it.

How do I talk to a specific agent over the API?

Put its handle in the model field of POST /v1/chat/completions. GET /v1/models lists the handles your key can reach; the built-in assistant is samreshu.

Where do I create and configure agents?

In the app, under Agents. Instructions, model, connectors, skills and account access are set there; the API addresses the result.

Can I pick the LLM per request?

No. The model is part of the agent: change it in the agent's settings, and every door (the app, messengers, tasks, the API) runs the same model.

Agents

Every answer comes from an agent: a profile with its own instructions, model, connectors and skills. Over the API you choose the agent, not the LLM: its handle goes in the model field of POST /v1/chat/completions.

What is an agent

An agent is a profile (name, handle, instructions, model, avatar) plus allowed connectors and skills. Every organization has the built-in assistant, samreshu, and any member can create their own agents in the app under Agents. The handle is the address people use in the app (@mp-manager) and the model you send over the API.

An agent is personal (only its owner sees and talks to it) or shared with the organization (every member can talk to it). Either way only the owner changes its settings.

Address an agent

GET /v1/models lists the agents the key can reach, the built-in assistant first. id is the handle, owned_by is system for the built-in assistant and the organization id for the organization's agents.

curl https://samreshuuu.ru/v1/models \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"

{ "object": "list", "data": [ { "id": "samreshu", "object": "model", "created": 1719187200, "owned_by": "system" }, { "id": "mp-manager", "object": "model", "created": 1777456800, "owned_by": "5b2e9d7a-1c4f-4e8b-a6d3-7f0c2b9e4a18" } ] }

Send the handle as model; a leading @ is accepted. The answer carries the same handle in model. The request below names mp-manager: substitute an id from your own GET /v1/models.

curl https://samreshuuu.ru/v1/chat/completions \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "mp-manager", "messages": [{ "role": "user", "content": "Which SKUs dropped the most in sales this week?" }] }'

The key acts as the member who created it, so it reaches the agents that member can reach: the built-in assistant, their own agents and the organization's shared ones. A handle outside that set, one that does not exist or a disabled agent answers 404 DATA_NOT_FOUND with param: "model", the same answer for all three: knowing a handle grants no access. Keep session_id per agent: a conversation belongs to the agent it started with (and to the key's organization), and naming it with another model answers 409 DATA_CONFLICT with param: "session_id".

Model, connectors and accounts

The agent's settings decide how it answers:

Model. The LLM is set on the agent, and every door (the app, messengers, tasks, the API) runs the same one. A request cannot override it.
Connectors. The agent calls only the connectors it is allowed. What it may call decides which tools it has.
Accounts. The agent reaches the connected accounts of the person it runs for, minus the ones switched off for it. For an API call that person is the key's creator.

Organization-shared agent

Sharing an agent publishes a fixed revision of its instructions, skills, required connections and model; teammates run the published revision, not the owner's draft. A teammate accepts the revision in the app before their first chat, choosing which of their own connections the agent gets. Until they do, a turn under that agent is refused with AGENT_REVISION_NOT_ACCEPTED. The owner's connections never reach teammates, and each teammate pays for their own requests.

Available tools

Every tool the agent can call inside a turn. The set is fixed and applies to all agents, while the instructions, model, skills, connectors and accounts differ per agent. Tool names are the ones the opt-in tool events carry in tool_name.

Errors

The error body is the public error object {"type": "error", "error": {"type", "code", "message", "param"}, "request_id"}; branch on error.type and error.code. See Errors & Rate Limits and Authentication.

HTTP	Code	When
403	`AUTH_PERMISSION_DENIED`	The key lacks `chat:write`
404	`DATA_NOT_FOUND`	`model` names no agent the key can reach (`param: "model"`)
409	`DATA_CONFLICT`	`session_id` belongs to another agent or to another key's conversation (`param: "session_id"`)
	`AGENT_REVISION_NOT_ACCEPTED`	A shared agent whose current revision the key's creator has not accepted