This reference is currently available in English. The Cloud console remains in your selected language.

BEEOS CLOUD / DEVELOPER REFERENCE

Automations

Create, update, pause, resume, and delete automations; start and read runs; create webhook automations.

Overview

The automations domain manages automations: create, list, read, update, pause, resume, and delete them, start and read their runs, and create webhook automations.

11 operations · SDK resource: TypeScript cloud.automations · Python cloud.automations · Go cloud.Automations · API overview

Main objects

ProtoAutomationInput and ProtoAutomationPatch: the requests to create and update an automation.
ProtoAutomationRule, ProtoAutomationSchedule, and ProtoAutomationTarget: what an automation consists of.
ProtoAutomationRunInput and ProtoAutomationRun: starting a run and the run itself.
ProtoAutomationWebhookInput: the request for a webhook automation.

ProtoAutomationInput

Field	Type	Required	Description
`name`	`string`	no	Display name of the automation, 1 to 256 characters and not blank.
`prompt`	`string`	no	Text sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to. Required.
`schedule`	ProtoAutomationSchedule	no	When the automation runs. Required.
`session`	ProtoAutomationSession	no	Not accepted by this API: a request that includes it fails with 400 `invalid_argument`. Automations created here open a new conversation for every run.
`validFrom`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound. It must not be after `validUntil`. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound. After it the automation becomes `expired`. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation is created from, if any. It must be a conversation of the same end user.

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

ProtoAutomationPatch

Field	Type	Required	Description
`name`	`string`	no	New display name, 1 to 256 characters and not blank.
`prompt`	`string`	no	New prompt sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	New agent the prompt is sent to.
`schedule`	ProtoAutomationSchedule	no	New schedule. It replaces the whole schedule, so send every field the `kind` needs, including `anchorAt` for `every`.
`session`	ProtoAutomationSession	no	Not accepted by this API: a request that includes it fails with 400 `invalid_argument`.
`validFrom`	`string`	no	New earliest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidFrom`. Constraints: `format=date-time`.
`validUntil`	`string`	no	New latest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidUntil`. Constraints: `format=date-time`.
`clearValidFrom`	`boolean`	no	Set to true to remove the lower bound of the validity period. Cannot be combined with `validFrom`.
`clearValidUntil`	`boolean`	no	Set to true to remove the upper bound of the validity period. Cannot be combined with `validUntil`.

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

ProtoAutomationRule

Field	Type	Required	Description
`id`	`string`	no	Unique ID of the automation.
`name`	`string`	no	Display name of the automation.
`prompt`	`string`	no	Text sent to the agent on every run.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to.
`schedule`	ProtoAutomationSchedule	no	When the automation runs. Empty (`kind` unset) for `webhook` automations.
`session`	ProtoAutomationSession	no	How runs choose their conversation. Automations created through this API always use `new`.
`validFrom`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Null when there is no lower bound. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Null when there is no upper bound. Constraints: `format=date-time`.
`status`	`string`	no	State of the automation. Allowed values: `"enabled"` — Active. A `schedule` automation runs at `nextFireAt`; a `webhook` automation reacts to incoming events; `"paused"` — Paused with the pause operation. No runs are created until it is resumed; `"expired"` — A `schedule` automation with no run left, for example a finished `at` schedule or one past `validUntil`. (enum table)
`nextFireAt`	`string`	no	Time of the next scheduled run, as an RFC 3339 timestamp. Null when the automation is paused or expired and for `webhook` automations. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation was created from. Empty when it was not created from a conversation.
`createdAt`	`string`	no	Time the automation was created, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`updatedAt`	`string`	no	Time the automation was last changed, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`triggerKind`	`string`	no	What starts a run. Automations created before webhook triggers existed can report an empty value; treat it as `schedule`. Allowed values: `"schedule"` — Runs start on the `schedule`; `"webhook"` — Runs start when the event source delivers an event, optionally narrowed by `eventFilter`. (enum table)
`hookId`	`string`	no	ID of the endpoint that receives the events of a `webhook` automation. Empty for `schedule` automations and for Gmail automations.
`source`	`string`	no	Platform that sends the events of a `webhook` automation, for example `github` or `gmail`. Empty for `schedule` automations.
`eventFilter`	`string`	no	Event type that starts a run of a `webhook` automation. Empty when every event starts a run.
`mailbox`	`string`	no	Gmail address a `webhook` automation watches. Empty for other sources.

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

ProtoAutomationSchedule

Field	Type	Required	Description
`kind`	`string`	no	Type of the schedule. It decides which of the other fields are required. Allowed values: `"at"` — Runs once, at `at`; `"every"` — Runs repeatedly, every `intervalSeconds` seconds counted from `anchorAt`; `"cron"` — Runs on the five-field cron `expression`, evaluated in the time zone `tz`. (enum table)
`tz`	`string`	no	IANA time zone name, for example `Asia/Shanghai`. Required for every kind; `Local` is not accepted.
`at`	`string`	no	Time of the single run, as an RFC 3339 timestamp. Required when `kind` is `at`; not allowed for other kinds. Constraints: `format=date-time`.
`intervalSeconds`	`string`	no	Seconds between runs, as a decimal string. Required and greater than 0 when `kind` is `every`; not allowed for other kinds.
`anchorAt`	`string`	no	Time the interval is counted from, as an RFC 3339 timestamp: runs fall on `anchorAt` plus whole multiples of the interval. When creating an `every` schedule it defaults to the creation time; when replacing a schedule it is required. Not allowed for other kinds. Constraints: `format=date-time`.
`expression`	`string`	no	Five-field cron expression: minute, hour, day of month, month and day of week. Required when `kind` is `cron`; not allowed for other kinds.

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

ProtoAutomationTarget

Field	Type	Required	Description
`instanceId`	`string`	no	ID of the instance the automation runs on.
`agentId`	`string`	no	ID of the agent that receives the prompt. It must be an active agent of `instanceId` in your app. Required.

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

ProtoAutomationRunInput

Field	Type	Required	Description
`sourceRunId`	`string`	no	ID of an earlier run of the same automation to repeat. Send it together with `rerunSessionMode`, or send neither for a plain manual run.
`rerunSessionMode`	`string`	no	Which conversation the rerun is delivered into. Required when `sourceRunId` is sent and not allowed without it. Allowed values: `"original"` — The conversation the source run was delivered into; `"new"` — A new conversation. (enum table)

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

ProtoAutomationRun

Field	Type	Required	Description
`id`	`string`	no	Unique ID of the run.
`automationId`	`string`	no	ID of the automation the run belongs to.
`triggerType`	`string`	no	What created the run. Allowed values: `"schedule"` — The automation's schedule came due; `"manual"` — A caller started it with the create-run operation; `"rerun"` — A caller started it with the create-run operation to repeat the earlier run in `sourceRunId`; `"webhook"` — An event arrived for a `webhook` automation. (enum table)
`scheduledAt`	`string`	no	Time the run was due, as an RFC 3339 timestamp: the scheduled time for scheduled runs, the time of the request or event for the others. Constraints: `format=date-time`.
`createdAt`	`string`	no	Time the run was created, as an RFC 3339 timestamp. Constraints: `format=date-time`.
`status`	`string`	no	Delivery state of the run. It tells whether the prompt reached the agent's conversation, not whether the agent finished the work. Allowed values: `"scheduled"` — Created and waiting to be delivered. A `reasonCode` of `dispatch_unconfirmed` means delivery started and its outcome is not confirmed yet; `"dispatched"` — The prompt was accepted into the conversation named by `conversationId`; `"failed"` — Delivery was rejected before the prompt was sent. `reasonCode` tells why; `"skipped"` — Not delivered because a condition no longer held when the run was due. `reasonCode` tells why. (enum table)
`target`	ProtoAutomationTarget	no	Agent the run delivers to, copied from the automation when the run was created.
`session`	ProtoAutomationSession	no	How the run chooses its conversation, copied from the automation when the run was created. A rerun sets it from `rerunSessionMode`.
`conversationId`	`string`	no	ID of the conversation the prompt is delivered into. Empty until the run is bound to a conversation.
`wakeMessageId`	`string`	no	ID of the conversation message that carries the prompt. It equals the run `id`.
`sourceRunId`	`string`	no	ID of the run this run repeats. Set only for reruns.
`rerunSessionMode`	`string`	no	Which conversation a rerun is delivered into. Empty for runs that are not reruns. Allowed values: `"original"` — The conversation the source run was delivered into; `"new"` — A new conversation. (enum table)
`reasonCode`	`string`	no	Why a run was skipped or failed, or is unconfirmed. Empty otherwise and after the prompt was accepted. Skip reasons include `outside_validity`, `missed_schedule` (the run was not delivered within its window), `automation_paused`, `automation_deleted` and `preparation_stale` (the agent or session of the automation changed after the run was created). A failed run carries an API error code such as `target_not_found`, `permission_denied`, `conversation_unavailable` or `dependency_unavailable`. `dispatch_unconfirmed` means delivery started and its outcome is unknown. New codes can be added, so ignore codes you do not know.
`dispatchedAt`	`string`	no	Time the prompt was accepted, as an RFC 3339 timestamp. Null until `status` is `dispatched`. Constraints: `format=date-time`.

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

ProtoAutomationWebhookInput

Field	Type	Required	Description
`name`	`string`	no	Display name of the automation, 1 to 256 characters and not blank.
`prompt`	`string`	no	Text sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to. Required.
`session`	ProtoAutomationSession	no	Not accepted by this API: a request that includes it fails with 400 `invalid_argument`. Automations created here open a new conversation for every run.
`validFrom`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation is created from, if any. It must be a conversation of the same end user.
`source`	`string`	no	Platform that sends the events, for example `github` or `gmail`, at most 64 characters without whitespace. The agent must have the matching connector set up. Required.
`events`	`array<string>`	no	Names of the events to subscribe to at the source, for example the GitHub event types the repository should deliver.
`repoOwner`	`string`	no	Owner of the repository to watch. Required when `source` is `github`.
`repoName`	`string`	no	Name of the repository to watch. Required when `source` is `github`.
`eventFilter`	`string`	no	Event type that starts a run. When set, only events of exactly this type start a run; others are skipped. Empty accepts every event.
`mailbox`	`string`	no	Gmail address to watch. Required when `source` is `gmail`; leave empty for other sources.

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

ProtoAutomationSession

Field	Type	Required	Description
`mode`	`string`	no	How a run chooses the conversation it is delivered into. Allowed values: `"new"` — Every run opens a new conversation with the agent. Automations created through this API always use it; `"bound"` — Every run is delivered into the conversation named by `boundConversationId`. (enum table)
`boundConversationId`	`string`	no	ID of the conversation runs are delivered into. Set only when `mode` is `bound`; empty otherwise.

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

Typical flow

Create an automation with automations.create, or a webhook automation with automations.createWebhook.
Read or list with automations.get and automations.list; change with automations.update.
Stop and restart it with automations.pause and automations.resume.
Start a run with automations.createRun and follow it with automations.getRun and automations.listRuns.
Remove it with automations.delete.

Methods

Method	HTTP	Summary
automations.list	`GET /v1/automations`	List automations
automations.create	`POST /v1/automations`	Create an automation
automations.get	`GET /v1/automations/{automationId}`	Get an automation
automations.update	`PATCH /v1/automations/{automationId}`	Update an automation
automations.delete	`DELETE /v1/automations/{automationId}`	Delete an automation
automations.pause	`POST /v1/automations/{automationId}/pause`	Pause an automation
automations.resume	`POST /v1/automations/{automationId}/resume`	Resume an automation
automations.listRuns	`GET /v1/automations/{automationId}/runs`	List automation runs
automations.createRun	`POST /v1/automations/{automationId}/runs`	Start an automation run
automations.getRun	`GET /v1/automations/{automationId}/runs/{runId}`	Get an automation run
automations.createWebhook	`POST /v1/automations/webhooks`	Create a webhook automation

automations.list

GET /v1/automations · Operation ID listAutomations

List automations

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.list`	`list(query?: Models.ListAutomationsQuery): Promise<Models.ListAutomationsResponse>`
Python	`cloud.automations.list`	`def list(self, options: ListAutomationsOptions \| None = None) -> ListAutomationsResponse`
Go	`cloud.Automations.List`	`func (r *AutomationsResource) List(ctx context.Context, options ListAutomationsOptions) (ListAutomationsResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`status`	query	`string`	no	Return only automations in this state: `enabled`, `paused` or `expired`.
`cursor`	query	`string`	no	Cursor from `nextCursor` of the previous page. Omit it to get the first page.
`limit`	query	`integer`	no	Maximum number of automations to return in one page, 1 or more, up to the server maximum (at most 1000). Larger values are rejected with 400 `invalid_argument`. Defaults to 20.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	ProtoListAutomationsResponse	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.automations.list();
console.log(result);

automations.create

POST /v1/automations · Operation ID createAutomation

Create an automation

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.create`	`create(input: Models.ProtoAutomationInput): Promise<Models.CreateAutomationResponse>`
Python	`cloud.automations.create`	`def create(self, input: ProtoAutomationInput) -> CreateAutomationResponse`
Go	`cloud.Automations.Create`	`func (r *AutomationsResource) Create(ctx context.Context, input ProtoAutomationInput) (CreateAutomationResponse, error)`

Request body

application/json · required · Schema: ProtoAutomationInput

Field	Type	Required	Description
`name`	`string`	no	Display name of the automation, 1 to 256 characters and not blank.
`prompt`	`string`	no	Text sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to. Required.
`schedule`	ProtoAutomationSchedule	no	When the automation runs. Required.
`session`	ProtoAutomationSession	no	Not accepted by this API: a request that includes it fails with 400 `invalid_argument`. Automations created here open a new conversation for every run.
`validFrom`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound. It must not be after `validUntil`. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound. After it the automation becomes `expired`. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation is created from, if any. It must be a conversation of the same end user.

Response

201 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	ProtoAutomationRule	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.automations.create({});
console.log(result);

automations.get

GET /v1/automations/{automationId} · Operation ID getAutomation

Get an automation

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.get`	`get(automationId: string): Promise<Models.GetAutomationResponse>`
Python	`cloud.automations.get`	`def get(self, automation_id: str) -> GetAutomationResponse`
Go	`cloud.Automations.Get`	`func (r *AutomationsResource) Get(ctx context.Context, automationId string) (GetAutomationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	JSONValue	yes	A genuinely open JSON value (provider/plugin parameters or arbitrary metadata). Nullable.

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.automations.get("automation_123");
console.log(result);

automations.update

PATCH /v1/automations/{automationId} · Operation ID updateAutomation

Update an automation

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.update`	`update(automationId: string, input: Models.ProtoAutomationPatch): Promise<Models.UpdateAutomationResponse>`
Python	`cloud.automations.update`	`def update(self, automation_id: str, input: ProtoAutomationPatch) -> UpdateAutomationResponse`
Go	`cloud.Automations.Update`	`func (r *AutomationsResource) Update(ctx context.Context, automationId string, input ProtoAutomationPatch) (UpdateAutomationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.

Request body

application/json · required · Schema: ProtoAutomationPatch

Field	Type	Required	Description
`name`	`string`	no	New display name, 1 to 256 characters and not blank.
`prompt`	`string`	no	New prompt sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	New agent the prompt is sent to.
`schedule`	ProtoAutomationSchedule	no	New schedule. It replaces the whole schedule, so send every field the `kind` needs, including `anchorAt` for `every`.
`session`	ProtoAutomationSession	no	Not accepted by this API: a request that includes it fails with 400 `invalid_argument`.
`validFrom`	`string`	no	New earliest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidFrom`. Constraints: `format=date-time`.
`validUntil`	`string`	no	New latest time a run may start, as an RFC 3339 timestamp, inclusive. Cannot be combined with `clearValidUntil`. Constraints: `format=date-time`.
`clearValidFrom`	`boolean`	no	Set to true to remove the lower bound of the validity period. Cannot be combined with `validFrom`.
`clearValidUntil`	`boolean`	no	Set to true to remove the upper bound of the validity period. Cannot be combined with `validUntil`.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	ProtoAutomationRule	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.automations.update("automation_123", {});
console.log(result);

automations.delete

DELETE /v1/automations/{automationId} · Operation ID deleteAutomation

Delete an automation

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.delete`	`delete(automationId: string): Promise<Models.DeleteAutomationResponse>`
Python	`cloud.automations.delete`	`def delete(self, automation_id: str) -> None`
Go	`cloud.Automations.Delete`	`func (r *AutomationsResource) Delete(ctx context.Context, automationId string) error`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.

Response

204

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.automations.delete("automation_123");
console.log(result);

automations.pause

POST /v1/automations/{automationId}/pause · Operation ID pauseAutomation

Pause an automation

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.pause`	`pause(automationId: string): Promise<Models.PauseAutomationResponse>`
Python	`cloud.automations.pause`	`def pause(self, automation_id: str) -> PauseAutomationResponse`
Go	`cloud.Automations.Pause`	`func (r *AutomationsResource) Pause(ctx context.Context, automationId string) (PauseAutomationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	JSONValue	yes	A genuinely open JSON value (provider/plugin parameters or arbitrary metadata). Nullable.

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.automations.pause("automation_123");
console.log(result);

automations.resume

POST /v1/automations/{automationId}/resume · Operation ID resumeAutomation

Resume an automation

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.resume`	`resume(automationId: string): Promise<Models.ResumeAutomationResponse>`
Python	`cloud.automations.resume`	`def resume(self, automation_id: str) -> ResumeAutomationResponse`
Go	`cloud.Automations.Resume`	`func (r *AutomationsResource) Resume(ctx context.Context, automationId string) (ResumeAutomationResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	JSONValue	yes	A genuinely open JSON value (provider/plugin parameters or arbitrary metadata). Nullable.

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.automations.resume("automation_123");
console.log(result);

automations.listRuns

GET /v1/automations/{automationId}/runs · Operation ID listAutomationRuns

List automation runs

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.listRuns`	`listRuns(automationId: string, query?: Models.ListAutomationRunsQuery): Promise<Models.ListAutomationRunsResponse>`
Python	`cloud.automations.list_runs`	`def list_runs(self, automation_id: str, options: ListAutomationRunsOptions \| None = None) -> ListAutomationRunsResponse`
Go	`cloud.Automations.ListRuns`	`func (r *AutomationsResource) ListRuns(ctx context.Context, automationId string, options ListAutomationRunsOptions) (ListAutomationRunsResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.
`status`	query	`string`	no	Return only runs in this state: `scheduled`, `dispatched`, `failed` or `skipped`.
`cursor`	query	`string`	no	Cursor from `nextCursor` of the previous page. Omit it to get the first page.
`limit`	query	`integer`	no	Maximum number of runs to return in one page, 1 or more, up to the server maximum (at most 1000). Larger values are rejected with 400 `invalid_argument`. Defaults to 20.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	ProtoListAutomationRunsResponse	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.automations.listRuns("automation_123");
console.log(result);

automations.createRun

POST /v1/automations/{automationId}/runs · Operation ID createAutomationRun

Start an automation run

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.createRun`	`createRun(automationId: string, input: Models.ProtoAutomationRunInput, idempotencyKey: string): Promise<Models.CreateAutomationRunResponse>`
Python	`cloud.automations.create_run`	`def create_run(self, automation_id: str, input: ProtoAutomationRunInput, options: CreateAutomationRunOptions) -> CreateAutomationRunResponse`
Go	`cloud.Automations.CreateRun`	`func (r *AutomationsResource) CreateRun(ctx context.Context, automationId string, input ProtoAutomationRunInput, options CreateAutomationRunOptions) (CreateAutomationRunResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 1 to 128 bytes and not blank. Repeating a request with the same key and body returns the original run; reusing the key for a different request returns 409 `idempotency_conflict`.

Request body

application/json · required · Schema: ProtoAutomationRunInput

Field	Type	Required	Description
`sourceRunId`	`string`	no	ID of an earlier run of the same automation to repeat. Send it together with `rerunSessionMode`, or send neither for a plain manual run.
`rerunSessionMode`	`string`	no	Which conversation the rerun is delivered into. Required when `sourceRunId` is sent and not allowed without it. Allowed values: `"original"` — The conversation the source run was delivered into; `"new"` — A new conversation. (enum table)

Response

202 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	ProtoAutomationRun	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.automations.createRun("automation_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

automations.getRun

GET /v1/automations/{automationId}/runs/{runId} · Operation ID getAutomationRun

Get an automation run

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.getRun`	`getRun(automationId: string, runId: string): Promise<Models.GetAutomationRunResponse>`
Python	`cloud.automations.get_run`	`def get_run(self, automation_id: str, run_id: str) -> GetAutomationRunResponse`
Go	`cloud.Automations.GetRun`	`func (r *AutomationsResource) GetRun(ctx context.Context, automationId string, runId string) (GetAutomationRunResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`automationId`	path	`string`	yes	ID of the automation, the `id` returned when it was created.
`runId`	path	`string`	yes	ID of the run, the `id` returned when the run was created or listed.

Response

200 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	ProtoAutomationRun	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.automations.getRun("automation_123", "run_123");
console.log(result);

automations.createWebhook

POST /v1/automations/webhooks · Operation ID createWebhookAutomation

Create a webhook automation

SDK methods

Language	Method	Signature
TypeScript	`cloud.automations.createWebhook`	`createWebhook(input: Models.ProtoAutomationWebhookInput): Promise<Models.CreateWebhookAutomationResponse>`
Python	`cloud.automations.create_webhook`	`def create_webhook(self, input: ProtoAutomationWebhookInput) -> CreateWebhookAutomationResponse`
Go	`cloud.Automations.CreateWebhook`	`func (r *AutomationsResource) CreateWebhook(ctx context.Context, input ProtoAutomationWebhookInput) (CreateWebhookAutomationResponse, error)`

Request body

application/json · required · Schema: ProtoAutomationWebhookInput

Field	Type	Required	Description
`name`	`string`	no	Display name of the automation, 1 to 256 characters and not blank.
`prompt`	`string`	no	Text sent to the agent on every run, up to 65536 bytes and not blank.
`target`	ProtoAutomationTarget	no	Agent the prompt is sent to. Required.
`session`	ProtoAutomationSession	no	Not accepted by this API: a request that includes it fails with 400 `invalid_argument`. Automations created here open a new conversation for every run.
`validFrom`	`string`	no	Earliest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no lower bound. Constraints: `format=date-time`.
`validUntil`	`string`	no	Latest time a run may start, as an RFC 3339 timestamp, inclusive. Omit it for no upper bound. Constraints: `format=date-time`.
`createdInConversationId`	`string`	no	ID of the conversation the automation is created from, if any. It must be a conversation of the same end user.
`source`	`string`	no	Platform that sends the events, for example `github` or `gmail`, at most 64 characters without whitespace. The agent must have the matching connector set up. Required.
`events`	`array<string>`	no	Names of the events to subscribe to at the source, for example the GitHub event types the repository should deliver.
`repoOwner`	`string`	no	Owner of the repository to watch. Required when `source` is `github`.
`repoName`	`string`	no	Name of the repository to watch. Required when `source` is `github`.
`eventFilter`	`string`	no	Event type that starts a run. When set, only events of exactly this type start a run; others are skipped. Empty accepts every event.
`mailbox`	`string`	no	Gmail address to watch. Required when `source` is `gmail`; leave empty for other sources.

Response

201 · application/json

Field	Type	Required	Description
`success`	`boolean`	yes	—
`data`	ProtoAutomationRule	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.automations.createWebhook({});
console.log(result);

BeeOS CloudBack to documentation