curl --request POST \
--url https://api.orbit.devotel.io/api/v1/agents/{id}/chat \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "Summarize my last three conversations and pick a follow-up.",
"history": [
{
"role": "user",
"content": "What were the last three calls about?"
},
{
"role": "assistant",
"content": "The calls covered billing, shipping, and refunds."
}
],
"conversationId": "conv_9d4e2f1a"
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/agents/{id}/chat"
payload = {
"message": "Summarize my last three conversations and pick a follow-up.",
"history": [
{
"role": "user",
"content": "What were the last three calls about?"
},
{
"role": "assistant",
"content": "The calls covered billing, shipping, and refunds."
}
],
"conversationId": "conv_9d4e2f1a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
message: 'Summarize my last three conversations and pick a follow-up.',
history: [
{role: 'user', content: 'What were the last three calls about?'},
{
role: 'assistant',
content: 'The calls covered billing, shipping, and refunds.'
}
],
conversationId: 'conv_9d4e2f1a'
})
};
fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/chat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/agents/{id}/chat",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'message' => 'Summarize my last three conversations and pick a follow-up.',
'history' => [
[
'role' => 'user',
'content' => 'What were the last three calls about?'
],
[
'role' => 'assistant',
'content' => 'The calls covered billing, shipping, and refunds.'
]
],
'conversationId' => 'conv_9d4e2f1a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/agents/{id}/chat"
payload := strings.NewReader("{\n \"message\": \"Summarize my last three conversations and pick a follow-up.\",\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"What were the last three calls about?\"\n },\n {\n \"role\": \"assistant\",\n \"content\": \"The calls covered billing, shipping, and refunds.\"\n }\n ],\n \"conversationId\": \"conv_9d4e2f1a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/agents/{id}/chat")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"Summarize my last three conversations and pick a follow-up.\",\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"What were the last three calls about?\"\n },\n {\n \"role\": \"assistant\",\n \"content\": \"The calls covered billing, shipping, and refunds.\"\n }\n ],\n \"conversationId\": \"conv_9d4e2f1a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/agents/{id}/chat")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"message\": \"Summarize my last three conversations and pick a follow-up.\",\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"What were the last three calls about?\"\n },\n {\n \"role\": \"assistant\",\n \"content\": \"The calls covered billing, shipping, and refunds.\"\n }\n ],\n \"conversationId\": \"conv_9d4e2f1a\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"response": "<string>",
"conversation_id": "<string>",
"tokens_used": 123
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "<string>",
"status": 429,
"retry_after": 2
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Send a chat message to an agent
Proxy a chat message to the agent runtime, returning the full response in a single 200 reply. The runtime returns { data: { response, conversation_id, tokens_used }, meta }. Use POST /chat/stream for incremental token streaming.
curl --request POST \
--url https://api.orbit.devotel.io/api/v1/agents/{id}/chat \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "Summarize my last three conversations and pick a follow-up.",
"history": [
{
"role": "user",
"content": "What were the last three calls about?"
},
{
"role": "assistant",
"content": "The calls covered billing, shipping, and refunds."
}
],
"conversationId": "conv_9d4e2f1a"
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/agents/{id}/chat"
payload = {
"message": "Summarize my last three conversations and pick a follow-up.",
"history": [
{
"role": "user",
"content": "What were the last three calls about?"
},
{
"role": "assistant",
"content": "The calls covered billing, shipping, and refunds."
}
],
"conversationId": "conv_9d4e2f1a"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
message: 'Summarize my last three conversations and pick a follow-up.',
history: [
{role: 'user', content: 'What were the last three calls about?'},
{
role: 'assistant',
content: 'The calls covered billing, shipping, and refunds.'
}
],
conversationId: 'conv_9d4e2f1a'
})
};
fetch('https://api.orbit.devotel.io/api/v1/agents/{id}/chat', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/agents/{id}/chat",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'message' => 'Summarize my last three conversations and pick a follow-up.',
'history' => [
[
'role' => 'user',
'content' => 'What were the last three calls about?'
],
[
'role' => 'assistant',
'content' => 'The calls covered billing, shipping, and refunds.'
]
],
'conversationId' => 'conv_9d4e2f1a'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/agents/{id}/chat"
payload := strings.NewReader("{\n \"message\": \"Summarize my last three conversations and pick a follow-up.\",\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"What were the last three calls about?\"\n },\n {\n \"role\": \"assistant\",\n \"content\": \"The calls covered billing, shipping, and refunds.\"\n }\n ],\n \"conversationId\": \"conv_9d4e2f1a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/agents/{id}/chat")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"Summarize my last three conversations and pick a follow-up.\",\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"What were the last three calls about?\"\n },\n {\n \"role\": \"assistant\",\n \"content\": \"The calls covered billing, shipping, and refunds.\"\n }\n ],\n \"conversationId\": \"conv_9d4e2f1a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/agents/{id}/chat")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"message\": \"Summarize my last three conversations and pick a follow-up.\",\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"What were the last three calls about?\"\n },\n {\n \"role\": \"assistant\",\n \"content\": \"The calls covered billing, shipping, and refunds.\"\n }\n ],\n \"conversationId\": \"conv_9d4e2f1a\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"response": "<string>",
"conversation_id": "<string>",
"tokens_used": 123
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "<string>",
"status": 429,
"retry_after": 2
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Authorizations
Dashboard JWT token from Clerk
Headers
Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.
1 - 255Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
true, false Path Parameters
Agent identifier (Devotel agent_xxx id). Path also accepts the alias :agentId for back-compat.
Body
User message to send to the agent.
1Optional conversation history to seed the agent (additive on top of any persisted state).
Show child attributes
Show child attributes
Existing conversation id to append onto. When omitted, a new conversation is created.