Send a message through the API

Call an AI agent from your server, continue a conversation and handle API errors.

Open copy menu

The message API lets your application send a question to an Aihio AI agent and receive a JSON response. It does not require an embedded chat window.

Before you start

You need a published agent’s ID and an API key from the same workspace. Check API-key availability in your subscription and create a key in the integration settings in Oma Aihio.

Send your first message

Set AIHIO_API_KEY and AIHIO_AGENT_ID in your server environment. The first contains the secret API key; the second is the agent’s UUID. Run this command on your server or in a secure local terminal:

curl --fail-with-body https://app.aihio.ai/api/v1/messages \
  -H "x-api-key: ${AIHIO_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data "{\"chatbot_id\":\"${AIHIO_AGENT_ID}\",\"message\":\"Where can I find help using the service?\"}"

A successful response includes a conversation_id and a message. This call consumes service usage; it is not a free connectivity check. Do not repeatedly send the same message just to test connectivity.

Request fields

The endpoint is POST /api/v1/messages. Authenticate with the x-api-key header, not a Bearer token.

Request fields
Field	Required	Content
`chatbot_id`	Yes	UUID of an agent belonging to the API key’s workspace.
`message`	Yes	Message text, 1–10,000 characters.
`conversation_id`	No	Conversation ID returned by the previous response.
`external_user_id`	No	Your user ID, at most 255 characters. It does not prove identity on its own.
`metadata`	No	JSON object containing additional data. Do not include secrets or unnecessary personal data.

Continue a conversation

Keep the first response’s conversation_id in your application’s user-specific state and include it with the next message. Never share it between users or trust an ID supplied by another user.

{
  "chatbot_id": "00000000-0000-4000-8000-000000000001",
  "message": "Could you explain your previous answer?",
  "conversation_id": "ID_FROM_PREVIOUS_RESPONSE"
}

Replace the example UUID with your agent ID and conversation_id with the actual response value. Omit the conversation ID to start a new conversation.

Read the response

Read the response
Field	Use
`conversation_id`	Associate the next message with the same conversation.
`message`	The agent’s response text.
`sources`	Associated source information, when available.
`follow_ups`	Suggested follow-up questions, when available.
`tokens`	Token usage information returned with the response.
`timing`	Optional processing timing information.

The endpoint returns a complete JSON response, not a progressively streamed response. Provide waiting and error states in your application. Do not assume every response includes sources or follow-up questions.

Recover from errors

Recover from errors
HTTP status	Check
`400`	JSON shape, field names and message length.
`401`	API key, header name and whether the key is still valid.
`402`	Usage and available balance.
`403`	Model access or the agent’s identity requirements.
`404`	Agent ID and membership in the API key’s workspace.
`422`	A safety restriction blocked the request; do not automatically vary requests to bypass it.
`429`	Request frequency; slow down and observe the response’s rate-limit headers.
`500`	Service error; provide recovery guidance and retain the request ID for support.

A timeout does not prove that a message was not processed. This request has no idempotency key: blindly resending can produce another answer and additional usage. Error bodies can differ, including identity failures, so also handle the HTTP status.

The precise machine-readable description is the Aihio OpenAPI document . This guide covers messaging, not an API for managing agents or knowledge sources.