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. Nine methods here. 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.

createUpload

client.files.createUpload(body: { name: string; content_type: string; size_bytes: number }): Promise<FileUploadTicket>

POST /v1/files/uploads. A one-shot link for up to 60 MiB: PUT the bytes to upload_url within 15 minutes, with the same Content-Type and a Content-Length of exactly size_bytes. The PUT needs no key, so a browser can send the bytes straight to it. Its answer is the published file, with the id file_id already named.

const ticket = await client.files.createUpload({ name: "clip.mp4", content_type: "video/mp4", size_bytes: blob.size });
await fetch(ticket.upload_url, { method: "PUT", headers: { "content-type": "video/mp4" }, body: blob });

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.

string

image, video, audio, document or other, or several comma-separated.

string

None of these kinds, comma-separated.

string

Only files an agent’s sessions made.

string

Exactly these files: up to 100 fil_ ids, comma-separated.

FileSourceType

Provenance — upload, url_import, image_generation, …

string

Only files carrying this tag.

string

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

"desc" | "asc"

Newest first (the default) or oldest first.

const heroes = await client.files.list({ kind: "image", tag: "launch", search: "hero" });
// An agent's pictures and clips, newest first — each carries `agent_id` and `source.model`/`source.prompt`.
const made = await client.files.list({ kind: "image,video", agent_id: "agt_01H9CD..." });

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

createUpload

import

list

get

update

download

publish

delete

​upload

​createUpload

​import

​list

​get

​update

​download

​publish

​delete

upload

createUpload

import

list

get

update

download

publish

delete