---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/api/files
markdown_url: https://steel.dev/docs/reference/api/files.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Files API
description: Upload, list, download and delete your organization's global files, which you can copy into any session, with the Steel API.
summary: Upload, list, download and delete your organization's global files, which you can copy into any session, with the Steel API.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/api/profiles.md
  - https://steel.dev/docs/reference/api/credentials.md
  - https://steel.dev/docs/reference/api/extensions.md
  - https://steel.dev/docs/reference/api/projects.md
  - https://steel.dev/docs/reference/api/api-keys.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Files API

Global files are the files that your organization stores outside any session. These endpoints upload, list, download and delete them. The endpoints for one session's files are on [Sessions API](https://steel.dev/docs/reference/api/sessions#session-files). For the base URL and authentication, see [API conventions](https://steel.dev/docs/reference/api). For the error codes, see [Errors](https://steel.dev/docs/reference/errors).

The first example is a complete program. The later examples use its `client`.

## Endpoints

### List global files

```http
GET /v1/files
```

Lists your organization's global files.

This endpoint takes no parameters.

| Field | Type | Description |
| - | - | - |
| `data` | object\[] | The files, each with `path`, `size` in bytes and `lastModified`. |

**cURL**

```sh
curl https://api.steel.dev/v1/files \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts file=list-files.mts
import Steel from "steel-sdk";

const client = new Steel();
const files = await client.files.list();

for (const file of files.data) {
  console.log(file.path, file.size);
}
```

**Python**

```python file=list-files.py
from steel import Steel

client = Steel()
files = client.files.list()

for file in files.data:
    print(file.path, int(file.size))
```

**Go**

```go file=main.go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/steel-dev/sdk/go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()
	files, err := client.Files.List(ctx)
	if err != nil {
		return err
	}

	for _, file := range files.Data {
		fmt.Println(file.Path, file.Size)
	}
	return nil
}
```

**Rust**

```rust file=src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();
    let files = client.files().list().await?;

    for file in files.data {
        println!("{} {}", file.path, file.size);
    }
    Ok(())
}
```

See [Files](https://steel.dev/docs/sessions/files).

### Upload a global file

```http
POST /v1/files
```

Uploads a global file. The request is `multipart/form-data`.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `file` | body | file or string | yes | | The file content, or a URL to download the file from. |
| `path` | body | string | no | | The path of the file in storage, such as `datasets/prices.csv`. |

The response is `201`:

| Field | Type | Description |
| - | - | - |
| `path` | string | The path of the file in storage. |
| `size` | integer | The size in bytes. |
| `lastModified` | string (date-time) | When the file was created. |

**cURL**

```sh
curl -X POST https://api.steel.dev/v1/files \
  -H "steel-api-key: $STEEL_API_KEY" \
  -F "file=@dataset.csv" \
  -F "path=dataset.csv"
```

**TypeScript**

```ts
import { createReadStream } from "node:fs";

const file = await client.files.upload({
  file: createReadStream("dataset.csv"),
  path: "dataset.csv",
});
console.log(file.path);
```

**Python**

```python
from pathlib import Path

file = client.files.upload(file=Path("dataset.csv"), path="dataset.csv")
print(file.path)
```

**Go**

```go
import (
	"io"
	"os"
)

dataset, err := os.Open("dataset.csv")
if err != nil {
	return err
}
defer dataset.Close()
file, err := client.Files.Upload(ctx, steel.FileUploadParams{
	File: steel.F[io.Reader](dataset),
	Path: steel.F("dataset.csv"),
})
if err != nil {
	return err
}
fmt.Println(file.Path)
```

**Rust**

```rust
let file = client
    .files()
    .upload(steel_rs::FileUploadParams {
        path: Some("dataset.csv".to_owned()),
        ..steel_rs::FileUploadParams::new(steel_rs::Upload::open("dataset.csv").await?)
    })
    .await?;
println!("{}", file.path);
```

To copy a global file into a session, pass its `path` as `file` to [Upload a file to a session](https://steel.dev/docs/reference/api/sessions#upload-a-file-to-a-session). See [Files](https://steel.dev/docs/sessions/files).

### Download a global file

```http
GET /v1/files/{path}
```

Downloads one global file.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `path` | path | string | yes | | The path of the file. It can contain `/`. |

The response is the file, as `application/octet-stream`.

**cURL**

```sh
curl https://api.steel.dev/v1/files/dataset.csv \
  -H "steel-api-key: $STEEL_API_KEY" \
  -o dataset.csv
```

**TypeScript**

```ts
const response = await client.files.download("dataset.csv");
const csv = await response.text();
```

**Python**

```python
response = client.files.download("dataset.csv")
response.write_to_file("dataset.csv")
```

**Go**

```go
import "io"

response, err := client.Files.Download(ctx, "dataset.csv")
if err != nil {
	return err
}
defer response.Body.Close()
body, err := io.ReadAll(response.Body)
if err != nil {
	return err
}
csv := string(body)
```

**Rust**

```rust
let response = client.files().download("dataset.csv").await?;
let csv = String::from_utf8(response.to_vec())?;
```

See [Files](https://steel.dev/docs/sessions/files).

### Delete a global file

```http
DELETE /v1/files/{path}
```

Deletes one global file.

| Name | In | Type | Required | Default | Description |
| - | - | - | - | - | - |
| `path` | path | string | yes | | The path of the file. It can contain `/`. |

The response is `204` with no body.

**cURL**

```sh
curl -X DELETE https://api.steel.dev/v1/files/dataset.csv \
  -H "steel-api-key: $STEEL_API_KEY"
```

**TypeScript**

```ts
await client.files.delete("dataset.csv");
```

**Python**

```python
client.files.delete("dataset.csv")
```

**Go**

```go
if err := client.Files.Delete(ctx, "dataset.csv"); err != nil {
	return err
}
```

**Rust**

```rust
client.files().delete("dataset.csv").await?;
```

See [Files](https://steel.dev/docs/sessions/files).
