Submit an async task to an agent.
curl --request POST \
--url https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "<string>",
"context_id": "<string>",
"deadline_ms": 302400000,
"idempotency_key": "<string>",
"metadata": {},
"attachments": [
{
"file_id": "<string>",
"filename": "<string>",
"content_type": "<string>"
}
]
}
'import requests
url = "https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks"
payload = {
"message": "<string>",
"context_id": "<string>",
"deadline_ms": 302400000,
"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>',
deadline_ms: 302400000,
idempotency_key: '<string>',
metadata: {},
attachments: [{file_id: '<string>', filename: '<string>', content_type: '<string>'}]
})
};
fetch('https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks', 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}/tasks",
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>',
'deadline_ms' => 302400000,
'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}/tasks"
payload := strings.NewReader("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"deadline_ms\": 302400000,\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}/tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"deadline_ms\": 302400000,\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}/tasks")
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 \"deadline_ms\": 302400000,\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": {
"task_kind": "browser",
"task_id": "<string>",
"context_id": "<string>",
"agent_id": "<string>",
"status": "submitted",
"is_terminal": true,
"is_error": true,
"text": "<string>",
"cancellation_requested": true,
"artifacts": [
{
"artifactId": "<string>",
"name": "<string>",
"description": "<string>",
"parts": [
{
"text": "<string>"
}
]
}
]
}
}{
"success": true,
"data": {
"task_id": "ch-task-uuid",
"agent_id": "agent-uuid",
"status": "queued",
"created_at": "2026-05-14T18:00:00Z"
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}tasks
Submit an async task to an agent.
Creates a single-shot task channel and publishes the initial
chat_message envelope, then returns 202 with the task_id. The agent
reply lands asynchronously — callers either poll GET /tasks/{taskId}
or subscribe to the SSE event stream at GET /tasks/{taskId}/events.
The channel inherits the caller-supplied deadline_ms (capped at 7
days server-side). If the deadline elapses before the agent produces a
terminal message the task transitions to timeout.
Browser exception: task_id is independent of context_id and the
deadline is at most 300000 ms. Use BrowserCreateTaskRequest and a
stable Idempotency-Key header or idempotency_key body field.
Current instance ownership is required even for a public agent.
Returns BrowserTaskEnvelope (202 for nonterminal admission/replay,
200 for an already-terminal original task). No replacement task is
created when retrying identical input and the same key.
POST
/
api
/
v1
/
agents
/
{agentId}
/
tasks
Submit an async task to an agent.
curl --request POST \
--url https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "<string>",
"context_id": "<string>",
"deadline_ms": 302400000,
"idempotency_key": "<string>",
"metadata": {},
"attachments": [
{
"file_id": "<string>",
"filename": "<string>",
"content_type": "<string>"
}
]
}
'import requests
url = "https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks"
payload = {
"message": "<string>",
"context_id": "<string>",
"deadline_ms": 302400000,
"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>',
deadline_ms: 302400000,
idempotency_key: '<string>',
metadata: {},
attachments: [{file_id: '<string>', filename: '<string>', content_type: '<string>'}]
})
};
fetch('https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks', 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}/tasks",
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>',
'deadline_ms' => 302400000,
'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}/tasks"
payload := strings.NewReader("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"deadline_ms\": 302400000,\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}/tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"<string>\",\n \"context_id\": \"<string>\",\n \"deadline_ms\": 302400000,\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}/tasks")
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 \"deadline_ms\": 302400000,\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": {
"task_kind": "browser",
"task_id": "<string>",
"context_id": "<string>",
"agent_id": "<string>",
"status": "submitted",
"is_terminal": true,
"is_error": true,
"text": "<string>",
"cancellation_requested": true,
"artifacts": [
{
"artifactId": "<string>",
"name": "<string>",
"description": "<string>",
"parts": [
{
"text": "<string>"
}
]
}
]
}
}{
"success": true,
"data": {
"task_id": "ch-task-uuid",
"agent_id": "agent-uuid",
"status": "queued",
"created_at": "2026-05-14T18:00:00Z"
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}{
"success": false,
"error": {
"code": "agent_not_found",
"message": "<string>",
"type": "api_error",
"request_id": "<string>",
"param": "<string>",
"metadata": {}
}
}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.
Required string length:
1 - 128Pattern:
^[!-~]+$Path Parameters
Maximum string length:
128Body
application/json
- Option 1
- Option 2
Initial user prompt. Wrapped into a chat_message envelope.
Optional existing conversation/channel ID to reuse instead of creating a fresh task channel. Rare; most callers omit this.
Task deadline in milliseconds. When > 0, the channel auto-closes
with status=timeout if no terminal reply lands in this window.
Max 7 days (server-side cap).
Required range:
0 <= x <= 604800000Forwarded to MS's channel_messages UNIQUE index. Re-submitting
with the same key returns the original task_id rather than
spawning a duplicate. Recommended for retry-prone callers.
Caller-supplied correlation tags (trace_id, business labels).
Reserved chatinvoke routing keys (protocol, caller_owner_id,
target_agent_id, delivery_principal) are overwritten by
the gateway and stripped from the response.
Show child attributes
Show child attributes
Optional list of files previously uploaded via
POST /api/v1/files/presign-upload.
Resolved server-side and embedded in the initial chat_message
envelope.
Maximum array length:
16Show child attributes
Show child attributes