Deployments

Preview Deployment resources are the API behind git push managed. The platform builds a repo into a content-addressed, signed artifact, deploys that artifact onto an environment as a release, and lets you promote between environments or roll back to a previous release — without touching Docker, a registry, or a deploy key.

The pipeline, as resources

Resource	What it is
build	A run that turns a git ref into an artifact.
artifact	The content-addressed, signed build output.
deployment	A request to roll a specific artifact onto an environment.
release	The historical record of what ran on an environment, and when.

Builds run on a dedicated builders pool, never on site hosts — see the build pipeline.

Builds

`POST /v1/sites/{id}/environments/{envID}/builds`

deployments:write Start a build from a git ref. Returns a 202 Accepted with a job; the resulting artifact id appears on the job’s result when it succeeds.

Parameter	Type	Required	Description
`ref`	string	no	Git ref to build; defaults to the environment’s mapped branch tip.
`clean`	boolean	no	Skip the build cache for a from-scratch build.

cURL
mf CLI

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../builds \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 2b9d...4f" \
  -H "Content-Type: application/json" \
  -d '{ "ref": "feature/checkout" }'

mf build --site acme-store --env feature-checkout --ref feature/checkout --wait

{
  "data": {
    "id": "job_01J9...",
    "type": "build.run",
    "status": "running",
    "progress": 35,
    "created_at": "2026-06-24T14:31:18Z",
    "resource": { "type": "build", "id": "build_01J8...", "env_id": "env_01J8..." },
    "links": { "self": "/v1/jobs/job_01J9...", "stream": "/v1/jobs/job_01J9.../stream" }
  },
  "request_id": "req_01J9..."
}

`GET …/builds` · `GET …/builds/{buildID}`

deployments:read List builds for an environment (cursor-paginated) or retrieve one, including its status and the artifact it produced.

`GET /v1/sites/{id}/environments/{envID}/artifacts`

deployments:read List the artifacts available to deploy onto this environment, newest first. Each carries a content digest and a signature.

Deployments & rollback

`POST /v1/sites/{id}/environments/{envID}/deployments`

deployments:write Roll a specific artifact onto the environment. Returns a 202 job.

Parameter	Type	Required	Description
`artifact_id`	string	yes	The artifact to deploy.

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../deployments \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: f0c3...aa" \
  -H "Content-Type: application/json" \
  -d '{ "artifact_id": "art_01J8..." }'

{
  "data": {
    "id": "job_01J9...",
    "type": "deployment.roll",
    "status": "queued",
    "created_at": "2026-06-24T14:35:02Z",
    "resource": { "type": "deployment", "id": "dep_01J8...", "env_id": "env_01J8..." },
    "links": { "self": "/v1/jobs/job_01J9...", "stream": "/v1/jobs/job_01J9.../stream" }
  },
  "request_id": "req_01J9..."
}

`POST /v1/sites/{id}/environments/{envID}/deployments/{depID}/rollback`

deployments:write Roll the environment back to the release that preceded a deployment. Returns a 202 job.

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../deployments/dep_01J8.../rollback \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 9bd1...07"

Promote

`POST /v1/sites/{id}/environments/{envID}/promote`

deployments:write Promote the artifact running on this environment onto another — for example, staging → production — without rebuilding. Returns a 202 job.

Parameter	Type	Required	Description
`to_env`	string	yes	Target environment id or kind, e.g. `production`.

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../promote \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 4ee2...c0" \
  -H "Content-Type: application/json" \
  -d '{ "to_env": "production" }'

Releases

`GET /v1/sites/{id}/environments/{envID}/releases`

deployments:read The release history for an environment — every artifact that has run, with its deploy time and the actor that triggered it. Use a release id with rollback to return to a known-good point.

{
  "data": [
    {
      "id": "rel_01J9...",
      "artifact_id": "art_01J8...",
      "ref": "main",
      "deployed_at": "2026-06-24T14:36:40Z",
      "actor": { "type": "api_key", "id": "key_01J7...", "label": "deploy-bot" },
      "current": true
    }
  ],
  "pagination": { "next_cursor": "eyJ0...", "has_more": true },
  "request_id": "req_01J9..."
}

Next steps

Build pipelineHow the platform detects, builds, signs, and rolls an artifact.

Promote & rollbackThe conceptual workflow for promoting between environments and rolling back.

Async jobsTrack the 202 jobs that builds, deploys, promotes, and rollbacks return.

Deployments

The pipeline, as resources

Builds

POST /v1/sites/{id}/environments/{envID}/builds

GET …/builds · GET …/builds/{buildID}

GET /v1/sites/{id}/environments/{envID}/artifacts