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

# REST API

Programmatic access to projects, deployments, and domains.

The base URL for all requests is `https://api.blode.md`.

> [!NOTE]
> The CLI handles deployments automatically. Use the REST API for custom
>   integrations or tooling built on top of blodemd.

## Authentication

Every endpoint uses the Supabase user session token issued by `blodemd login`:

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

The CLI attaches this header automatically.

## Error format

All errors return JSON with an `error` string and an optional `issues` field for validation errors.

```json
{ "error": "string", "issues": [] }
```

---

## Health

| Method | Path      | Description                       |
| ------ | --------- | --------------------------------- |
| GET    | `/health` | Returns `{ ok: true, timestamp }` |

---

## Projects

| Method | Path                   | Description                                  |
| ------ | ---------------------- | -------------------------------------------- |
| GET    | `/projects/`           | List all projects for the authenticated user |
| POST   | `/projects/`           | Create a project                             |
| GET    | `/projects/:projectId` | Get a project                                |
| PATCH  | `/projects/:projectId` | Update a project                             |

**POST /projects/ — request body**

- `name` (type: string): Display name for the project.
- `slug` (type: string): URL-safe identifier. Used as the subdomain at `{slug}.blode.md`.
- `description` (type: string, default: undefined): Optional short description.

Returns the created project.

**PATCH /projects/:projectId — request body**

- `name` (type: string, default: undefined): New display name.
- `description` (type: string, default: undefined): New description.
- `deploymentName` (type: string, default: undefined): Override the active deployment label.

---

## Deployments

Deployments follow a three-step flow: create → upload files → finalize.

| Method | Path                                               | Description           |
| ------ | -------------------------------------------------- | --------------------- |
| POST   | `/projects/slug/:slug/deployments`                 | Create a deployment   |
| POST   | `/projects/slug/:slug/deployments/:id/files/batch` | Upload files in batch |
| POST   | `/projects/slug/:slug/deployments/:id/finalize`    | Finalize and promote  |

**POST /projects/slug/:slug/deployments — request body**

- `branch` (type: string, default: "main"): Git branch name.
- `commitMessage` (type: string, default: undefined): Commit message attached to this deployment.
- `environment` (type: string, default: undefined): Deployment environment label.

**POST .../files/batch — request body**

**POST .../finalize — request body**

- `promote` (type: boolean, default: true): Promote this deployment to production immediately.

---

## Domains

| Method | Path                                                  | Description                  |
| ------ | ----------------------------------------------------- | ---------------------------- |
| GET    | `/projects/:projectId/domains`                        | List domains                 |
| POST   | `/projects/:projectId/domains`                        | Add a custom domain          |
| DELETE | `/projects/:projectId/domains/:domainId`              | Remove a domain              |
| GET    | `/projects/:projectId/domains/:domainId/verification` | Get DNS verification records |
| POST   | `/projects/:projectId/domains/:domainId/verify`       | Trigger domain verification  |

**POST /projects/:projectId/domains — request body**

- `hostname` (type: string): The fully-qualified domain name to add, e.g. `docs.example.com`.
- `pathPrefix` (type: string, default: undefined): Mount the docs at a subpath, e.g. `/docs`.