Append user/system events to a session
curl --request POST \
--url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"actor": "human:api",
"events": [
{
"actor": "human:api",
"content": [
{
"byte_size": 1,
"content": [],
"context": "example",
"data": "example",
"encrypted_content": "example",
"height": 1,
"id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"input": {
"key": "example"
},
"is_error": true,
"media_type": "example",
"name": "example-name",
"omitted_bytes": 1,
"payload": "example",
"provider": "example",
"provider_payload": "example",
"redacted": true,
"semantic_hint": "example",
"sha256": "example",
"signature": "example",
"source": {
"file_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "file"
},
"summary": [],
"text": "example",
"title": "example",
"tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "example",
"uri": "example",
"url": "https://example.com",
"url_expires_at": "2026-02-18T09:30:00.000Z",
"width": 1
}
],
"handoff_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"note": "example",
"text": "example",
"type": "user.message"
}
],
"message": "example",
"referenced_session_ids": [
"example"
]
}
'import requests
url = "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"
payload = {
"actor": "human:api",
"events": [
{
"actor": "human:api",
"content": [
{
"byte_size": 1,
"content": [],
"context": "example",
"data": "example",
"encrypted_content": "example",
"height": 1,
"id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"input": { "key": "example" },
"is_error": True,
"media_type": "example",
"name": "example-name",
"omitted_bytes": 1,
"payload": "example",
"provider": "example",
"provider_payload": "example",
"redacted": True,
"semantic_hint": "example",
"sha256": "example",
"signature": "example",
"source": {
"file_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "file"
},
"summary": [],
"text": "example",
"title": "example",
"tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "example",
"uri": "example",
"url": "https://example.com",
"url_expires_at": "2026-02-18T09:30:00.000Z",
"width": 1
}
],
"handoff_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"note": "example",
"text": "example",
"type": "user.message"
}
],
"message": "example",
"referenced_session_ids": ["example"]
}
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({
actor: 'human:api',
events: [
{
actor: 'human:api',
content: [
{
byte_size: 1,
content: [],
context: 'example',
data: 'example',
encrypted_content: 'example',
height: 1,
id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
input: {key: 'example'},
is_error: true,
media_type: 'example',
name: 'example-name',
omitted_bytes: 1,
payload: 'example',
provider: 'example',
provider_payload: 'example',
redacted: true,
semantic_hint: 'example',
sha256: 'example',
signature: 'example',
source: {file_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d', type: 'file'},
summary: [],
text: 'example',
title: 'example',
tool_use_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
type: 'example',
uri: 'example',
url: 'https://example.com',
url_expires_at: '2026-02-18T09:30:00.000Z',
width: 1
}
],
handoff_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
note: 'example',
text: 'example',
type: 'user.message'
}
],
message: 'example',
referenced_session_ids: ['example']
})
};
fetch('https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events', 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.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events",
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([
'actor' => 'human:api',
'events' => [
[
'actor' => 'human:api',
'content' => [
[
'byte_size' => 1,
'content' => [
],
'context' => 'example',
'data' => 'example',
'encrypted_content' => 'example',
'height' => 1,
'id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'input' => [
'key' => 'example'
],
'is_error' => true,
'media_type' => 'example',
'name' => 'example-name',
'omitted_bytes' => 1,
'payload' => 'example',
'provider' => 'example',
'provider_payload' => 'example',
'redacted' => true,
'semantic_hint' => 'example',
'sha256' => 'example',
'signature' => 'example',
'source' => [
'file_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'type' => 'file'
],
'summary' => [
],
'text' => 'example',
'title' => 'example',
'tool_use_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'type' => 'example',
'uri' => 'example',
'url' => 'https://example.com',
'url_expires_at' => '2026-02-18T09:30:00.000Z',
'width' => 1
]
],
'handoff_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'note' => 'example',
'text' => 'example',
'type' => 'user.message'
]
],
'message' => 'example',
'referenced_session_ids' => [
'example'
]
]),
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.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"
payload := strings.NewReader("{\n \"actor\": \"human:api\",\n \"events\": [\n {\n \"actor\": \"human:api\",\n \"content\": [\n {\n \"byte_size\": 1,\n \"content\": [],\n \"context\": \"example\",\n \"data\": \"example\",\n \"encrypted_content\": \"example\",\n \"height\": 1,\n \"id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"input\": {\n \"key\": \"example\"\n },\n \"is_error\": true,\n \"media_type\": \"example\",\n \"name\": \"example-name\",\n \"omitted_bytes\": 1,\n \"payload\": \"example\",\n \"provider\": \"example\",\n \"provider_payload\": \"example\",\n \"redacted\": true,\n \"semantic_hint\": \"example\",\n \"sha256\": \"example\",\n \"signature\": \"example\",\n \"source\": {\n \"file_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"file\"\n },\n \"summary\": [],\n \"text\": \"example\",\n \"title\": \"example\",\n \"tool_use_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"example\",\n \"uri\": \"example\",\n \"url\": \"https://example.com\",\n \"url_expires_at\": \"2026-02-18T09:30:00.000Z\",\n \"width\": 1\n }\n ],\n \"handoff_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"note\": \"example\",\n \"text\": \"example\",\n \"type\": \"user.message\"\n }\n ],\n \"message\": \"example\",\n \"referenced_session_ids\": [\n \"example\"\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://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"actor\": \"human:api\",\n \"events\": [\n {\n \"actor\": \"human:api\",\n \"content\": [\n {\n \"byte_size\": 1,\n \"content\": [],\n \"context\": \"example\",\n \"data\": \"example\",\n \"encrypted_content\": \"example\",\n \"height\": 1,\n \"id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"input\": {\n \"key\": \"example\"\n },\n \"is_error\": true,\n \"media_type\": \"example\",\n \"name\": \"example-name\",\n \"omitted_bytes\": 1,\n \"payload\": \"example\",\n \"provider\": \"example\",\n \"provider_payload\": \"example\",\n \"redacted\": true,\n \"semantic_hint\": \"example\",\n \"sha256\": \"example\",\n \"signature\": \"example\",\n \"source\": {\n \"file_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"file\"\n },\n \"summary\": [],\n \"text\": \"example\",\n \"title\": \"example\",\n \"tool_use_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"example\",\n \"uri\": \"example\",\n \"url\": \"https://example.com\",\n \"url_expires_at\": \"2026-02-18T09:30:00.000Z\",\n \"width\": 1\n }\n ],\n \"handoff_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"note\": \"example\",\n \"text\": \"example\",\n \"type\": \"user.message\"\n }\n ],\n \"message\": \"example\",\n \"referenced_session_ids\": [\n \"example\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events")
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 \"actor\": \"human:api\",\n \"events\": [\n {\n \"actor\": \"human:api\",\n \"content\": [\n {\n \"byte_size\": 1,\n \"content\": [],\n \"context\": \"example\",\n \"data\": \"example\",\n \"encrypted_content\": \"example\",\n \"height\": 1,\n \"id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"input\": {\n \"key\": \"example\"\n },\n \"is_error\": true,\n \"media_type\": \"example\",\n \"name\": \"example-name\",\n \"omitted_bytes\": 1,\n \"payload\": \"example\",\n \"provider\": \"example\",\n \"provider_payload\": \"example\",\n \"redacted\": true,\n \"semantic_hint\": \"example\",\n \"sha256\": \"example\",\n \"signature\": \"example\",\n \"source\": {\n \"file_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"file\"\n },\n \"summary\": [],\n \"text\": \"example\",\n \"title\": \"example\",\n \"tool_use_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"example\",\n \"uri\": \"example\",\n \"url\": \"https://example.com\",\n \"url_expires_at\": \"2026-02-18T09:30:00.000Z\",\n \"width\": 1\n }\n ],\n \"handoff_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"note\": \"example\",\n \"text\": \"example\",\n \"type\": \"user.message\"\n }\n ],\n \"message\": \"example\",\n \"referenced_session_ids\": [\n \"example\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"delivery_state": "stored",
"events_accepted": 1,
"ok": true
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "unsupported_media_type",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "bad_gateway",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "gateway_timeout",
"message": "<string>",
"details": {}
}Sessions
Append user/system events to a session
Accepts ordered user and system messages and returns how many were accepted. A running session is woken so the agent sees them, and a finished session resumes to act on them; delivery_state reports how they were delivered. Events are appended in the order given. An omitted or empty events array yields exactly one user turn built from message; the request fails with 400 only when every entry sent was dropped, leaving nothing to append. A top-level image or document block may name a file with source {type: file, file_id}: an unknown, expired, or foreign file answers 404 on that block's source.file_id, a file the block cannot carry (a file whose bytes are not an image on an image block, a binary on a document block, a document over 512 KiB, more than 1 MiB of documents in one event, more than 100 such blocks, or more than 32 MiB of catalog bytes in one request) answers 400 there, and nothing is appended to the transcript; copies of files resolved before the refusal are kept with the session and removed once nothing references them. Without file storage such a block answers 503 file_storage_unconfigured.
POST
/
managed-agents
/
v1
/
sessions
/
{session_id}
/
events
Append user/system events to a session
curl --request POST \
--url https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"actor": "human:api",
"events": [
{
"actor": "human:api",
"content": [
{
"byte_size": 1,
"content": [],
"context": "example",
"data": "example",
"encrypted_content": "example",
"height": 1,
"id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"input": {
"key": "example"
},
"is_error": true,
"media_type": "example",
"name": "example-name",
"omitted_bytes": 1,
"payload": "example",
"provider": "example",
"provider_payload": "example",
"redacted": true,
"semantic_hint": "example",
"sha256": "example",
"signature": "example",
"source": {
"file_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "file"
},
"summary": [],
"text": "example",
"title": "example",
"tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "example",
"uri": "example",
"url": "https://example.com",
"url_expires_at": "2026-02-18T09:30:00.000Z",
"width": 1
}
],
"handoff_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"note": "example",
"text": "example",
"type": "user.message"
}
],
"message": "example",
"referenced_session_ids": [
"example"
]
}
'import requests
url = "https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"
payload = {
"actor": "human:api",
"events": [
{
"actor": "human:api",
"content": [
{
"byte_size": 1,
"content": [],
"context": "example",
"data": "example",
"encrypted_content": "example",
"height": 1,
"id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"input": { "key": "example" },
"is_error": True,
"media_type": "example",
"name": "example-name",
"omitted_bytes": 1,
"payload": "example",
"provider": "example",
"provider_payload": "example",
"redacted": True,
"semantic_hint": "example",
"sha256": "example",
"signature": "example",
"source": {
"file_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "file"
},
"summary": [],
"text": "example",
"title": "example",
"tool_use_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"type": "example",
"uri": "example",
"url": "https://example.com",
"url_expires_at": "2026-02-18T09:30:00.000Z",
"width": 1
}
],
"handoff_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
"note": "example",
"text": "example",
"type": "user.message"
}
],
"message": "example",
"referenced_session_ids": ["example"]
}
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({
actor: 'human:api',
events: [
{
actor: 'human:api',
content: [
{
byte_size: 1,
content: [],
context: 'example',
data: 'example',
encrypted_content: 'example',
height: 1,
id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
input: {key: 'example'},
is_error: true,
media_type: 'example',
name: 'example-name',
omitted_bytes: 1,
payload: 'example',
provider: 'example',
provider_payload: 'example',
redacted: true,
semantic_hint: 'example',
sha256: 'example',
signature: 'example',
source: {file_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d', type: 'file'},
summary: [],
text: 'example',
title: 'example',
tool_use_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
type: 'example',
uri: 'example',
url: 'https://example.com',
url_expires_at: '2026-02-18T09:30:00.000Z',
width: 1
}
],
handoff_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
note: 'example',
text: 'example',
type: 'user.message'
}
],
message: 'example',
referenced_session_ids: ['example']
})
};
fetch('https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events', 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.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events",
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([
'actor' => 'human:api',
'events' => [
[
'actor' => 'human:api',
'content' => [
[
'byte_size' => 1,
'content' => [
],
'context' => 'example',
'data' => 'example',
'encrypted_content' => 'example',
'height' => 1,
'id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'input' => [
'key' => 'example'
],
'is_error' => true,
'media_type' => 'example',
'name' => 'example-name',
'omitted_bytes' => 1,
'payload' => 'example',
'provider' => 'example',
'provider_payload' => 'example',
'redacted' => true,
'semantic_hint' => 'example',
'sha256' => 'example',
'signature' => 'example',
'source' => [
'file_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'type' => 'file'
],
'summary' => [
],
'text' => 'example',
'title' => 'example',
'tool_use_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'type' => 'example',
'uri' => 'example',
'url' => 'https://example.com',
'url_expires_at' => '2026-02-18T09:30:00.000Z',
'width' => 1
]
],
'handoff_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
'note' => 'example',
'text' => 'example',
'type' => 'user.message'
]
],
'message' => 'example',
'referenced_session_ids' => [
'example'
]
]),
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.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events"
payload := strings.NewReader("{\n \"actor\": \"human:api\",\n \"events\": [\n {\n \"actor\": \"human:api\",\n \"content\": [\n {\n \"byte_size\": 1,\n \"content\": [],\n \"context\": \"example\",\n \"data\": \"example\",\n \"encrypted_content\": \"example\",\n \"height\": 1,\n \"id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"input\": {\n \"key\": \"example\"\n },\n \"is_error\": true,\n \"media_type\": \"example\",\n \"name\": \"example-name\",\n \"omitted_bytes\": 1,\n \"payload\": \"example\",\n \"provider\": \"example\",\n \"provider_payload\": \"example\",\n \"redacted\": true,\n \"semantic_hint\": \"example\",\n \"sha256\": \"example\",\n \"signature\": \"example\",\n \"source\": {\n \"file_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"file\"\n },\n \"summary\": [],\n \"text\": \"example\",\n \"title\": \"example\",\n \"tool_use_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"example\",\n \"uri\": \"example\",\n \"url\": \"https://example.com\",\n \"url_expires_at\": \"2026-02-18T09:30:00.000Z\",\n \"width\": 1\n }\n ],\n \"handoff_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"note\": \"example\",\n \"text\": \"example\",\n \"type\": \"user.message\"\n }\n ],\n \"message\": \"example\",\n \"referenced_session_ids\": [\n \"example\"\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://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"actor\": \"human:api\",\n \"events\": [\n {\n \"actor\": \"human:api\",\n \"content\": [\n {\n \"byte_size\": 1,\n \"content\": [],\n \"context\": \"example\",\n \"data\": \"example\",\n \"encrypted_content\": \"example\",\n \"height\": 1,\n \"id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"input\": {\n \"key\": \"example\"\n },\n \"is_error\": true,\n \"media_type\": \"example\",\n \"name\": \"example-name\",\n \"omitted_bytes\": 1,\n \"payload\": \"example\",\n \"provider\": \"example\",\n \"provider_payload\": \"example\",\n \"redacted\": true,\n \"semantic_hint\": \"example\",\n \"sha256\": \"example\",\n \"signature\": \"example\",\n \"source\": {\n \"file_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"file\"\n },\n \"summary\": [],\n \"text\": \"example\",\n \"title\": \"example\",\n \"tool_use_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"example\",\n \"uri\": \"example\",\n \"url\": \"https://example.com\",\n \"url_expires_at\": \"2026-02-18T09:30:00.000Z\",\n \"width\": 1\n }\n ],\n \"handoff_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"note\": \"example\",\n \"text\": \"example\",\n \"type\": \"user.message\"\n }\n ],\n \"message\": \"example\",\n \"referenced_session_ids\": [\n \"example\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.recursion.labelbox.com/managed-agents/v1/sessions/{session_id}/events")
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 \"actor\": \"human:api\",\n \"events\": [\n {\n \"actor\": \"human:api\",\n \"content\": [\n {\n \"byte_size\": 1,\n \"content\": [],\n \"context\": \"example\",\n \"data\": \"example\",\n \"encrypted_content\": \"example\",\n \"height\": 1,\n \"id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"input\": {\n \"key\": \"example\"\n },\n \"is_error\": true,\n \"media_type\": \"example\",\n \"name\": \"example-name\",\n \"omitted_bytes\": 1,\n \"payload\": \"example\",\n \"provider\": \"example\",\n \"provider_payload\": \"example\",\n \"redacted\": true,\n \"semantic_hint\": \"example\",\n \"sha256\": \"example\",\n \"signature\": \"example\",\n \"source\": {\n \"file_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"file\"\n },\n \"summary\": [],\n \"text\": \"example\",\n \"title\": \"example\",\n \"tool_use_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"type\": \"example\",\n \"uri\": \"example\",\n \"url\": \"https://example.com\",\n \"url_expires_at\": \"2026-02-18T09:30:00.000Z\",\n \"width\": 1\n }\n ],\n \"handoff_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n \"note\": \"example\",\n \"text\": \"example\",\n \"type\": \"user.message\"\n }\n ],\n \"message\": \"example\",\n \"referenced_session_ids\": [\n \"example\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"delivery_state": "stored",
"events_accepted": 1,
"ok": true
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "unsupported_media_type",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "bad_gateway",
"message": "<string>",
"details": {}
}{
"code": "analytics",
"message": "<string>",
"details": {}
}{
"code": "gateway_timeout",
"message": "<string>",
"details": {}
}Authorizations
A Recursion API key, created in the console under API keys.
Path Parameters
Session id (UUID) as returned by startSession or listSessions.
Body
application/json
Request body of POST /v1/sessions/{session_id}/events. It has two mutually exclusive forms and events wins: send message for the common case of one plain-text user turn, or send events as ordered typed turns with provider-shaped content. An empty events array always yields exactly one user turn built from message, even when message is empty. The handoff_resolved control form rejects all message and referenced-session fields. The response acknowledges durable acceptance of the turn, not the agent's reply.
Who the turn is attributed to. Defaults to human:api when omitted.
Typed events to append instead of message. When present, message and the top-level actor are ignored.
Show child attributes
Show child attributes
Plain-text message to append as a single user turn. Used only when events is empty.
Prior sessions this session may read from this turn on, by session id, added to any it already has. Each id is authorized under your own scope and grants read access to the whole tree containing it; one you cannot read refuses the whole request with 404 and delivers no message. The grant is recorded before the message, so the turn it starts is the first one that can use it.
Maximum array length:
10Response
Shared response body of POST /v1/sessions/{session_id}/events and POST /v1/sessions/{session_id}/interrupt-and-send. It acknowledges durable acceptance of the turn, never the agent's reply: read the reply by listing events or streaming. Compare events_accepted against what was sent to detect silently dropped entries, and read delivery_state to learn whether an agent is actually going to act on them. events_accepted counts canonical events rather than requests, so interrupt-and-send reports 2 for its single instruction: the stop and the message that follows it.
Shared response body of POST /v1/sessions/{session_id}/events and POST /v1/sessions/{session_id}/interrupt-and-send. It acknowledges durable acceptance of the turn, never the agent's reply: read the reply by listing events or streaming. Compare events_accepted against what was sent to detect silently dropped entries, and read delivery_state to learn whether an agent is actually going to act on them. events_accepted counts canonical events rather than requests, so interrupt-and-send reports 2 for its single instruction: the stop and the message that follows it.
How the accepted events reached a reader. queued: the agent was mid-turn, so the input is waiting outside the transcript and the next turn boundary will read it; interrupt to bring that forward. signaled: the running session was woken and will act on them. resumed: the session had already finished, so it resumed to act on them. stored: appended to the timeline with nothing running to act on them yet.
Available options:
stored, signaled, resumed, queued How many canonical events were written or queued. This counts the inputs actually derived from the body, not its length: a plain message body yields 1, and a typed event with an unrecognised type or no content is dropped, so this can be lower than the events array sent.
Always true. Every event in the request was durably accepted; any partial or total failure is an HTTP error instead, so this field never reports false.