aethexDocs
Dashboard

API Reference

Chat with Agent

Send a text message to an agent and get its reply, a voice call without the audio.

Base URL
https://api.aethexai.com/api/v1
Endpoints
1
Scopes
agents:write
YOUR APPserver or clientAETHEXyour agentPOST /agents/:id/chatmessagereply · conversation_id · usagePass the returned conversation_id on the next request to continue the session.
POST/agents/:id/chat

Send a text message to an agent and get its reply, a voice call without the audio.

Chat with Agent

Runs one text turn against the agent. The agent's own configuration (role, language, guardrails, knowledge base, and dynamic variables) shapes the reply, just like a voice call without the audio. You send only a single message; the system prompt and conversation history stay server-side, so there is no way to inject a system role. Pass conversation_id to continue a session (the id is returned so you can reuse it); omit it to start a new one. Set stream: true for a Server-Sent-Events stream of the reply. Usage is billed per token.

Path & Query

1
  • idstringrequired

    UUID of the agent to chat with.

Request body

4
  • messagestringrequired

    The user's message: 1 to 8000 characters and at most 8000 bytes when UTF-8 encoded, so an emoji- or CJK-heavy message can hit the limit well below 8000 characters. Control characters other than tab, newline, and carriage return are rejected.

  • conversation_idstringoptional

    Continue an existing chat session by id; omit to start a new one.

  • streambooleanoptional

    When true, the reply streams as text/event-stream Server-Sent Events instead of a single JSON body. The status is committed to 200 as soon as the stream opens, so a provider failure or an empty completion arrives as a terminal SSE error event rather than an error status. Handle that event shape, not just the HTTP code. The terminal done event carries persisted. When it is false the reply reached you but its turns could not be saved: that turn is not billed, and it is absent from the conversation history the next turn replays. Treat the conversation_id as usable but that exchange as lost, or start a new session.

  • dynamic_variablesobjectoptional

    Per-request {{variable}} overrides merged over the agent's stored defaults.

Errors

8
401Unauthorized

Missing or invalid API key.

Add X-API-Key: YOUR_KEY to your request headers.

403Forbidden

Chat runs a billed generation and appends to the conversation, so it requires the write scope: a key with only agents:read is rejected. Continuing an existing session additionally requires conversations:read, because its stored history is replayed to the model.

Issue a key with the agents:write scope, plus conversations:read if you pass conversation_id.

404Not Found

No such agent under this tenant, or the conversation_id does not exist, belongs to a different agent, or was opened on a different channel (a voice call's transcript cannot be resumed over text). All of these return the same 404 on purpose, so probing cannot distinguish "exists but not yours" from "does not exist".

Check the agent id, and omit conversation_id to start a fresh session if the id came from another agent or channel.

402Payment Required

The tenant's billing is hard-blocked (out of credits).

Add credits or resolve the billing issue, then retry.

409Conflict

The agent is still provisioning or failed to provision, so it has no usable configuration to shape a reply yet.

Wait for the agent to finish provisioning (poll GET /agents/{id} until its status is ready), then retry.

422Unprocessable Entity

The message is blank, exceeds 8000 characters or 8000 UTF-8 bytes, contains control characters, the agent's prompt references a dynamic variable with no value, or the assembled prompt exceeds the model context window.

Shorten the message, supply the missing dynamic_variables, or lower the agent's max_tokens.

429Too Many Requests

Too many requests are in flight, so the service is momentarily at capacity and throttled this one.

Retry after the delay in the Retry-After response header, with exponential backoff.

503Service Unavailable

The model is temporarily unavailable (provider down or circuit breaker open).

Retry after a short delay.