Stream events

Stream events

curl --request GET \
  --url https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "org_id": "<string>",
  "project_id": "<string>",
  "agent_id": "<string>",
  "turn_id": "<string>",
  "turn_sequence": 4503599627370496,
  "is_opening_event": true,
  "sequence": 4503599627370496,
  "event_kind": "agent_input",
  "agent_input_id": "<string>",
  "input_kind": "content",
  "content_blocks": [
    {
      "type": "text",
      "text": "<string>",
      "metadata": {}
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "actor_id": "<string>",
  "input_idempotency_key": "<string>",
  "control_type": "cancel_current",
  "interaction_id": "<string>",
  "agent_config_id": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

GET

orgs

{orgID}

projects

{projectID}

agents

{agentID}

events

stream

Stream events

curl --request GET \
  --url https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.staging.bma.beeos.ai/api/v1/orgs/{orgID}/projects/{projectID}/agents/{agentID}/events/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "<string>",
  "org_id": "<string>",
  "project_id": "<string>",
  "agent_id": "<string>",
  "turn_id": "<string>",
  "turn_sequence": 4503599627370496,
  "is_opening_event": true,
  "sequence": 4503599627370496,
  "event_kind": "agent_input",
  "agent_input_id": "<string>",
  "input_kind": "content",
  "content_blocks": [
    {
      "type": "text",
      "text": "<string>",
      "metadata": {}
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "actor_id": "<string>",
  "input_idempotency_key": "<string>",
  "control_type": "cancel_current",
  "interaction_id": "<string>",
  "agent_config_id": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>",
  "current_digest": "<string>",
  "issues": [
    {
      "path": "<string>",
      "message": "<string>",
      "line": 2,
      "column": 2
    }
  ]
}

{
  "error": "<string>",
  "code": "<string>"
}

{
  "error": "<string>",
  "code": "<string>"
}

Authorizations

Authorization

string

header

required

An opaque BMA personal or organization bearer token.

Headers

Last-Event-ID

integer<int64>

Required range: x >= 0

Path Parameters

orgID

string

required

Organization ID (org_...).

Pattern: ^org_[a-z2-7]{26}$

projectID

string

required

Project ID (proj_...).

Pattern: ^proj_[a-z2-7]{26}$

agentID

string

required

Agent ID (agt_...).

Pattern: ^agt_[a-z2-7]{26}$

Query Parameters

session_id

string

Agent session ID (ses_...). Omit to use the agent's default session.

Pattern: ^ses_[a-z2-7]{26}$

after_sequence

integer<int64>

Required range: x >= 0

stream_deltas

boolean

Opt in to ephemeral delta streamed frames while a model call is in flight. This includes partial assistant text, tool call, and reasoning output. Each frame carries the public turn_id and model_call_context_id it belongs to, and tool_use block starts carry the same public tool_call_id the durable model_output content block and tool_result event will use. Deltas are best-effort: they are not persisted and are not replayed on reconnect. The durable model_output event remains the source of truth. Default false.

Response

Server-sent event stream. Durable frames use agent_input, model_output, tool_result, or context_checkpoint as the SSE event name and set the SSE id field to the event's sequence, which reconnects can replay via Last-Event-ID. Best-effort tool lifecycle updates use tool_call_update and cover this agent and every subagent beneath it, model previews use model_output_delta, and stream-closing errors use error; none carries an SSE id, so reconnects resume from the last durable event. The response closes after every error frame. Raw clients reconnect when the error's stable code is service_unavailable and treat other current codes as terminal. Heartbeats are SSE comments and carry no JSON payload.

One JSON payload from the event stream: an authoritative durable event, a best-effort tool-call update, a best-effort model-output preview, or a stream-closing error. The wire response ends after an error payload; service_unavailable is retryable and other current codes are terminal.

string

required

Pattern: ^evt_[a-z2-7]{26}$

org_id

string

required

Pattern: ^org_[a-z2-7]{26}$

project_id

string

required

Project ID (proj_...).

Pattern: ^proj_[a-z2-7]{26}$

agent_id

string

required

Pattern: ^agt_[a-z2-7]{26}$

turn_id

string

required

Pattern: ^trn_[a-z2-7]{26}$

turn_sequence

integer

required

Positive per-agent event, turn, or live-frame sequence.

Required range: 1 <= x <= 9007199254740991

is_opening_event

boolean

required

sequence

integer

required

Positive per-agent event, turn, or live-frame sequence.

Required range: 1 <= x <= 9007199254740991

event_kind

enum<string>

required

Available options:

agent_input

agent_input_id

string

required

Matches the input that produced this event, allowing clients to correlate an input submission with its durable timeline admission.

Pattern: ^ain_[a-z2-7]{26}$

input_kind

enum<string>

required

Available options:

content,

control,

interaction_response,

config_change

content_blocks

object[]

required

Option 1
Option 2

Show child attributes

created_at

string<date-time>

required

actor_id

string

Actor attributed to the input. Resolve details through the project actors endpoints.

Pattern: ^actr_[a-z2-7]{26}$

input_idempotency_key

string

Echoes the Idempotency-Key of a content-input request so its sender can recognize the durable admission. Absent for other input kinds.

control_type

enum<string>

Available options:

cancel_current

interaction_id

string

Interaction answered by an interaction_response input.

Pattern: ^int_[a-z2-7]{26}$

agent_config_id

string

Configuration selected by a config_change input.

Pattern: ^acfg_[a-z2-7]{26}$

API reference

Native REST API

Managed Agents extensions

Authorizations

Headers

Path Parameters

Query Parameters

Response