# Projects (/docs/projects)



Projects are lightweight containers for files. Use them when one API key needs
to serve multiple apps, environments, customers, or AI-agent workflows without
mixing their file lists together.

Every account gets a default project. Existing files without a project are shown
there, and new SDK calls that omit `projectId` keep working by using that default.

## Create a project [#create-a-project]

```ts
import { S3Delivery } from "s3delivery";

const s3 = new S3Delivery();
const project = await s3.createProject({ name: "Production app" });
```

## Upload into a project [#upload-into-a-project]

```ts
const file = await s3.upload(blob, {
  name: "report.pdf",
  visibility: "private",
  projectId: project.id,
});
```

The bytes still go directly to your bucket through presigned URLs. The project
only changes the metadata grouping and the organized bucket key prefix for new
uploads.

## List project files [#list-project-files]

```ts
const { projects } = await s3.listProjects();
const { files } = await s3.list({ projectId: projects[0].id });
```

## REST API [#rest-api]

```bash
curl https://api.s3.delivery/v1/projects \
  -H "x-api-key: $S3DELIVERY_TOKEN"

curl https://api.s3.delivery/v1/files?projectId=proj_xxx \
  -H "x-api-key: $S3DELIVERY_TOKEN"
```