BEEOS CLOUD / DEVELOPER REFERENCE

Files

Presigned uploads, file metadata, share links, and the file summary.

Overview

The files domain stores and shares files: it prepares presigned uploads, confirms them, lists and reads file metadata, renames and deletes files, manages file share links, and returns a file summary.

11 operations · SDK resource: TypeScript cloud.files · Python cloud.files · Go cloud.Files · API overview

Main objects

FilePrepareUploadInput and FileTransferDescriptor: the upload request and the descriptor you transfer the file with.
FileConfirmInput and FileFile: the confirmation and the stored file.
FilePage, FileResolution, and FileSummary: listings, a resolved file, and the summary.
FileShareResponse: a share link.

FilePrepareUploadInput

Field	Type	Required	Description
`upload_context`	FileChatUploadContext	no	Ties the upload to an instance and optionally an agent. The credential's organization and app own the file. Omit the context for a plain upload. Nullable.
`filename`	`string`	yes	Name of the file, 1 to 255 characters, without leading or trailing whitespace and without `/`, `\` or control characters.
`content_type`	`string`	yes	MIME type of the file, at most 255 characters and without control characters. The uploaded content must carry this type.
`size_bytes`	`integer`	yes	Size of the file in bytes, from 1 to 104857600 (100 MiB). The uploaded content must have exactly this size.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the content (64 characters). Optional. When sent, the uploaded content must match it and the confirmation verifies it.

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

FileTransferDescriptor

Field	Type	Required	Description
`direction`	`string`	yes	Whether the URL is used to upload or to download the file content. Allowed values: `"upload"` — Send the file content to `url` with `http_method`. Returned when an upload is prepared; `"download"` — Fetch the file content from `url` with `http_method`. Returned when a file or a share is read. (enum table)
`file_id`	`string`	yes	ID of the file the transfer is for.
`url`	`string`	yes	Pre-signed URL to transfer the file content with. The URL is already signed, so do not send your API key to it.
`http_method`	`string`	yes	HTTP method to use with `url`: `PUT` for an upload, `GET` for a download.
`required_headers`	`map<string, string>`	yes	Headers to send with the transfer request exactly as given. Empty when none are required.
`expires_at`	`string`	yes	Time the URL stops working, as an RFC 3339 timestamp. Upload URLs are valid for 15 minutes and download URLs for 5 minutes. Constraints: `format=date-time`.
`content_type`	`string`	yes	MIME type of the file.
`size_bytes`	`integer`	yes	Size of the file in bytes.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the file content. Omitted when no digest is known.

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

FileConfirmInput

Field	Type	Required	Description
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the uploaded content (64 characters). Optional. When sent, it is compared with the digest of the stored object and a difference fails the confirmation with 409 `checksum_mismatch`.

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

FileFile

Field	Type	Required	Description
`file_id`	`string`	yes	Unique ID of the file.
`filename`	`string`	yes	Name of the file, without a path.
`content_type`	`string`	yes	MIME type of the file, for example image/png.
`size_bytes`	`integer`	yes	Size of the file in bytes.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the file content. Empty when no checksum was supplied at upload and none was recorded for the object.
`status`	`string`	yes	Upload state of the file. Deleted files are never returned. New states can be added, so ignore values you do not know. Allowed values: `"pending_upload"` — The upload was prepared but not confirmed yet. The file has no content to download; `"ready"` — The upload was confirmed. The file can be downloaded, renamed, shared and deleted. (enum table)
`resource_version`	`integer`	yes	Version of the file record. It starts at 1 and increases when the upload is confirmed and when the file is renamed or deleted.
`updated_at`	`string`	yes	Time the file was last changed: created, confirmed or renamed, whichever is latest. RFC 3339 timestamp. Constraints: `format=date-time`.
`title`	`string`	no	Title read from the document's own metadata. It is extracted for PDF, docx, xlsx and pptx files of up to 8 MiB the first time the file is read by ID, and omitted when the document has no usable title.
`file_type`	`string`	yes	Category of the file, derived from its MIME type and, for generic types such as `application/octet-stream`, from its extension. Allowed values: see the table below, FileFile.file_type values.
`created_at`	`string`	yes	Time the file record was created, when the upload was prepared. RFC 3339 timestamp. Constraints: `format=date-time`.
`confirmed_at`	`string`	no	Time the upload was confirmed. Omitted until the file is ready. RFC 3339 timestamp. Nullable. Constraints: `format=date-time`.
`origin`	FileOrigin	no	Where the file came from, with the instance and agent it belongs to. Nullable.

FileFile.file_type values

Value	Meaning
`"FILE_TYPE_IMAGE"`	An image, for example PNG, JPEG, GIF, WebP or SVG.
`"FILE_TYPE_VIDEO"`	A video, for example MP4, MOV or WebM.
`"FILE_TYPE_AUDIO"`	An audio file, for example MP3, WAV or FLAC.
`"FILE_TYPE_DOCUMENT"`	A text or office document, for example plain text, Markdown, JSON, PDF, Word, Excel, PowerPoint or OpenDocument.
`"FILE_TYPE_ARCHIVE"`	A compressed or packed archive, for example ZIP, TAR, GZIP, 7z or RAR.
`"FILE_TYPE_OTHER"`	Any other file.

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

FilePage

Field	Type	Required	Description
`data`	array<FileFile>	yes	Files on this page.
`total`	`integer`	yes	Number of files that match the query, across all pages.
`next_since`	`string`	no	Cursor to pass as `since` to get the next page. Returned only by the default chronological listing, and only when more files follow. Filtered or sorted listings page with `offset` instead.

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

FileResolution

Field	Type	Required	Description
`file`	FileFile	yes	The file.
`download`	FileTransferDescriptor	yes	Pre-signed descriptor to download the content with. While the file is still `pending_upload` it carries no usable URL.

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

FileSummary

Field	Type	Required	Description
`file_count`	`integer`	yes	Number of ready files.
`storage_file_count`	`integer`	yes	Number of ready files that count toward storage. Files provided by template skills are not counted.
`used_bytes`	`integer`	yes	Total size in bytes of the files that count toward storage.
`image_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_IMAGE` category.
`video_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_VIDEO` category.
`document_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_DOCUMENT` category.
`instances`	`array<object>`	yes	Ready files grouped by the agent they belong to, or by instance when they have no agent, largest group first.
`instances[].source`	`string`	yes	How the file came to exist. New values can be added, so ignore values you do not know. Allowed values: `"manual"` — Uploaded directly through the files API without an upload context. Files without a recorded origin are reported as `manual`; `"chat_upload"` — Uploaded with an `upload_context`, to be used in a conversation with the agent named by it; `"runtime_generated"` — Generated by an agent while it handled a request. `operation_id` identifies that operation; `"template_skill"` — Provided by a template skill. The file is read-only: it cannot be renamed or deleted, and it does not count toward storage usage. (enum table)
`instances[].instance_id`	`string`	no	ID of the instance the file belongs to. Omitted for files that are not tied to an instance.
`instances[].agent_id`	`string`	no	ID of the agent the file belongs to. Omitted for files that are not tied to an agent.
`instances[].operation_id`	`string`	no	ID of the agent operation that generated the file. Set only when `source` is `runtime_generated`.
`instances[].instance_name`	`string`	no	Current display name of the instance, filled in when the file is returned. Omitted for files without an instance.
`instances[].agent_name`	`string`	no	Current display name of the agent, filled in when the file is returned. Omitted for files without an agent.
`instances[].avatar_url`	`string`	no	URL of the agent avatar. Omitted for files without an agent.
`instances[].harness`	`string`	no	Harness the instance runs, for example `openclaw`. Omitted for files without an instance.
`instances[].destroyed`	`boolean`	no	True when the instance has been terminated or deleted. The file stays available. Omitted when false.
`instances[].count`	`integer`	yes	Number of ready files in this group.

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

FileShareResponse

Field	Type	Required	Description
`file_id`	`string`	yes	ID of the shared file.
`slug`	`string`	yes	Public slug of the share. Pass it to the resolve-share operation to get the file.
`filename`	`string`	yes	Current name of the shared file.
`content_type`	`string`	yes	MIME type of the shared file.
`size_bytes`	`integer`	yes	Size of the shared file in bytes.
`revoked`	`boolean`	yes	True when the share was revoked. A revoked share can no longer be resolved. Creating the share again turns it back on.

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

Typical flow

Ask for an upload with files.prepareUpload and transfer the file's bytes with the returned descriptor.
Confirm it with files.confirmUpload.
Find files with files.list and files.get; rename with files.rename; remove with files.delete.
Share a file with files.createShare and read the link with files.getShare; anyone with the slug opens it through files.resolveShare; withdraw it with files.revokeShare.
files.getSummary returns the overall file summary.

Methods

Method	HTTP	Summary
files.resolveShare	`GET /v1/file-shares/{slug}`	Resolve a file share link
files.list	`GET /v1/files`	List files
files.get	`GET /v1/files/{fileId}`	Get a file
files.rename	`PATCH /v1/files/{fileId}`	Rename a file
files.delete	`DELETE /v1/files/{fileId}`	Delete a file
files.confirmUpload	`POST /v1/files/{fileId}/confirm`	Confirm a file upload
files.getShare	`GET /v1/files/{fileId}/share`	Get a file share link
files.createShare	`POST /v1/files/{fileId}/share`	Create a file share link
files.revokeShare	`DELETE /v1/files/{fileId}/share`	Revoke a file share link
files.prepareUpload	`POST /v1/files/presign-upload`	Create a file upload URL
files.getSummary	`GET /v1/files/summary`	Get the file summary

files.resolveShare

GET /v1/file-shares/{slug} · Operation ID resolveFileShare

Resolve a file share link

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.resolveShare`	`resolveShare(slug: string): Promise<Models.ResolveFileShareResponse>`
Python	`cloud.files.resolve_share`	`def resolve_share(self, slug: str) -> ResolveFileShareResponse`
Go	`cloud.Files.ResolveShare`	`func (r *FilesResource) ResolveShare(ctx context.Context, slug string) (ResolveFileShareResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`slug`	path	`string`	yes	Public slug of the file share, the `slug` returned when the share was created.

Response

200 · application/json

Field	Type	Required	Description
`file_id`	`string`	yes	—
`slug`	`string`	yes	—
`filename`	`string`	yes	—
`content_type`	`string`	yes	—
`size_bytes`	`integer`	yes	—
`download`	FileTransferDescriptor	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.files.resolveShare("share_slug");
console.log(result);

files.list

GET /v1/files · Operation ID listFiles

List files

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.list`	`list(query?: Models.ListFilesQuery): Promise<Models.ListFilesResponse>`
Python	`cloud.files.list`	`def list(self, options: ListFilesOptions \| None = None) -> FilePage`
Go	`cloud.Files.List`	`func (r *FilesResource) List(ctx context.Context, options ListFilesOptions) (FilePage, error)`

Parameters

Parameter	In	Type	Required	Description
`content_type`	query	`string`	no	Return only files with exactly this MIME type, at most 255 characters.
`since`	query	`string`	no	Cursor from `next_since` of the previous page. Omit it to start at the oldest file. It applies only to the default chronological listing, that is when none of `status`, `file_type`, `category`, `source`, `q`, `instance_id`, `agent_id`, `sort`, `sort_dir` and `offset` is set. At most 2048 characters.
`status`	query	`string`	no	Return only files in this state: `ready` or `pending_upload`. When omitted, files in both states are returned.
`file_type`	query	`string`	no	Return only files in this category: `FILE_TYPE_IMAGE`, `FILE_TYPE_VIDEO`, `FILE_TYPE_AUDIO`, `FILE_TYPE_DOCUMENT`, `FILE_TYPE_ARCHIVE` or `FILE_TYPE_OTHER`.
`category`	query	`string`	no	Return only files in a broad category: `image`, `video`, `document` or `other`. `other` covers every file that is not an image, a video or a document, including audio and archives.
`source`	query	`string`	no	Return only files with this origin: `manual`, `chat_upload`, `runtime_generated` or `template_skill`. Files without a recorded origin count as `manual`.
`q`	query	`string`	no	Return only files whose name contains this text, compared case-insensitively.
`instance_id`	query	`string`	no	Return only files that belong to this instance.
`agent_id`	query	`string`	no	Return only files that belong to this agent.
`sort`	query	`string`	no	Field to sort by: `created_at` (the default), `updated_at`, `file_name` or `size_bytes`. Ties are ordered by file ID. Any sort, filter or `offset` switches the listing to offset paging.
`sort_dir`	query	`string`	no	Sort direction: `asc` or `desc`. When sorting or filtering the default is `desc`; the default chronological listing is oldest first.
`limit`	query	`integer`	no	Maximum number of files to return, from 0 to 200. Defaults to 50.
`offset`	query	`integer`	no	Number of matching files to skip, 0 or more. Setting it switches the listing to offset paging.

Response

200 · application/json · Schema: FilePage

Field	Type	Required	Description
`data`	array<FileFile>	yes	Files on this page.
`total`	`integer`	yes	Number of files that match the query, across all pages.
`next_since`	`string`	no	Cursor to pass as `since` to get the next page. Returned only by the default chronological listing, and only when more files follow. Filtered or sorted listings page with `offset` instead.

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.files.list();
console.log(result);

files.get

GET /v1/files/{fileId} · Operation ID getFile

Get a file

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.get`	`get(fileId: string): Promise<Models.GetFileResponse>`
TypeScript	`cloud.files.resolveDownload`	`resolveDownload(fileId: string)`
TypeScript	`cloud.files.download`	`download(fileId: string)`
Python	`cloud.files.get`	`def get(self, file_id: str) -> FileResolution`
Go	`cloud.Files.Get`	`func (r *FilesResource) Get(ctx context.Context, fileId string) (FileResolution, error)`

cloud.files.resolveDownload: Calls GET /files/{fileId} through the untyped client.request; the declared return type is inferred as Promise<JSONValue>. Use files.get for the typed result.

cloud.files.download: Alias of files.resolveDownload(fileId); the declared return type is inferred as Promise<JSONValue>.

Parameters

Parameter	In	Type	Required	Description
`fileId`	path	`string`	yes	ID of the file, the `file_id` returned when the upload was prepared.

Response

200 · application/json · Schema: FileResolution

Field	Type	Required	Description
`file`	FileFile	yes	The file.
`download`	FileTransferDescriptor	yes	Pre-signed descriptor to download the content with. While the file is still `pending_upload` it carries no usable URL.

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

files.rename

PATCH /v1/files/{fileId} · Operation ID renameFile

Rename a file

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.rename`	`rename(fileId: string, input: Models.RenameFileRequest): Promise<Models.RenameFileResponse>`
Python	`cloud.files.rename`	`def rename(self, file_id: str, input: RenameFileRequest) -> FileFile`
Go	`cloud.Files.Rename`	`func (r *FilesResource) Rename(ctx context.Context, fileId string, input RenameFileRequest) (FileFile, error)`

Parameters

Parameter	In	Type	Required	Description
`fileId`	path	`string`	yes	ID of the file, the `file_id` returned when the upload was prepared.

Request body

application/json · required

Field	Type	Required	Description
`title`	`string`	yes	New name of the file, 1 to 255 characters, without leading or trailing whitespace and without `/`, `\` or control characters.

Response

200 · application/json · Schema: FileFile

Field	Type	Required	Description
`file_id`	`string`	yes	Unique ID of the file.
`filename`	`string`	yes	Name of the file, without a path.
`content_type`	`string`	yes	MIME type of the file, for example image/png.
`size_bytes`	`integer`	yes	Size of the file in bytes.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the file content. Empty when no checksum was supplied at upload and none was recorded for the object.
`status`	`string`	yes	Upload state of the file. Deleted files are never returned. New states can be added, so ignore values you do not know. Allowed values: `"pending_upload"` — The upload was prepared but not confirmed yet. The file has no content to download; `"ready"` — The upload was confirmed. The file can be downloaded, renamed, shared and deleted. (enum table)
`resource_version`	`integer`	yes	Version of the file record. It starts at 1 and increases when the upload is confirmed and when the file is renamed or deleted.
`updated_at`	`string`	yes	Time the file was last changed: created, confirmed or renamed, whichever is latest. RFC 3339 timestamp. Constraints: `format=date-time`.
`title`	`string`	no	Title read from the document's own metadata. It is extracted for PDF, docx, xlsx and pptx files of up to 8 MiB the first time the file is read by ID, and omitted when the document has no usable title.
`file_type`	`string`	yes	Category of the file, derived from its MIME type and, for generic types such as `application/octet-stream`, from its extension. Allowed values: see FileFile.file_type values.
`created_at`	`string`	yes	Time the file record was created, when the upload was prepared. RFC 3339 timestamp. Constraints: `format=date-time`.
`confirmed_at`	`string`	no	Time the upload was confirmed. Omitted until the file is ready. RFC 3339 timestamp. Nullable. Constraints: `format=date-time`.
`origin`	FileOrigin	no	Where the file came from, with the instance and agent it belongs to. 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.files.rename("file_123", { title: "example_title" });
console.log(result);

files.delete

DELETE /v1/files/{fileId} · Operation ID deleteFile

Delete a file

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.delete`	`delete(fileId: string, idempotencyKey: string): Promise<Models.DeleteFileResponse>`
Python	`cloud.files.delete`	`def delete(self, file_id: str, options: DeleteFileOptions) -> None`
Go	`cloud.Files.Delete`	`func (r *FilesResource) Delete(ctx context.Context, fileId string, options DeleteFileOptions) error`

Parameters

Parameter	In	Type	Required	Description
`fileId`	path	`string`	yes	ID of the file, the `file_id` returned when the upload was prepared.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.

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.files.delete("file_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.confirmUpload

POST /v1/files/{fileId}/confirm · Operation ID confirmFileUpload

Confirm a file upload

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.confirmUpload`	`confirmUpload(fileId: string, input: Models.FileConfirmInput, idempotencyKey: string): Promise<Models.ConfirmFileUploadResponse>`
Python	`cloud.files.confirm_upload`	`def confirm_upload(self, file_id: str, input: FileConfirmInput, options: ConfirmFileUploadOptions) -> FileFile`
Go	`cloud.Files.ConfirmUpload`	`func (r *FilesResource) ConfirmUpload(ctx context.Context, fileId string, input FileConfirmInput, options ConfirmFileUploadOptions) (FileFile, error)`

Parameters

Parameter	In	Type	Required	Description
`fileId`	path	`string`	yes	ID of the file, the `file_id` returned when the upload was prepared.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.

Request body

application/json · required · Schema: FileConfirmInput

Field	Type	Required	Description
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the uploaded content (64 characters). Optional. When sent, it is compared with the digest of the stored object and a difference fails the confirmation with 409 `checksum_mismatch`.

Response

200 · application/json · Schema: FileFile

Field	Type	Required	Description
`file_id`	`string`	yes	Unique ID of the file.
`filename`	`string`	yes	Name of the file, without a path.
`content_type`	`string`	yes	MIME type of the file, for example image/png.
`size_bytes`	`integer`	yes	Size of the file in bytes.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the file content. Empty when no checksum was supplied at upload and none was recorded for the object.
`status`	`string`	yes	Upload state of the file. Deleted files are never returned. New states can be added, so ignore values you do not know. Allowed values: `"pending_upload"` — The upload was prepared but not confirmed yet. The file has no content to download; `"ready"` — The upload was confirmed. The file can be downloaded, renamed, shared and deleted. (enum table)
`resource_version`	`integer`	yes	Version of the file record. It starts at 1 and increases when the upload is confirmed and when the file is renamed or deleted.
`updated_at`	`string`	yes	Time the file was last changed: created, confirmed or renamed, whichever is latest. RFC 3339 timestamp. Constraints: `format=date-time`.
`title`	`string`	no	Title read from the document's own metadata. It is extracted for PDF, docx, xlsx and pptx files of up to 8 MiB the first time the file is read by ID, and omitted when the document has no usable title.
`file_type`	`string`	yes	Category of the file, derived from its MIME type and, for generic types such as `application/octet-stream`, from its extension. Allowed values: see FileFile.file_type values.
`created_at`	`string`	yes	Time the file record was created, when the upload was prepared. RFC 3339 timestamp. Constraints: `format=date-time`.
`confirmed_at`	`string`	no	Time the upload was confirmed. Omitted until the file is ready. RFC 3339 timestamp. Nullable. Constraints: `format=date-time`.
`origin`	FileOrigin	no	Where the file came from, with the instance and agent it belongs to. 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.files.confirmUpload("file_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.getShare

GET /v1/files/{fileId}/share · Operation ID getShareFileShare

Get a file share link

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.getShare`	`getShare(fileId: string): Promise<Models.GetShareFileShareResponse>`
Python	`cloud.files.get_share`	`def get_share(self, file_id: str) -> FileShareResponse`
Go	`cloud.Files.GetShare`	`func (r *FilesResource) GetShare(ctx context.Context, fileId string) (FileShareResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`fileId`	path	`string`	yes	ID of the file, the `file_id` returned when the upload was prepared.

Response

200 · application/json · Schema: FileShareResponse

Field	Type	Required	Description
`file_id`	`string`	yes	ID of the shared file.
`slug`	`string`	yes	Public slug of the share. Pass it to the resolve-share operation to get the file.
`filename`	`string`	yes	Current name of the shared file.
`content_type`	`string`	yes	MIME type of the shared file.
`size_bytes`	`integer`	yes	Size of the shared file in bytes.
`revoked`	`boolean`	yes	True when the share was revoked. A revoked share can no longer be resolved. Creating the share again turns it back on.

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.files.getShare("file_123");
console.log(result);

files.createShare

POST /v1/files/{fileId}/share · Operation ID createShareFileShare

Create a file share link

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.createShare`	`createShare(fileId: string, idempotencyKey: string): Promise<Models.CreateShareFileShareResponse>`
Python	`cloud.files.create_share`	`def create_share(self, file_id: str, options: CreateShareFileShareOptions) -> FileShareResponse`
Go	`cloud.Files.CreateShare`	`func (r *FilesResource) CreateShare(ctx context.Context, fileId string, options CreateShareFileShareOptions) (FileShareResponse, error)`

Parameters

Parameter	In	Type	Required	Description
`fileId`	path	`string`	yes	ID of the file, the `file_id` returned when the upload was prepared.
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.

Response

200 · application/json · Schema: FileShareResponse

Field	Type	Required	Description
`file_id`	`string`	yes	ID of the shared file.
`slug`	`string`	yes	Public slug of the share. Pass it to the resolve-share operation to get the file.
`filename`	`string`	yes	Current name of the shared file.
`content_type`	`string`	yes	MIME type of the shared file.
`size_bytes`	`integer`	yes	Size of the shared file in bytes.
`revoked`	`boolean`	yes	True when the share was revoked. A revoked share can no longer be resolved. Creating the share again turns it back on.

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.files.createShare("file_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.revokeShare

DELETE /v1/files/{fileId}/share · Operation ID revokeShareFileShare

Revoke a file share link

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.revokeShare`	`revokeShare(fileId: string): Promise<Models.RevokeShareFileShareResponse>`
Python	`cloud.files.revoke_share`	`def revoke_share(self, file_id: str) -> None`
Go	`cloud.Files.RevokeShare`	`func (r *FilesResource) RevokeShare(ctx context.Context, fileId string) error`

Parameters

Parameter	In	Type	Required	Description
`fileId`	path	`string`	yes	ID of the file, the `file_id` returned when the upload was prepared.

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.files.revokeShare("file_123");
console.log(result);

files.prepareUpload

POST /v1/files/presign-upload · Operation ID presignFileUpload

Create a file upload URL

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.prepareUpload`	`prepareUpload(input: Models.FilePrepareUploadInput, idempotencyKey: string): Promise<Models.PresignFileUploadResponse>`
TypeScript	`cloud.files.upload`	`upload(input: Models.FilePrepareUploadInput, idempotencyKey: string)`
Python	`cloud.files.prepare_upload`	`def prepare_upload(self, input: FilePrepareUploadInput, options: PresignFileUploadOptions) -> FileTransferDescriptor`
Go	`cloud.Files.PrepareUpload`	`func (r *FilesResource) PrepareUpload(ctx context.Context, input FilePrepareUploadInput, options PresignFileUploadOptions) (FileTransferDescriptor, error)`

cloud.files.upload: Alias of files.prepareUpload(input, idempotencyKey): returns the presigned upload descriptor. The SDK does not transfer the file bytes; upload to the returned URL, then call files.confirmUpload.

Parameters

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	`string`	yes	Key that makes the request safe to retry, 8 to 128 characters without leading or trailing whitespace. Repeating a request with the same key and parameters replays the original result; reusing the key for a different request returns 409 `idempotency_conflict`.

Request body

application/json · required · Schema: FilePrepareUploadInput

Field	Type	Required	Description
`upload_context`	FileChatUploadContext	no	Ties the upload to an instance and optionally an agent. The credential's organization and app own the file. Omit the context for a plain upload. Nullable.
`filename`	`string`	yes	Name of the file, 1 to 255 characters, without leading or trailing whitespace and without `/`, `\` or control characters.
`content_type`	`string`	yes	MIME type of the file, at most 255 characters and without control characters. The uploaded content must carry this type.
`size_bytes`	`integer`	yes	Size of the file in bytes, from 1 to 104857600 (100 MiB). The uploaded content must have exactly this size.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the content (64 characters). Optional. When sent, the uploaded content must match it and the confirmation verifies it.

Response

201 · application/json · Schema: FileTransferDescriptor

Field	Type	Required	Description
`direction`	`string`	yes	Whether the URL is used to upload or to download the file content. Allowed values: `"upload"` — Send the file content to `url` with `http_method`. Returned when an upload is prepared; `"download"` — Fetch the file content from `url` with `http_method`. Returned when a file or a share is read. (enum table)
`file_id`	`string`	yes	ID of the file the transfer is for.
`url`	`string`	yes	Pre-signed URL to transfer the file content with. The URL is already signed, so do not send your API key to it.
`http_method`	`string`	yes	HTTP method to use with `url`: `PUT` for an upload, `GET` for a download.
`required_headers`	`map<string, string>`	yes	Headers to send with the transfer request exactly as given. Empty when none are required.
`expires_at`	`string`	yes	Time the URL stops working, as an RFC 3339 timestamp. Upload URLs are valid for 15 minutes and download URLs for 5 minutes. Constraints: `format=date-time`.
`content_type`	`string`	yes	MIME type of the file.
`size_bytes`	`integer`	yes	Size of the file in bytes.
`checksum_sha256`	`string`	no	Lowercase hex SHA-256 digest of the file content. Omitted when no digest is known.

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.files.prepareUpload({
  filename: "example_filename",
  content_type: "example_content_type",
  size_bytes: 1
}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.getSummary

GET /v1/files/summary · Operation ID getFilesSummary

Get the file summary

SDK methods

Language	Method	Signature
TypeScript	`cloud.files.getSummary`	`getSummary(): Promise<Models.GetFilesSummaryResponse>`
Python	`cloud.files.get_summary`	`def get_summary(self) -> FileSummary`
Go	`cloud.Files.GetSummary`	`func (r *FilesResource) GetSummary(ctx context.Context) (FileSummary, error)`

Response

200 · application/json · Schema: FileSummary

Field	Type	Required	Description
`file_count`	`integer`	yes	Number of ready files.
`storage_file_count`	`integer`	yes	Number of ready files that count toward storage. Files provided by template skills are not counted.
`used_bytes`	`integer`	yes	Total size in bytes of the files that count toward storage.
`image_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_IMAGE` category.
`video_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_VIDEO` category.
`document_count`	`integer`	yes	Number of ready files in the `FILE_TYPE_DOCUMENT` category.
`instances`	`array<object>`	yes	Ready files grouped by the agent they belong to, or by instance when they have no agent, largest group first.
`instances[].source`	`string`	yes	How the file came to exist. New values can be added, so ignore values you do not know. Allowed values: `"manual"` — Uploaded directly through the files API without an upload context. Files without a recorded origin are reported as `manual`; `"chat_upload"` — Uploaded with an `upload_context`, to be used in a conversation with the agent named by it; `"runtime_generated"` — Generated by an agent while it handled a request. `operation_id` identifies that operation; `"template_skill"` — Provided by a template skill. The file is read-only: it cannot be renamed or deleted, and it does not count toward storage usage. (enum table)
`instances[].instance_id`	`string`	no	ID of the instance the file belongs to. Omitted for files that are not tied to an instance.
`instances[].agent_id`	`string`	no	ID of the agent the file belongs to. Omitted for files that are not tied to an agent.
`instances[].operation_id`	`string`	no	ID of the agent operation that generated the file. Set only when `source` is `runtime_generated`.
`instances[].instance_name`	`string`	no	Current display name of the instance, filled in when the file is returned. Omitted for files without an instance.
`instances[].agent_name`	`string`	no	Current display name of the agent, filled in when the file is returned. Omitted for files without an agent.
`instances[].avatar_url`	`string`	no	URL of the agent avatar. Omitted for files without an agent.
`instances[].harness`	`string`	no	Harness the instance runs, for example `openclaw`. Omitted for files without an instance.
`instances[].destroyed`	`boolean`	no	True when the instance has been terminated or deleted. The file stays available. Omitted when false.
`instances[].count`	`integer`	yes	Number of ready files in this group.

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.files.getSummary();
console.log(result);

BeeOS CloudBack to documentation