Responses

Overview

The responses domain runs a task on a configured harness and reads it back (UHP). With stream: false the server returns one Response object when the task reaches a terminal state; with stream: true it returns a text/event-stream of events.

6 operations · SDK resource: TypeScript cloud.responses · Python cloud.responses · Go cloud.Responses · API overview

Operations whose path starts with /uhp/v1 are served from https://api.cloud.beeos.ai/uhp/v1 instead of https://api.cloud.beeos.ai/v1; the SDKs switch automatically.

Main objects

• UHPCreateResponseRequest: the task to run (input, model, metadata, and options).
• UHPResponse: the task with its output items and usage; its state is UHPResponseStatus.
• UHPEvent: one event of a streamed response.

UHPCreateResponseRequest

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

UHPResponse

UHPResponseStatus values

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

UHPEvent

One streamed event. sequence_number starts at 0 and increases by exactly 1 per event, so a client can detect a dropped event rather than silently rendering a gap.

UHPEvent.type values

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

UHPOutputItem

A client must tolerate item types it does not recognise. A client that renders only message items and ignores the rest is a valid client.

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

UHPContentPart

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

UHPAnnotation

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

Typical flow

1. Run a task with responses.create; retries must carry the same Idempotency-Key.
2. Read the task back with responses.get, or follow or resume its events with responses.getEvents.
3. Stop a running task with responses.cancel; cancelling a task that already ended succeeds and changes nothing.
4. Read the original input with responses.getInputItems.
5. Remove the stored response with responses.delete; deleting does not cancel a running task.

Methods

responses.create

POST /uhp/v1/responses · Operation ID createResponse

Run a task

The core of the protocol. With stream: false the server returns one Response object when the task reaches a terminal state. With stream: true it returns text/event-stream carrying the events defined in the Streaming chapter. Retries MUST carry Idempotency-Key: without one, a retry after a timeout runs the task a second time while the first may still be running.

SDK methods

cloud.responses.createStream: Creates a Response with stream: true and returns the server-sent events as an async iterable. The method spreads input and forces stream: true before calling POST /responses with responseType: "sse".

cloud.responses.create_stream: Creates a Response with stream: True and yields the server-sent events as decoded JSON values. It copies input, forces stream to True, and posts to /responses; options are sent as headers unchanged.

cloud.Responses.CreateStream: Creates a Response with stream forced to true and returns an *UHPEventStream. Read events with Next() until it returns io.EOF, and call Close() when done. options are sent as headers.

Parameters

Request body

application/json · required · Schema: UHPCreateResponseRequest

Response

200 The finished Response (non-streaming), or the event stream (streaming). · application/json · Schema: UHPResponse

stream=true returns text/event-stream; stream=false returns UHPResponse

Errors

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.responses.create({ input: "example_input" });
console.log(result);

responses.get

GET /uhp/v1/responses/{response_id} · Operation ID getResponse

Read a task back

SDK methods

Parameters

Response

200 The Response · application/json · Schema: UHPResponse

Errors

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

responses.delete

DELETE /uhp/v1/responses/{response_id} · Operation ID deleteResponse

Delete a stored response

Must not cancel a running task — deletion and cancellation are different intentions.

SDK methods

Parameters

Response

200 Deleted · application/json

Errors

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

responses.cancel

POST /uhp/v1/responses/{response_id}/cancel · Operation ID cancelResponse

Cancel a running task

Idempotent. Cancelling an already-terminal task succeeds and changes nothing — a client retrying a cancel after a dropped connection must not be punished for having succeeded.

SDK methods

Parameters

Response

200 The Response, now cancelling or terminal · application/json · Schema: UHPResponse

Errors

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.responses.cancel("response_123");
console.log(result);

responses.getEvents

GET /uhp/v1/responses/{response_id}/events · Operation ID getResponseEvents

Stream or resume the events of a response

SDK methods

Parameters

Response

200 Server-sent protocol events · text/event-stream · Schema: UHPEvent

Streams server-sent events.

Errors

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 stream = await cloud.responses.getEvents("response_123");
for await (const event of stream) {
  console.log(event);
}

responses.getInputItems

GET /uhp/v1/responses/{response_id}/input_items · Operation ID getResponseInputItems

The input the task was created with

SDK methods

Parameters

Response

200 Input items · application/json

Errors

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.responses.getInputItems("response_123");
console.log(result);

Structures by discriminator

UHPContentPart by type

The structure of UHPContentPart depends on its own type value.

UHPEvent by type

The structure of UHPEvent depends on its own type value.

UHPOutputItem by type

The structure of UHPOutputItem depends on its own type value.