files

Files are session scratch until published, then durable org artifacts — and, with a title and tags, the asset library an agent searches with find_files. Eight methods. API detail: Files.

upload

client.files.upload(form: FormData): Promise<File>

POST /v1/files, multipart/form-data — the one method in the client that does not send JSON. The file part carries the bytes; other parts are metadata:

const form = new FormData();
form.append("file", new Blob([bytes], { type: "application/pdf" }), "invoice.pdf");
form.append("title", "Invoice 4821");
form.append("tags", "finance,q3");
const file = await client.files.upload(form);

title, description and tags (comma-separated) are optional; the body is capped at 25 MiB. The stored file carries kind (derived from the content type), source: { type: "upload" } and, for an image, its width/height.

import

client.files.import(body: FileImport): Promise<File>

POST /v1/files/imports. The API fetches a public http(s) URL server-side and stores it as a published file with source.type: "url_import". The client sends the Idempotency-Key for you, so a retried call replays the same file.

const hero = await client.files.import({
  url: "https://cdn.example.com/hero.png",
  title: "Launch hero",
  tags: ["launch"],
});

string

required

Public http(s) URL; private and local hosts are refused.

string

A human title.

string

A longer, searchable description.

string[]

Labels to filter by.

list

client.files.list(query?: FileFilter): Promise<Page<File>>

GET /v1/files. FileFilter extends the page query with:

"session" | "published"

Only scratch, or only published artifacts.

string

Only files a given session produced.

FileKind

image, video, audio, document or other.

FileSourceType

Provenance — upload, url_import, image_generation, …

string

Only files carrying this tag.

string

Case-insensitive substring of the title, name or description.

const heroes = await client.files.list({ kind: "image", tag: "launch", search: "hero" });

get

client.files.get(id: string): Promise<File>

GET /v1/files/{id} — the metadata object.

update

client.files.update(id: string, body: FileUpdate): Promise<File>

PATCH /v1/files/{id}. Library metadata only — title, description (each a string, or null to clear) and tags (replaces the list). The bytes, name, scope and provenance never change.

await client.files.update(hero.id, { title: "Launch hero (final)", tags: ["launch", "approved"] });

download

client.files.download(id: string): Promise<string>

GET /v1/files/{id}?download=true — the bytes, as text, through the API. A download is authorized by the same key as every other read; there is no unauthenticated URL unless you publish.

publish

client.files.publish(id: string): Promise<File>

POST /v1/files/{id}/publish. The promotion boundary: session scratch becomes a durable org artifact. Idempotent — publishing twice is fine.

delete

client.files.delete(id: string): Promise<Deleted>

DELETE /v1/files/{id}.

TypeScript

Control plane

Resources

Identity & access

Automation

Account

upload

import

list

get

update

download

publish

delete

​upload

​import

​list

​get

​update

​download

​publish

​delete

upload

import

list

get

update

download

publish

delete