Docdeploymill://docs/rest-api

REST API v1

deploymill's /api/v1 REST API is a read-only HTTP mirror of the MCP tool surface. It lets scripts, CI pipelines, and other HTTP clients query app and org state without setting up a full MCP client.

Endpoints

Endpoint	Notes
`GET /api/v1/openapi.json`	OpenAPI 3.1 schema for the full v1 surface. No auth required.
`POST /api/v1/tools/:name`	Call a read-only tool by name. Auth required.

Authentication

All POST /api/v1/tools/:name calls require the same OAuth Bearer token used for the POST /mcp endpoint. Obtain one by running the standard OAuth 2.1 flow (Dynamic Client Registration + PKCE) against /api/auth/mcp/:

POST /api/auth/mcp/register — dynamic client registration.
GET /api/auth/mcp/authorize — browser redirect, user signs in.
POST /api/auth/mcp/token — exchange auth code for access token.

Pass the token as Authorization: Bearer <token>.

For local development, bearer local-dev works against a localhost server. Against a preview with E2E_BOOTSTRAP_SECRET set, use that value as the bearer.

Available tools

v1 exposes the read/inspect subset of the MCP tool surface (no mutations — deploy, set env vars, push files, etc. remain MCP-only):

Tool	What it returns
`get_account`	Org account info, quota headroom, resource summary
`list_apps`	All apps owned by the org
`list_domains`	Domains attached to an app
`list_previews`	Preview environments for an app
`list_deployments`	Recent deployments for an app
`get_app_health`	App status, last deploy, and edge health snapshot
`list_env_vars`	Env-var key names for an app (values are never returned)
`list_org_secrets`	Org secret names (values are never returned)
`list_templates`	Available starter stack templates
`list_files`	Files in a repo path
`get_file`	Contents of a repo file
`search_docs`	Full-text search the public docs/guides corpus
`list_projects`	Underlying Dokploy projects for the org

The full schema (including input shapes and response formats) is in GET /api/v1/openapi.json.

Calling a tool

Send a POST with Content-Type: application/json and a JSON body matching the tool's input shape. An empty object {} works for tools with no required inputs.

# List all apps in the authenticated org
curl -s https://your-deploymill.example.com/api/v1/tools/list_apps \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

# Get health for a specific app
curl -s https://your-deploymill.example.com/api/v1/tools/get_app_health \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_abc123"}'

Error responses

Status	Meaning
`401`	Missing or invalid Bearer token
`404`	Tool name not found in the v1 registry
`422`	Input validation failed — `detail` field lists the Zod errors
`500`	Unexpected server error

Scope and roadmap

v1 is intentionally read-only for now. Mutating operations (deploy, rollback, env var changes, etc.) are on the MCP surface where the agent-safety guardrails (auto-rollback, isolated previews, typed partial-failure recovery) live. Expanding v1 to cover mutations is a tracked follow-up.