Send message

POST https://app.sulus.ai/api/v1/agents/{agent_id}/chats/{chat_id}/messages

Send a message and get the assistant reply

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Path parameters

agent_id string Required

The agent id (UUID).

Validation: uuid (route-constrained)

Stored in ai_projects.uid

chat_id string Required

The chat id (UUID).

Validation: uuid (route-constrained)

Stored in ai_chats.uid

Request body

content string Required

Your message, max 20,000 characters.

Validation: required|string|max:20000

Stored in ai_chat_messages.content

model string Optional Nullable

Override the thread model for this turn.

Validation: sometimes|nullable|string|max:255

Stored in ai_chat_messages.model

Errors

Status	Meaning	Body
`404`	Agent not found, or you do not have access to it
`404`	Chat not found in this agent, or it was created by a different token
`422`	Validation failed	`{"message":"…","errors":{"field":["…"]}}`
`402`	Out of prepaid USD	`{"error":true,"insufficient_tokens":true,"payer_is_self":true,"message":"You are not subscribed or your USD balance is empty. Please recharge to continue chatting."}`
`422`	Generation failed — your message was rolled back so a retry re-runs cleanly	`{"error":true,"message":"The assistant could not generate a response. Please try again.","content":"<your original message>"}`
`401`	Missing or invalid bearer token
`403`	Feature ai_chat not enabled for the account

Notes

user_message never carries a usage block — only a freshly generated assistant_message does.
wallet is null when prepaid billing is not active for the account (e.g. admin-owned agents, or resellers without USD billing enabled); otherwise it reflects the balance immediately after this turn.

curl --request POST \
  --url https://app.sulus.ai/api/v1/agents/{agent_id}/chats/{chat_id}/messages \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "content": "Summarise our refund policy.",
  "model": "sulus-chat-1"
}'

import requests

url = "https://app.sulus.ai/api/v1/agents/{agent_id}/chats/{chat_id}/messages"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}
payload = {
  "content": "Summarise our refund policy.",
  "model": "sulus-chat-1"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://app.sulus.ai/api/v1/agents/{agent_id}/chats/{chat_id}/messages"
	payload := strings.NewReader(`{
  "content": "Summarise our refund policy.",
  "model": "sulus-chat-1"
}`)
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	req.Header.Add("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Response 201

{
    "object": "message",
    "data": {
        "user_message": {
            "id": 9001,
            "object": "message",
            "role": "user",
            "content": "Summarise our refund policy.",
            "model": null,
            "created_at": "2026-07-30T14:19:58.000000Z"
        },
        "assistant_message": {
            "id": 9002,
            "object": "message",
            "role": "assistant",
            "content": "Refunds are available within 30 days of purchase, provided the item is unused.",
            "model": "sulus-chat-1",
            "created_at": "2026-07-30T14:20:11.000000Z",
            "usage": {
                "prompt_tokens": 210,
                "completion_tokens": 88,
                "total_tokens": 298
            }
        }
    },
    "model": "sulus-chat-1",
    "tools_used": [],
    "wallet": {
        "usd_cost": 0.0149,
        "balance_tokens": 1249702,
        "balance_usd": 6.2485,
        "payer_user_id": 501
    }
}

{
    "object": "message",
    "data": {
        "user_message": {
            "id": 9001,
            "object": "message",
            "role": "user",
            "content": "Summarise our refund policy.",
            "model": null,
            "created_at": "2026-07-30T14:19:58.000000Z"
        },
        "assistant_message": {
            "id": 9002,
            "object": "message",
            "role": "assistant",
            "content": "Refunds are available within 30 days of purchase, provided the item is unused.",
            "model": "sulus-chat-1",
            "created_at": "2026-07-30T14:20:11.000000Z",
            "usage": {
                "prompt_tokens": 210,
                "completion_tokens": 88,
                "total_tokens": 298
            }
        }
    },
    "model": "sulus-chat-1",
    "tools_used": [],
    "wallet": {
        "usd_cost": 0.0149,
        "balance_tokens": 1249702,
        "balance_usd": 6.2485,
        "payer_user_id": 501
    }
}