​

files

orc files filters Workspace files by purpose or owner, registers and retrieves metadata, and uploads file content. Manage Issue attachments, brand assets, knowledge-base documents, and other files by ID.

Authentication and a selected Workspace are required. create, which registers file metadata, is separate from content update, which sends the binary content. Use --file, not JSON --stdin, for binary uploads.

List knowledge-base documents in the Workspace.

Lists files filtered by purpose or owner. For Issue attachments, combine --owner-type issue with --owner-id. --order is asc or desc by creation time and ID; paginate with --limit and --cursor.

Include only files with this purpose. Omit for all purposes in the workspace.; enum: agent-context|brand-asset|chat-attachment|document|screenshot|export|profile-image|docs-asset|domain-favicon

Type: string. Optional.

Owner type for an ownership filter. Must be paired with one or
more repeated owner_id values. Issue attachments use issue.; enum: issue

Type: string. Optional.

Owner ID values for an ownership filter. Repeat this parameter
to return files owned by any of several issues in one read.; csv

Type: string. Optional.

Sort order by created_at, then id.; enum: asc|desc

Type: string. Optional.

Creates a file registration with purpose, filename, mime_type, and byte_size. You can also supply sha256, JSON metadata, and a structured owner_ref. Issue attachment ownership uses type issue and the Issue ID.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

(required) File usage category. Determines applicable upload policy. Use document for a general document or chat-attachment for an attachment.; enum: agent-context|brand-asset|chat-attachment|document|screenshot|export|profile-image|docs-asset|domain-favicon

Type: string. Optional.

(required) Display filename. Leading and trailing whitespace is removed; the result must not be empty.

Type: string. Optional.

(required) MIME type of the binary content, such as text/plain. Accepted types depend on purpose.

Type: string. Optional.

(required) Expected binary content size in bytes. Must be a non-negative integer; purpose-specific size limits also apply.

Type: number. Optional.

Optional 64-character hexadecimal hash for workspace-scoped deduplication. Normalized to lowercase. Omit to register a new storage key.

Type: string. Optional.

Optional caller-defined metadata object. Defaults to {}.; (JSON object, e.g. '{"custom_id":"x"}')

Type: string. Optional.

Optional ownership reference. Issue attachments must use
{ "type": "issue", "id": "<issue id>" }.

Type: string. Optional.

Retrieves metadata by file ID. This is separate from retrieving binary content.

Calls the content retrieval API for a file ID. The current CLI response handling passes through text, so do not use it to preserve original binary files such as images.

Uploads binary content using a file ID and a local path in --file. --file is required, and combining it with --stdin is rejected.

Path to the local file to upload as binary content

Type: string. Required.

Inspect metadata for a file ID.

Upload local content to a registered file.

The following global options can be used with orc files:

For details and examples, see global options.