> ## 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, list, download, and publish artifacts — client.files.

Files are session scratch until published, then durable org artifacts. Six 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");
const file = await client.files.upload(form);
```

## 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>

## get

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

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

## 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}`.