--- title: "Send Agent Message" method: POST path: "/agent/messages" tags: ["accepts-api-key"] --- # Send Agent Message `POST /agent/messages` ## Request - Base URL: `https://api.tellers.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.tellers.ai/agent/messages` - Auth: none declared Send a message to a chat; the backend decides how it runs. Nothing is streamed back: the run's events go to the chat's stream, which clients watch with ``subscribe_chat`` on the user websocket (or ``GET /agent/response/{chat_id}``) from ``stream_cursor``. - Idle chat (or no ``chat_id``, which creates one): a turn starts with this message (``mode: started``). - Running chat: the message is queued (``mode: queued``) and handed to the running turn with the next tool results, so it can change course mid-turn. If the turn ends before another tool call, the message opens the next turn instead, with its own settings. Its ``tellers.user_message`` events say which happened. ``DELETE /agent/response/{chat_id}`` cancels the turn and drops the messages still waiting for it. ## Headers - `x-api-key` string, nullable - `authorization` string, nullable ## Request body - AgentMessageRequest - `message` string, required: The message to send to the agent - `chat_id` string, nullable: Optional chat ID for conversation tracking - `previous_response_id` string, nullable: The ID of the previous response to the model. Use this to create multi-turn conversations. - `llm_verbosity` 'low' | 'medium' | 'high': Range of number of tokens that can be generated by the LLM, higher values yield more verbose responses. A value the chosen model does not advertise in `available_llm_models` is ignored. - `llm_reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable: Controls reasoning effort: higher values yield more precise but slower responses. A value the chosen model does not advertise in `available_llm_models` is ignored. - `priority` 'low' | 'default' | 'high' | 'ultra', nullable: Priority level for the response: 'low' (cheaper/slower), 'default' (standard), 'high' (premium/low-latency), or 'ultra' (OpenAI Ultrafast: several times faster output at about 3x the 'high' price). Only levels in the chosen model's `available_priorities` (see GET /) take effect; others fall back to 'default'. - `context` AppContext - `current_playback_time` number, nullable: The current playback time in the project when the response is sent. - `on_screen_asset` string, nullable: The id of the asset on screen when the response is sent. - `on_screen_project` string, nullable: The id of the project on screen when the response is sent. - `selected_clips` string[], nullable: The ids of the clips selected when the response is sent. - `selected_assets` string[], nullable: The ids of the assets selected when the response is sent. - `selected_projects` string[], nullable: The ids of the projects selected when the response is sent. - `llm_model` 'gpt-6-astra' | 'gpt-6.1-sol' | 'gpt-6.1-terra' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5.5-2026-04-23' | 'gpt-5.5-pro-2026-04-23' | 'gpt-5.4-pro-2026-03-05' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.3-codex' | 'gpt-5.2-2025-12-11' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano': The model to use to generate the response. - `tools` string[]: The tools to use to generate the response. Defaults to the same as GET /settings (AVAILABLE_AGENT_TOOLS if set, else all tools). - `custom_agent_id` string, nullable: The ID of the custom agent to use to generate the response. If not provided, the default custom agent will be used. - `parallel_tool_calls` boolean: Whether to allow parallel tool calls. Defaults to true. If True, the tool calls will be executed in parallel. If False, the tool calls will be executed sequentially. - `compaction` boolean: Whether to enable automatic context cleanup when the selected model supports it. This keeps long conversations manageable. - `prefer_compaction` integer, nullable: Preferred input-token size to compact the conversation at, when `compaction` is enabled and the model supports it. A preference, not a guarantee: it is capped at the chosen model's own threshold (`compaction_threshold` in `available_llm_models`), which is also what is used when this is unset, because past that point compaction is what keeps the request inside the context window. Lower it to have long conversations compacted earlier. - `override_llm_verbosity` 'low' | 'medium' | 'high', nullable: Override the verbosity of the LLM, range of number of tokens that can be generated by the LLM, higher values yield more verbose responses. - `override_llm_reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable: Override the reasoning effort of the LLM, controls reasoning effort: higher values yield more precise but slower responses. - `tool_exposure` 'search' | 'flat_search' | 'flat': How much of a tool the model is shown up front. What deferral hides depends on whether the tool is in a namespace, and the difference is the whole point of this enum. Per OpenAI's tool search guide: a deferred tool *inside a namespace* is hidden completely — the model sees only the namespace name and description — while a deferred *top-level* function still shows its name and description, so deferral there only holds back the parameter schema. Measured over the current 56 tools: ============== ============================ ========== exposure visible up front tokens ============== ============================ ========== ``search`` 11 namespace descriptions ~0.5k ``flat_search`` 56 tool names + descriptions ~10.2k ``flat`` the above plus every schema ~44.6k ============== ============================ ========== ``search`` uses namespace descriptions and hides the names inside them; ``flat_search`` exposes top-level tool names and descriptions while deferring only parameter schemas. ``flat`` removes deferral entirely. Grouping without deferring is deliberately not offered: namespaces exist to make search legible, so once every schema is up front they buy nothing and cost their own descriptions. The member value is what the API accepts on the wire. - `max_tellers_token` integer, nullable: Maximum cumulative Tellers Token budget for the agent run. - `no_interaction` boolean: Whether to disable interaction with the agent. If True, the agent will try to generate a response without interacting with the user. ## Response `200` Successful Response - AgentMessageSubmitResponse: Where a message sent to a chat went. - `chat_id` string, required - `pending_id` string, required: Id of this message in the chat's ``tellers.user_message`` events, which say when it is applied, started, or dropped. - `mode` 'started' | 'queued', required: ``started``: the chat was idle and a turn started with this message. ``queued``: a turn is running; the message is handed to it at the next tool call (``tellers.user_message`` status ``applied``), or opens the next turn when this one ends first (status ``started``). - `stream_cursor` string, required: Stream entry id to subscribe from (``subscribe_chat`` ``after`` on the user websocket, or ``last_event_id`` on ``GET /agent/response``) to see every event of this message's run without a gap. ## Other responses - `402`: The chosen `llm_model` or `priority` needs a higher subscription tier (see `subscription_locked` in GET /settings). Nothing was charged. `detail.code` is `SUBSCRIPTION_REQUIRED`. - `403`: The account's email is not verified yet, so it cannot spend tokens. Nothing was charged. `detail.code` is `EMAIL_NOT_VERIFIED`. - `422`: Validation Error - `429`: Too many messages already wait on this chat. - `503`: The chat run coordinator is unavailable. ## Changes - **2026-11-05** `fdaa0fa44a26`: 1 info - endpoint added [Operation history](https://skmtc.dev/tellers/apis/tellers-api/changes/agent/messages/post.md) --- [API](https://skmtc.dev/tellers/apis/tellers-api.md) - [All operations](https://skmtc.dev/tellers/apis/tellers-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tellers/apis/tellers-api/revisions/fdaa0fa44a26?raw)