curl --request POST \
--url 'http://localhost:8000/conversations' \
--header "Authorization: Bearer $STATESET_AGENTS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"context": {
"goal": "Plan a 4-day trip to Kyoto",
"plan_goal": "Plan a 4-day trip to Osaka",
"plan_update": {
"action": "advance"
}
},
"conversation_id": "demo-trip",
"max_tokens": 256,
"messages": [
{
"content": "You are a helpful assistant.",
"role": "system"
},
{
"content": "Hello! How can you help me?",
"role": "user"
}
],
"stream": false,
"temperature": 0.7
}'
{
"response": "string",
"conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tokens_used": 1,
"processing_time": 1.5,
"metadata": {}
}
Chat with Agent
Send a message to an agent and get a response.
POST
/
conversations
curl --request POST \
--url 'http://localhost:8000/conversations' \
--header "Authorization: Bearer $STATESET_AGENTS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"context": {
"goal": "Plan a 4-day trip to Kyoto",
"plan_goal": "Plan a 4-day trip to Osaka",
"plan_update": {
"action": "advance"
}
},
"conversation_id": "demo-trip",
"max_tokens": 256,
"messages": [
{
"content": "You are a helpful assistant.",
"role": "system"
},
{
"content": "Hello! How can you help me?",
"role": "user"
}
],
"stream": false,
"temperature": 0.7
}'
{
"response": "string",
"conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tokens_used": 1,
"processing_time": 1.5,
"metadata": {}
}
Send a message to an agent and get a response.
Request body
ConversationRequest
object[]
required
List of conversation messages (append-only when conversation_id is set)
string,null
Conversation identifier
string,null
User identifier
integer
Maximum tokens in response
number
Response temperature
boolean
Whether to stream the response
object,null
Additional context
Response
ConversationResponse
string
required
Agent’s response
string
required
Conversation identifier
integer
required
Number of tokens used
number
required
Processing time in seconds
object
Additional metadata
Status codes
| Code | Meaning |
|---|---|
200 | Successful response |
400 | Invalid input |
401 | Authentication required |
404 | Agent not found |
422 | Validation Error |
429 | Rate limit exceeded |
500 | Internal server error |
curl --request POST \
--url 'http://localhost:8000/conversations' \
--header "Authorization: Bearer $STATESET_AGENTS_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"context": {
"goal": "Plan a 4-day trip to Kyoto",
"plan_goal": "Plan a 4-day trip to Osaka",
"plan_update": {
"action": "advance"
}
},
"conversation_id": "demo-trip",
"max_tokens": 256,
"messages": [
{
"content": "You are a helpful assistant.",
"role": "system"
},
{
"content": "Hello! How can you help me?",
"role": "user"
}
],
"stream": false,
"temperature": 0.7
}'
{
"response": "string",
"conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"tokens_used": 1,
"processing_time": 1.5,
"metadata": {}
}
Last modified on August 31, 2026