TEtellers
accepts-api-key

Send Agent Message

Changed on

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.

post/agent/messages

Request

  • Base URL
    https://api.tellers.ai (the document declares no server; this is the origin it was published from)
  • Auth
    none declared

Headers

x-api-keystring nullable
authorizationstring nullable

Request body

messagestring required

The message to send to the agent

chat_idstring nullable

Optional chat ID for conversation tracking

previous_response_idstring 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'.

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.

toolsstring[]

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_idstring 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_callsboolean

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.

compactionboolean

Whether to enable automatic context cleanup when the selected model supports it. This keeps long conversations manageable.

prefer_compactioninteger 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_tokeninteger nullable

Maximum cumulative Tellers Token budget for the agent run.

no_interactionboolean

Whether to disable interaction with the agent. If True, the agent will try to generate a response without interacting with the user.

Response

Successful Response

chat_idstring required
pending_idstring 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_cursorstring 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.

Changes