EN

BEEOS CLOUD / DEVELOPER REFERENCE

Conversations

Create, list, rename, delete, cancel, resume, and clear conversations; set the model, reasoning effort, and approval mode.

Overview

The conversations domain manages the conversations of an agent: create, list, read, rename, and delete them, cancel or resume their execution, clear their history, and set the model, reasoning effort, and approval mode. Every operation is scoped by an agent ID.

11 operations · SDK resource: TypeScript cloud.conversations · Python cloud.conversations · Go cloud.Conversations · API overview

Main objects

CreateConversationInput and UpdateConversationInput: the requests to create and rename a conversation.
ConversationResponse: one conversation; ConversationPage lists conversations.
CommandReceiptResponse and ClearConversationReceiptResponse: the receipts of the asynchronous commands.
ApprovalModeSettings, ReasoningSettings, and SetConversationModelInput: the settings you can change.

CreateConversationInput

Field	Type	Required	Description
`title`	`string`	no	Title of the new conversation, at most 512 bytes of valid UTF-8. Omit it to create a conversation without a title. Constraints: `maxLength=256`.

Every field, and the methods that use this object: appendix.

UpdateConversationInput

Field	Type	Required	Description
`title`	`string`	yes	New title of the conversation, 1 to 256 characters after leading and trailing whitespace is removed. Constraints: `minLength=1`, `maxLength=256`.

Every field, and the methods that use this object: appendix.

ConversationResponse

Field	Type	Required	Description
`data`	Conversation	yes	The conversation.

Every field, and the methods that use this object: appendix.

ConversationPage

Field	Type	Required	Description
`conversations`	array<Conversation>	yes	Conversations on this page.
`next_cursor`	`string`	no	Cursor to pass as `cursor` to get the next page. Empty when `has_more` is false.
`has_more`	`boolean`	yes	Whether more conversations are available after this page.

Every field, and the methods that use this object: appendix.

CommandReceiptResponse

Field	Type	Required	Description
`data`	CommandReceipt	yes	The receipt of the request.

Every field, and the methods that use this object: appendix.

ClearConversationReceiptResponse

Field	Type	Required	Description
`data`	ClearConversationReceipt	yes	The receipt of the clear operation.

Every field, and the methods that use this object: appendix.

ApprovalModeSettings

Field	Type	Required	Description
`approval_mode`	`string`	yes	Approval mode to set for the conversation: lowercase letters, digits and underscores, starting with a letter, at most 32 characters. `ask` and `full` are the modes defined so far. New modes can be added, and an agent treats a mode it does not know as `ask`. Send `null` to remove the setting so the instance default applies. Nullable. Constraints: `minLength=1`, `maxLength=32`, `pattern=^[a-z][a-z0-9_]*$`.

Every field, and the methods that use this object: appendix.

ReasoningSettings

Field	Type	Required	Description
`modelId`	`string`	yes	ID of the model that `reasoningOverrideId` applies to, 1 to 512 characters. Constraints: `minLength=1`, `maxLength=512`.
`reasoningOverrideId`	`string`	yes	ID of the reasoning option to use with the model, 1 to 64 characters. Send `null` to use the model's default. Nullable. Constraints: `minLength=1`, `maxLength=64`.

Every field, and the methods that use this object: appendix.

SetConversationModelInput

Field	Type	Required	Description
`model_override_id`	`string`	yes	ID of the model to use for this conversation, at most 512 characters. Send `null` to remove the override so the agent's default model is used again. When the override changes, the conversation's `reasoning` is cleared. Nullable. Constraints: `maxLength=512`.

Every field, and the methods that use this object: appendix.

Conversation

Field	Type	Required	Description
`id`	`string`	yes	ID of the conversation. Constraints: `minLength=1`.
`agent_id`	`string`	yes	ID of the agent the conversation is with, the `id` returned by the agents API. Constraints: `minLength=1`.
`instance_id`	`string`	yes	ID of the instance the agent runs on. Constraints: `minLength=1`.
`title`	`string`	yes	Title of the conversation. Empty when no title was set.
`state`	`string`	yes	Whether the conversation still accepts messages. A closed conversation stays readable but cannot receive new messages. Allowed values: `"open"` — The conversation accepts new messages; `"closed"` — The conversation was closed, for example by deleting it. `closed_at` is set, and sending to it returns 410 `conversation_closed`. (enum table)
`metadata_version`	`integer`	yes	Version of the conversation settings (title, model override, reasoning and approval mode). It increases by one on every change. It always equals `resource_version`. Constraints: `minimum=1`, `format=int64`.
`history_generation`	`integer`	yes	Generation of the conversation history. It increases by one each time the history is cleared, so a larger value means messages sent before the latest clear are no longer part of the history. Constraints: `minimum=0`, `format=int64`.
`created_at`	`string`	yes	Time the conversation was created, in RFC 3339 format. Constraints: `format=date-time`.
`last_activity_at`	`string`	no	Time of the latest activity in the conversation, in RFC 3339 format. Omitted when no activity is recorded. Constraints: `format=date-time`.
`closed_at`	`string`	no	Time the conversation was closed, in RFC 3339 format. Omitted while the conversation is open. Constraints: `format=date-time`.
`resource_version`	`integer`	yes	Version of the conversation to send as `If-Match`, in double quotes, when you rename it or change its model, reasoning or approval mode. The same value is returned in the `ETag` header when you read or update a single conversation. Constraints: `minimum=1`, `format=int64`.
`model_override_id`	`string`	no	ID of the model that overrides the agent's default model for this conversation. Omitted when no override is set.
`effective_model_id`	`string`	no	Reserved. The Server API does not currently return this field; use `model_override_id`.
`active_response`	ActiveConversationResponse	no	The response that is currently being produced in the conversation. Returned only when you read a single conversation, and only while a response is in progress.
`reasoning`	ReasoningSettings	no	Reasoning selection set for the conversation: the model and the reasoning option chosen for it. Omitted when none is set. It is cleared when `model_override_id` changes.
`approval_mode`	`string`	no	Approval mode set for the conversation. Omitted when none is set and the instance default applies. Nullable.

Every field, and the methods that use this object: appendix.

CommandReceipt

Field	Type	Required	Description
`request_id`	`string`	yes	ID of the request. For cancel and resume it identifies the control message that was sent to the agent; for a model change it is the ID of this HTTP request.
`status`	`string`	yes	Outcome of the request at the time the call returned. Allowed values: `"accepted"` — The request was queued for the agent and has not taken effect yet. Read the conversation messages to follow the result; `"completed"` — The change was applied before the call returned. (enum table)

Every field, and the methods that use this object: appendix.

ClearConversationReceipt

Field	Type	Required	Description
`request_id`	`string`	yes	ID of the clear operation. Retrying with the same `Idempotency-Key` returns the same ID.
`conversation_id`	`string`	yes	ID of the conversation that was cleared.
`current_generation`	`integer`	yes	History generation after the clear. Messages from earlier generations are no longer part of the conversation history. Constraints: `minimum=0`, `format=int64`.
`status`	`string`	yes	Outcome of the clear at the time the call returned. Allowed values: `"completed"` — The history was cleared before the call returned.

Every field, and the methods that use this object: appendix.

Typical flow

Create a conversation for an agent with conversations.create; find existing ones with conversations.list and conversations.get.
Adjust it with conversations.setModel, conversations.setReasoning, and conversations.setApprovalMode.
Stop work with conversations.cancel and continue a paused conversation with conversations.resume.
Reset it with conversations.clear, rename it with conversations.update, or remove it with conversations.delete.
Read its messages with the messages domain.

Methods

Method	HTTP	Summary
conversations.list	`GET /v1/agents/{agentId}/conversations`	List conversations
conversations.create	`POST /v1/agents/{agentId}/conversations`	Create a conversation
conversations.get	`GET /v1/agents/{agentId}/conversations/{conversationId}`	Get a conversation
conversations.update	`PATCH /v1/agents/{agentId}/conversations/{conversationId}`	Rename a conversation
conversations.delete	`DELETE /v1/agents/{agentId}/conversations/{conversationId}`	Delete a conversation
conversations.setApprovalMode	`PUT /v1/agents/{agentId}/conversations/{conversationId}/approval-mode`	Set the conversation approval mode
conversations.cancel	`POST /v1/agents/{agentId}/conversations/{conversationId}/cancel`	Cancel conversation execution
conversations.clear	`POST /v1/agents/{agentId}/conversations/{conversationId}/clear`	Clear conversation history
conversations.setModel	`PUT /v1/agents/{agentId}/conversations/{conversationId}/model`	Set the conversation model override
conversations.setReasoning	`PUT /v1/agents/{agentId}/conversations/{conversationId}/reasoning`	Set the conversation reasoning effort
conversations.resume	`POST /v1/agents/{agentId}/conversations/{conversationId}/resume`	Resume a paused conversation

conversations.list

GET /v1/agents/{agentId}/conversations · Operation ID listAgentConversations

List conversations

Required scopes: conversations:read.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.list`	`list(agentId: string, query?: Models.ListAgentConversationsQuery): Promise<Models.ListAgentConversationsResponse>`
Python	`cloud.conversations.list`	`def list(self, agent_id: str, options: ListAgentConversationsOptions \| None = None) -> ConversationPage`
Go	`cloud.Conversations.List`	`func (r *ConversationsResource) List(ctx context.Context, agentId string, options ListAgentConversationsOptions) (ConversationPage, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`cursor`	query	`string`	no	Cursor from `next_cursor` of the previous page. Omit it to get the first page. At most 4096 characters.
`limit`	query	`integer`	no	Maximum number of conversations to return in one page. Defaults to 50. Values from 1 to 200 are accepted. Constraints: `minimum=1`, `maximum=100`.
`state`	query	`string`	no	Which conversations to list: `open` for conversations that accept messages (default), `closed` for closed conversations such as deleted ones, or `all` for both. Allowed values: `"open"`, `"closed"`, `"all"`.

Response

200 Authorized conversation directory · application/json · Schema: ConversationPage

Field	Type	Required	Description
`conversations`	array<Conversation>	yes	Conversations on this page.
`next_cursor`	`string`	no	Cursor to pass as `cursor` to get the next page. Empty when `has_more` is false.
`has_more`	`boolean`	yes	Whether more conversations are available after this page.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.list("agent_123");
console.log(result);

conversations.create

POST /v1/agents/{agentId}/conversations · Operation ID createAgentConversation

Create a conversation

Required scopes: conversations:write.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.create`	`create(agentId: string, input: Models.CreateConversationInput, idempotencyKey: string): Promise<Models.CreateAgentConversationResponse>`
Python	`cloud.conversations.create`	`def create(self, agent_id: str, input: CreateConversationInput, options: CreateAgentConversationOptions) -> ConversationResponse`
Go	`cloud.Conversations.Create`	`func (r *ConversationsResource) Create(ctx context.Context, agentId string, input CreateConversationInput, options CreateAgentConversationOptions) (ConversationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=8`, `maxLength=128`.

Request body

application/json · required · Schema: CreateConversationInput

Field	Type	Required	Description
`title`	`string`	no	Title of the new conversation, at most 512 bytes of valid UTF-8. Omit it to create a conversation without a title. Constraints: `maxLength=256`.

Response

201 Durable conversation created or replayed · application/json · Schema: ConversationResponse

Field	Type	Required	Description
`data`	Conversation	yes	The conversation.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.create("agent_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.get

GET /v1/agents/{agentId}/conversations/{conversationId} · Operation ID getConversation

Get a conversation

Required scopes: conversations:read.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.get`	`get(agentId: string, conversationId: string): Promise<Models.GetConversationResponse>`
Python	`cloud.conversations.get`	`def get(self, agent_id: str, conversation_id: str) -> ConversationResponse`
Go	`cloud.Conversations.Get`	`func (r *ConversationsResource) Get(ctx context.Context, agentId string, conversationId string) (ConversationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.

Response

200 Authorized conversation · application/json · Schema: ConversationResponse

Field	Type	Required	Description
`data`	Conversation	yes	The conversation.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.get("agent_123", "conversation_123");
console.log(result);

conversations.update

PATCH /v1/agents/{agentId}/conversations/{conversationId} · Operation ID updateConversation

Rename a conversation

Required scopes: conversations:write.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.update`	`update(agentId: string, conversationId: string, input: Models.UpdateConversationInput, version: number): Promise<Models.UpdateConversationResponse>`
Python	`cloud.conversations.update`	`def update(self, agent_id: str, conversation_id: str, input: UpdateConversationInput, options: UpdateConversationOptions) -> ConversationResponse`
Go	`cloud.Conversations.Update`	`func (r *ConversationsResource) Update(ctx context.Context, agentId string, conversationId string, input UpdateConversationInput, options UpdateConversationOptions) (ConversationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`If-Match`	header	`string`	yes	Version of the conversation the change is based on: its `resource_version` in double quotes, for example `"3"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`. Constraints: `pattern=^"[1-9][0-9]*"$`.

Request body

application/json · required · Schema: UpdateConversationInput

Field	Type	Required	Description
`title`	`string`	yes	New title of the conversation, 1 to 256 characters after leading and trailing whitespace is removed. Constraints: `minLength=1`, `maxLength=256`.

Response

200 Conversation renamed · application/json · Schema: ConversationResponse

Field	Type	Required	Description
`data`	Conversation	yes	The conversation.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.update("agent_123", "conversation_123", { title: "example_title" }, 1);
console.log(result);

conversations.delete

DELETE /v1/agents/{agentId}/conversations/{conversationId} · Operation ID deleteConversation

Delete a conversation

Required scopes: conversations:write.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.delete`	`delete(agentId: string, conversationId: string, idempotencyKey: string): Promise<Models.DeleteConversationResponse>`
Python	`cloud.conversations.delete`	`def delete(self, agent_id: str, conversation_id: str, options: DeleteConversationOptions) -> None`
Go	`cloud.Conversations.Delete`	`func (r *ConversationsResource) Delete(ctx context.Context, agentId string, conversationId string, options DeleteConversationOptions) error`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=8`, `maxLength=128`.

Response

204 Conversation deleted

No response body.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.delete("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.setApprovalMode

PUT /v1/agents/{agentId}/conversations/{conversationId}/approval-mode · Operation ID setConversationApprovalMode

Set the conversation approval mode

Required scopes: conversations:control.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.setApprovalMode`	`setApprovalMode(agentId: string, conversationId: string, input: Models.ApprovalModeSettings, version: number): Promise<Models.SetConversationApprovalModeResponse>`
Python	`cloud.conversations.set_approval_mode`	`def set_approval_mode(self, agent_id: str, conversation_id: str, input: ApprovalModeSettings, options: SetConversationApprovalModeOptions) -> ApprovalModeResultResponse`
Go	`cloud.Conversations.SetApprovalMode`	`func (r *ConversationsResource) SetApprovalMode(ctx context.Context, agentId string, conversationId string, input ApprovalModeSettings, options SetConversationApprovalModeOptions) (ApprovalModeResultResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`If-Match`	header	`string`	yes	Version of the conversation the change is based on: its `resource_version` in double quotes, for example `"3"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`. Constraints: `pattern=^"[1-9][0-9]*"$`.

Request body

application/json · required · Schema: ApprovalModeSettings

Field	Type	Required	Description
`approval_mode`	`string`	yes	Approval mode to set for the conversation: lowercase letters, digits and underscores, starting with a letter, at most 32 characters. `ask` and `full` are the modes defined so far. New modes can be added, and an agent treats a mode it does not know as `ask`. Send `null` to remove the setting so the instance default applies. Nullable. Constraints: `minLength=1`, `maxLength=32`, `pattern=^[a-z][a-z0-9_]*$`.

Response

200 Approval mode desired state confirmed · application/json · Schema: ApprovalModeResultResponse

Field	Type	Required	Description
`data`	ApprovalModeResult	yes	The result of the change.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.setApprovalMode("agent_123", "conversation_123", { approval_mode: "example_approval_mode" }, 1);
console.log(result);

conversations.cancel

POST /v1/agents/{agentId}/conversations/{conversationId}/cancel · Operation ID cancelConversation

Cancel conversation execution

Required scopes: conversations:control.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.cancel`	`cancel(agentId: string, conversationId: string, idempotencyKey: string, input?: JSONValue): Promise<Models.CancelConversationResponse>`
Python	`cloud.conversations.cancel`	`def cancel(self, agent_id: str, conversation_id: str, input: CancelConversationInput, options: CancelConversationOptions) -> CommandReceiptResponse`
Go	`cloud.Conversations.Cancel`	`func (r *ConversationsResource) Cancel(ctx context.Context, agentId string, conversationId string, input CancelConversationInput, options CancelConversationOptions) (CommandReceiptResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=8`, `maxLength=128`.

Request body

application/json · required · Schema: CancelConversationInput

Field	Type	Required	Description
`target_message_id`	`string`	yes	ID of the `chat_message` whose turn should stop, 1 to 256 characters. Constraints: `minLength=1`, `maxLength=256`.
`reason`	`string`	no	Why the turn is stopped, as free text of at most 256 characters. When it is omitted or empty, `user_request` is recorded. Constraints: `maxLength=256`.

Response

202 Cancel accepted · application/json · Schema: CommandReceiptResponse

Field	Type	Required	Description
`data`	CommandReceipt	yes	The receipt of the request.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.cancel("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.clear

POST /v1/agents/{agentId}/conversations/{conversationId}/clear · Operation ID clearConversation

Clear conversation history

Required scopes: conversations:control.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.clear`	`clear(agentId: string, conversationId: string, idempotencyKey: string): Promise<Models.ClearConversationResponse>`
Python	`cloud.conversations.clear`	`def clear(self, agent_id: str, conversation_id: str, options: ClearConversationOptions) -> ClearConversationReceiptResponse`
Go	`cloud.Conversations.Clear`	`func (r *ConversationsResource) Clear(ctx context.Context, agentId string, conversationId string, options ClearConversationOptions) (ClearConversationReceiptResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`. Constraints: `minLength=8`, `maxLength=128`.

Response

202 Clear accepted · application/json · Schema: ClearConversationReceiptResponse

Field	Type	Required	Description
`data`	ClearConversationReceipt	yes	The receipt of the clear operation.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.clear("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

conversations.setModel

PUT /v1/agents/{agentId}/conversations/{conversationId}/model · Operation ID setConversationModel

Set the conversation model override

Required scopes: conversations:control.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.setModel`	`setModel(agentId: string, conversationId: string, modelId: string \| null, version: number): Promise<Models.SetConversationModelResponse>`
Python	`cloud.conversations.set_model`	`def set_model(self, agent_id: str, conversation_id: str, input: SetConversationModelInput, options: SetConversationModelOptions) -> CommandReceiptResponse`
Go	`cloud.Conversations.SetModel`	`func (r *ConversationsResource) SetModel(ctx context.Context, agentId string, conversationId string, input SetConversationModelInput, options SetConversationModelOptions) (CommandReceiptResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`If-Match`	header	`string`	yes	Version of the conversation the change is based on: its `resource_version` in double quotes, for example `"3"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`. Constraints: `pattern=^"[1-9][0-9]*"$`.

Request body

application/json · required · Schema: SetConversationModelInput

Field	Type	Required	Description
`model_override_id`	`string`	yes	ID of the model to use for this conversation, at most 512 characters. Send `null` to remove the override so the agent's default model is used again. When the override changes, the conversation's `reasoning` is cleared. Nullable. Constraints: `maxLength=512`.

Response

202 Model change accepted · application/json · Schema: CommandReceiptResponse

Field	Type	Required	Description
`data`	CommandReceipt	yes	The receipt of the request.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.setModel("agent_123", "conversation_123", "model_override_123", 1);
console.log(result);

conversations.setReasoning

PUT /v1/agents/{agentId}/conversations/{conversationId}/reasoning · Operation ID setConversationReasoning

Set the conversation reasoning effort

Required scopes: conversations:control.

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.setReasoning`	`setReasoning(agentId: string, conversationId: string, input: Models.ReasoningSettings, version: number): Promise<Models.SetConversationReasoningResponse>`
Python	`cloud.conversations.set_reasoning`	`def set_reasoning(self, agent_id: str, conversation_id: str, input: ReasoningSettings, options: SetConversationReasoningOptions) -> ReasoningResultResponse`
Go	`cloud.Conversations.SetReasoning`	`func (r *ConversationsResource) SetReasoning(ctx context.Context, agentId string, conversationId string, input ReasoningSettings, options SetConversationReasoningOptions) (ReasoningResultResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`If-Match`	header	`string`	yes	Version of the conversation the change is based on: its `resource_version` in double quotes, for example `"3"`. A different current version returns 412 `resource_version_conflict`; a missing header returns 428 `precondition_required`. Constraints: `pattern=^"[1-9][0-9]*"$`.

Request body

application/json · required · Schema: ReasoningSettings

Field	Type	Required	Description
`modelId`	`string`	yes	ID of the model that `reasoningOverrideId` applies to, 1 to 512 characters. Constraints: `minLength=1`, `maxLength=512`.
`reasoningOverrideId`	`string`	yes	ID of the reasoning option to use with the model, 1 to 64 characters. Send `null` to use the model's default. Nullable. Constraints: `minLength=1`, `maxLength=64`.

Response

200 Reasoning desired state confirmed · application/json · Schema: ReasoningResultResponse

Field	Type	Required	Description
`data`	ReasoningResult	yes	The result of the change.

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.setReasoning("agent_123", "conversation_123", { modelId: "model_123", reasoningOverrideId: "reasoning_override_123" }, 1);
console.log(result);

conversations.resume

POST /v1/agents/{agentId}/conversations/{conversationId}/resume · Operation ID resumeConversation

Resume a paused conversation

SDK methods

Language	Method	Signature
TypeScript	`cloud.conversations.resume`	`resume(agentId: string, conversationId: string, idempotencyKey: string): Promise<Models.ResumeConversationResponse>`
Python	`cloud.conversations.resume`	`def resume(self, agent_id: str, conversation_id: str, options: ResumeConversationOptions) -> ResumeConversationResponse`
Go	`cloud.Conversations.Resume`	`func (r *ConversationsResource) Resume(ctx context.Context, agentId string, conversationId string, options ResumeConversationOptions) (ResumeConversationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	`string`	yes	ID of the agent, the `id` returned by the agents API.
`conversationId`	path	`string`	yes	ID of the conversation, as returned when it was created or listed.
`Idempotency-Key`	header	`string`	yes	Key that makes retries of this request safe, 8 to 128 characters without leading or trailing whitespace. Retrying with the same key and the same content returns the original result; reusing the key with different content returns 409 `idempotency_conflict`.

Response

200 · application/json

Field	Type	Required	Description
`data`	`object`	yes	—
`data.request_id`	`string`	yes	—
`data.status`	`string`	yes	—

Errors

Status	Schema	Description
other (default)	ErrorResponse	Cloud Server error

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.conversations.resume("agent_123", "conversation_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

BeeOS CloudBack to documentation