> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# files

> Upload, import, find, describe and publish artifacts — client.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](/docs/api/files).

## upload

```ts theme={"system"}
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:

```ts theme={"system"}
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

```ts theme={"system"}
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.

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

<ResponseField name="url" type="string" required>Public `http(s)` URL; private and local hosts are refused.</ResponseField>
<ResponseField name="title" type="string">A human title.</ResponseField>
<ResponseField name="description" type="string">A longer, searchable description.</ResponseField>
<ResponseField name="tags" type="string[]">Labels to filter by.</ResponseField>

## list

```ts theme={"system"}
client.files.list(query?: FileFilter): Promise<Page<File>>
```

`GET /v1/files`. `FileFilter` extends the [page query](/docs/sdk/pagination) with:

<ResponseField name="scope" type="&#x22;session&#x22; | &#x22;published&#x22;">Only scratch, or only published artifacts.</ResponseField>
<ResponseField name="session_id" type="string">Only files a given session produced.</ResponseField>
<ResponseField name="kind" type="FileKind">`image`, `video`, `audio`, `document` or `other`.</ResponseField>
<ResponseField name="source" type="FileSourceType">Provenance — `upload`, `url_import`, `image_generation`, …</ResponseField>
<ResponseField name="tag" type="string">Only files carrying this tag.</ResponseField>
<ResponseField name="search" type="string">Case-insensitive substring of the title, name or description.</ResponseField>

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

## get

```ts theme={"system"}
client.files.get(id: string): Promise<File>
```

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

## update

```ts theme={"system"}
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.

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

## download

```ts theme={"system"}
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

```ts theme={"system"}
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

```ts theme={"system"}
client.files.delete(id: string): Promise<Deleted>
```

`DELETE /v1/files/{id}`.