# Quick Start

**Page:** api/files/quick-start

[Download Raw Markdown](./api/files/quick-start.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Quick Start

Hoody Files provides a unified API for managing files and directories across your workspaces. Whether you are uploading assets, organizing project resources, or building collaborative editing experiences, the Files API gives you programmatic access to the same storage layer that powers the Hoody dashboard.

This guide covers the core file and directory operations available to authenticated users. All endpoints are scoped to a workspace and require a valid API token in the `Authorization` header.

### Core operations

The Files API is organized around a small set of predictable operations:

- **Files** — upload, retrieve, update metadata, and delete individual files. Files are addressed by a unique `fileID` within a workspace.
- **Directories** — create, list, rename, and delete folders. Directories can be nested and are addressed by a path or `directoryID`.
- **Workspace context** — every file and directory lives inside a workspace. The `workspaceID` is always part of the request path and identifies the storage boundary for the operation.

### Authentication

All requests must include a bearer token:

```
Authorization: Bearer <token>
```

Tokens are issued from the Hoody dashboard and inherit the permissions of the user that created them. Ensure the token has read and write access to the target workspace before performing mutating operations.

### Base path

All endpoints in this section are rooted at:

```
/api/v1/workspaces/{workspaceID}/files
```

Replace `{workspaceID}` with the ID of the workspace that owns the files you want to manage.

### Next steps


  
    Upload, retrieve, update, and delete files. See the file endpoints for request/response details.
  
  
    Create, list, rename, and delete directories. Directory operations accept a path or an ID.
  
  
    Files are always scoped to a workspace. Confirm your `workspaceID` before issuing requests.
  



  When in doubt, start with a `GET` against a directory path to confirm the workspace ID and token permissions are valid before attempting uploads or mutations.