REST API

Programmatic access to projects, deployments, and domains.

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

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.

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


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

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

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

Field	Type	Description	Required	Default
`name`	string	Display name for the project.	Yes	—
`slug`	string	URL-safe identifier. Used as the subdomain at `{slug}.blode.md`.	Yes	—
`description`	string	Optional short description.	Yes	undefined

Returns the created project.

PATCH /projects/:projectId — request body

Field	Type	Description	Required	Default
`name`	string	New display name.	Yes	undefined
`description`	string	New description.	Yes	undefined
`deploymentName`	string	Override the active deployment label.	Yes	undefined

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

Field	Type	Description	Required	Default
`branch`	string	Git branch name.	Yes	"main"
`commitMessage`	string	Commit message attached to this deployment.	Yes	undefined
`environment`	string	Deployment environment label.	Yes	undefined

POST .../files/batch — request body

Field	Type	Description	Required	Default
`files[].path`	string	Relative path of the file within the docs directory.	Yes	—
`files[].contentBase64`	string	Base64-encoded file contents.	Yes	—
`files[].contentType`	string	MIME type. Inferred from the path if omitted.	Yes	undefined

POST .../finalize — request body

Field	Type	Description	Required	Default
`promote`	boolean	Promote this deployment to production immediately.	Yes	true

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

Field	Type	Description	Required	Default
`hostname`	string	The fully-qualified domain name to add, e.g. `docs.example.com`.	Yes	—
`pathPrefix`	string	Mount the docs at a subpath, e.g. `/docs`.	Yes	undefined