> ## Documentation Index
> [HTML page](https://blode.co/edda/docs/api/overview)
> [Documentation index](https://blode.co/edda/docs/llms.txt)
> Use the index to discover all available pages before exploring further.

# REST API overview

Use the Edda REST API for programmatic access to projects, deployments, and domains when you need custom tooling beyond the CLI workflows.

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 edda.

## Authentication

Every endpoint uses the Supabase user session token issued by `edda 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`.