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

# Sites

> Create a site, upload files and bundles to it, list, read and delete — the full authenticated surface.

Base URL is `https://htmldrop.app/api/v1`. Every endpoint here needs an
[API token](/api/authentication).

<Info>
  Most authenticated endpoints require a verified email and return
  `403 {"error":"email_not_verified"}` otherwise. The exceptions — so a new
  account can get one site live before confirming — are `POST /sites`,
  `GET /sites`, `GET /sites/{id}`, `DELETE /sites/{id}`, `POST /sites/{id}/upload`
  and `POST /sites/{id}/upload-bundle`. In practice this only affects dashboard
  sessions: API tokens can only be created by an already-verified account.
</Info>

## Create a site

```
POST /sites
```

Both fields are optional — omit `slug` for a random one, omit `name` to leave it
blank.

```bash theme={null}
curl -X POST https://htmldrop.app/api/v1/sites \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-project", "name": "My Project"}'
```

Returns `201`:

```json theme={null}
{
  "id": "st_...",
  "slug": "my-project",
  "name": "My Project",
  "access_mode": "public",
  "has_password": false,
  "branding_enabled": true
}
```

Creating a site only reserves the slug — it has no content until you upload.

## Upload a single file

```
POST /sites/{id}/upload
```

Multipart with one `file` field: `.html`/`.htm` is served as-is, `.md` is
rendered to HTML. Every upload creates a version and promotes it live.

```bash theme={null}
curl -X POST https://htmldrop.app/api/v1/sites/st_.../upload \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -F "file=@./index.html"
```

Returns `201`:

```json theme={null}
{ "version_id": "v_...", "version_number": 2, "byte_size": 4213, "file_count": 1 }
```

## Upload a folder or .zip

```
POST /sites/{id}/upload-bundle
```

Two accepted shapes:

<Tabs>
  <Tab title="Files and paths">
    Repeated `files` fields with a parallel `paths` field giving each file's
    relative path. This is what the dashboard's folder picker sends, and what
    multipart clients that can't preserve directory structure should use.

    ```bash theme={null}
    curl -X POST https://htmldrop.app/api/v1/sites/st_.../upload-bundle \
      -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
      -F "files=@./dist/index.html"       -F "paths=index.html" \
      -F "files=@./dist/assets/app.css"   -F "paths=assets/app.css" \
      -F "files=@./dist/assets/app.js"    -F "paths=assets/app.js"
    ```
  </Tab>

  <Tab title="A single .zip">
    One `file` field whose filename ends in `.zip`. htmldrop extracts it
    server-side and deploys the contents.

    ```bash theme={null}
    curl -X POST https://htmldrop.app/api/v1/sites/st_.../upload-bundle \
      -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
      -F "file=@./site.zip"
    ```
  </Tab>
</Tabs>

Either way `index.html` must exist at the root of the bundle. The response has
the same shape as a single-file upload.

## List and read

```bash theme={null}
curl https://htmldrop.app/api/v1/sites \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"

curl https://htmldrop.app/api/v1/sites/st_... \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"
```

`GET /sites` returns an array; `GET /sites/{id}` returns one site in the same
shape `POST /sites` returns.

## Update settings

`PATCH /sites/{id}` changes a site's configuration — name, slug, password,
analytics, and `spa_fallback`:

```bash theme={null}
curl -X PATCH https://htmldrop.app/api/v1/sites/{id} \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spa_fallback": true}'
```

## Delete

```bash theme={null}
curl -X DELETE https://htmldrop.app/api/v1/sites/st_... \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"
```

Returns `204`. Deletion is immediate and permanent.

## The authenticated account

```bash theme={null}
curl https://htmldrop.app/api/v1/me \
  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"
```

Returns the signed-in user and tenant: email, verification status, plan, role,
and the organisations available to switch between.

## Usage and export

```bash theme={null}
curl https://htmldrop.app/api/v1/usage  -H "Authorization: Bearer $HTMLDROP_API_TOKEN"
curl https://htmldrop.app/api/v1/sites/export -H "Authorization: Bearer $HTMLDROP_API_TOKEN" -o export.zip
```

`usage` reports consumption against your plan's caps. `export` returns every
drop as a `.zip` — there is no lock-in and no export fee.