curl --request POST \
--url https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "<string>",
"context_id": "<string>",
"timeout_ms": 57500,
"idempotency_key": "<string>",
"metadata": {},
"attachments": [
{
"file_id": "<string>",
"filename": "<string>",
"content_type": "<string>"
}
]
}
'import requests
url = "https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke"
payload = {
"message": "<string>",
"context_id": "<string>",
"timeout_ms": 57500,
"idempotency_key": "<string>",
"metadata": {},
"attachments": [
{
"file_id": "<string>",
"filename": "<string>",
"content_type": "<string>"
}
]
}
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: '<string>',
context_id: '<string>',
timeout_ms: 57500,
idempotency_key: '<string>',
metadata: {},
attachments: [{file_id: '<string>', filename: '<string>', content_type: '<string>'}]
})
};
fetch('https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke', 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://openapi.beeos.ai/api/v1/agents/{agentId}/invoke",
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' => '<string>',
'context_id' => '<string>',
'timeout_ms' => 57500,
'idempotency_key' => '<string>',
'metadata' => [
],
'attachments' => [
[
'file_id' => '<string>',
'filename' => '<string>',
'content_type' => '<string>'
]
]
]),
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://openapi.beeos.ai/api/v1/agents/{agentId}/invoke"
payload := strings.NewReader("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"timeout_ms\": 57500,\n \"idempotency_key\": \"<string>\",\n \"metadata\": {},\n \"attachments\": [\n {\n \"file_id\": \"<string>\",\n \"filename\": \"<string>\",\n \"content_type\": \"<string>\"\n }\n ]\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://openapi.beeos.ai/api/v1/agents/{agentId}/invoke")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"timeout_ms\": 57500,\n \"idempotency_key\": \"<string>\",\n \"metadata\": {},\n \"attachments\": [\n {\n \"file_id\": \"<string>\",\n \"filename\": \"<string>\",\n \"content_type\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke")
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\": \"<string>\",\n \"context_id\": \"<string>\",\n \"timeout_ms\": 57500,\n \"idempotency_key\": \"<string>\",\n \"metadata\": {},\n \"attachments\": [\n {\n \"file_id\": \"<string>\",\n \"filename\": \"<string>\",\n \"content_type\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"text": "BeeOS ships unified task core in 1.0.x. The release adds A2A v1.0 compatibility, slim A2A task schema, and chatinvoke as the canonical primitive.",
"context_id": "ch-uuid",
"is_error": false
}
}Send a message to an agent and receive a reply (sync / SSE).
Sends a chat_message to the specified agent via Message Service
channel-primitives and blocks until the agent replies (or times out).
For streaming responses, set Accept: text/event-stream — the
response body will be Server-Sent Events with delta and done
event types. For async fire-and-forget invocations, use the tasks
API instead.
Browser agents use durable A2A admission backed by Message Service,
not a single-shot conversation channel. They require the current
browser owner and a stable Idempotency-Key header or idempotency_key
body field. See BrowserInvokeRequest and BrowserTaskEnvelope.
Browser SSE emits task_accepted, message, done/error; a pause ends
the subscription with is_terminal=false. Disconnect never cancels
execution. See BrowserEventStream. Unsupported attachments/metadata
are rejected for browser tasks rather than silently discarded.
curl --request POST \
--url https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "<string>",
"context_id": "<string>",
"timeout_ms": 57500,
"idempotency_key": "<string>",
"metadata": {},
"attachments": [
{
"file_id": "<string>",
"filename": "<string>",
"content_type": "<string>"
}
]
}
'import requests
url = "https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke"
payload = {
"message": "<string>",
"context_id": "<string>",
"timeout_ms": 57500,
"idempotency_key": "<string>",
"metadata": {},
"attachments": [
{
"file_id": "<string>",
"filename": "<string>",
"content_type": "<string>"
}
]
}
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: '<string>',
context_id: '<string>',
timeout_ms: 57500,
idempotency_key: '<string>',
metadata: {},
attachments: [{file_id: '<string>', filename: '<string>', content_type: '<string>'}]
})
};
fetch('https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke', 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://openapi.beeos.ai/api/v1/agents/{agentId}/invoke",
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' => '<string>',
'context_id' => '<string>',
'timeout_ms' => 57500,
'idempotency_key' => '<string>',
'metadata' => [
],
'attachments' => [
[
'file_id' => '<string>',
'filename' => '<string>',
'content_type' => '<string>'
]
]
]),
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://openapi.beeos.ai/api/v1/agents/{agentId}/invoke"
payload := strings.NewReader("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"timeout_ms\": 57500,\n \"idempotency_key\": \"<string>\",\n \"metadata\": {},\n \"attachments\": [\n {\n \"file_id\": \"<string>\",\n \"filename\": \"<string>\",\n \"content_type\": \"<string>\"\n }\n ]\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://openapi.beeos.ai/api/v1/agents/{agentId}/invoke")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"timeout_ms\": 57500,\n \"idempotency_key\": \"<string>\",\n \"metadata\": {},\n \"attachments\": [\n {\n \"file_id\": \"<string>\",\n \"filename\": \"<string>\",\n \"content_type\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://openapi.beeos.ai/api/v1/agents/{agentId}/invoke")
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\": \"<string>\",\n \"context_id\": \"<string>\",\n \"timeout_ms\": 57500,\n \"idempotency_key\": \"<string>\",\n \"metadata\": {},\n \"attachments\": [\n {\n \"file_id\": \"<string>\",\n \"filename\": \"<string>\",\n \"content_type\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"text": "BeeOS ships unified task core in 1.0.x. The release adds A2A v1.0 compatibility, slim A2A task schema, and chatinvoke as the canonical primitive.",
"context_id": "ch-uuid",
"is_error": false
}
}Authorizations
Pass a user JWT or a oag_ User API Key on the
Authorization: Bearer <token> header. Both are validated by
openapi-gateway against the Auth service.
Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.
Removed in v1.1.0: the legacy
agents:*/tasks:*/files:*/instances:*scope set has been dropped together with the403 insufficient_scopeerror. Existingoag_keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passedscopestocreateAPIKeyshould drop the argument. See the changelog at the bottom of this spec for the full migration note.
Headers
Browser tasks require this header or the idempotency_key body field. If both are present they must agree. Reuse identical input and key after ambiguous failures; never retry with a replacement key. Does not apply to continuing an existing browser task.
1 - 128^[!-~]+$Path Parameters
128Body
- Option 1
- Option 2
The message to send to the agent.
Optional conversation context ID for multi-turn conversations.
Per-request timeout in milliseconds. Default 120000 (2 minutes).
Hard-capped at 115000 server-side so the response always has
time to flush before the HTTP WriteTimeout (120s) fires.
Values above 115000 are silently clamped; if the agent does not
reply within the effective window the server returns
service_timeout (HTTP 504) — see
docs/reference/errors.md.
0 <= x <= 115000Optional caller-generated idempotency key forwarded to Message
Service as the chat_message's idempotency_key. Retries that race
the same key dedup at MS (UNIQUE index on channel_messages).
When omitted, the gateway generates a fresh UUID. The same key
also doubles as the message_id an agent must echo back as
in_reply_to on its reply.
Opaque caller-controlled key/value pairs merged into the channel
metadata (e.g. trace_id, user_id, business tags). Reserved
routing keys (protocol, caller_owner_id, target_agent_id,
delivery_principal) are silently scrubbed server-side and
cannot be overridden by the caller.
Show child attributes
Show child attributes
Optional list of files previously uploaded via
POST /api/v1/files/presign-upload.
Each file_id is resolved server-side to a presigned download
URL and embedded in the chat_message envelope so the receiving
agent can fetch the bytes without further BeeOS auth.
16Show child attributes
Show child attributes