Deployments

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 — an OCI image, static bundle, or wasm module.
deployment	A request to roll a specific artifact onto an environment.
release	The historical record of what ran on an environment, and which is current.

Builds run on a dedicated builders pool, never on site hosts — see the build pipeline. All mutations here return 202 Accepted with a job; on success the job’s result carries the ids you need next (build_id, artifact_id, deployment_id).

Builds

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

deployments:write Start a build. Returns a 202 Accepted with a job (type build.run); the resulting artifact_id appears on the job’s result when it succeeds.

Parameter	Type	Required	Description
builder	string	yes	The builder to run, e.g. wordpress.
source_ref	string	no	Git ref to build, e.g. refs/heads/main; defaults to the environment’s mapped branch.
commit	string	no	Pin the build to an exact commit.
source	string	no	Source override for non-git builds.
auto_deploy	boolean	no	Roll the artifact onto the environment as soon as the build succeeds.

cURL

Build the branch tip

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 '{ "builder": "wordpress", "source_ref": "refs/heads/feature/checkout", "auto_deploy": true }'

Go

Build the branch tip and follow the job

job, err := client.Deployments.CreateBuild(ctx, "site_01J7...", "env_01J8...",
    forge.BuildCreateParams{
        Builder:   "wordpress",
        SourceRef: "refs/heads/feature/checkout", // auto-deploys by default
    })
if err != nil { return err }
_, err = client.Jobs.FollowSuccess(ctx, job.ID, os.Stdout)

mf CLI

Build the branch tip

mf deploy build --site site_01J7... --builder wordpress \
  --ref refs/heads/feature/checkout --follow

Response (202 Accepted)

{
  "data": {
    "id": "job_01J9...",
    "type": "build.run",
    "status": "queued",
    "progress": 0,
    "created_at": "2026-06-24T14:31:18Z",
    "resource": { "type": "build", "id": "build_01J8...", "site_id": "site_01J7...", "env_id": "env_01J8..." },
    "result": null,
    "error": null,
    "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, newest first) or retrieve one. A build carries its status (queued, running, succeeded, failed), the builder, ref, commit, and the artifact_id it produced.

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

deployments:read List the artifacts deployable onto this environment, newest first. Each carries a content digest, a signature_ref, its serve_model (container, static, or wasm), and the source commit and ref it was built from.

Deployments & rollback

POST /v1/sites/{siteID}/environments/{envID}/deployments

deployments:write Roll a specific artifact onto the environment. Returns a 202 job (type deployment.deploy_artifact).

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

cURL

Deploy an artifact

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..." }'

Go

Deploy an artifact

job, err := client.Deployments.CreateDeployment(ctx, "site_01J7...", "env_01J8...", "art_01J8...")

mf CLI

Deploy an artifact

mf deploy create art_01J8... --site site_01J7... --wait

Response (202 Accepted)

{
  "data": {
    "id": "job_01J9...",
    "type": "deployment.deploy_artifact",
    "status": "queued",
    "progress": 0,
    "created_at": "2026-06-24T14:35:02Z",
    "resource": { "type": "deployment", "id": "dep_01J8...", "site_id": "site_01J7...", "env_id": "env_01J8..." },
    "result": null,
    "error": null,
    "links": { "self": "/v1/jobs/job_01J9...", "stream": "/v1/jobs/job_01J9.../stream" }
  },
  "request_id": "req_01J9..."
}

GET /v1/sites/{siteID}/environments/{envID}/deployments

deployments:read The environment’s deployments, newest first. Each carries its status (pending, deploying, live, failed, superseded), the artifact_id it rolled, and current_since when it is the live one.

POST /v1/sites/{siteID}/environments/{envID}/deployments/{depID}/rollback

deployments:write Roll the environment back to this deployment’s release — restore the artifact it ran. Returns a 202 job (type deployment.rollback).

Roll back a bad deploy

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"

Tip

Rollback restores the previous release — code plus the artifact that ran with it. To roll back data as well, restore a snapshot. See promote & rollback for when to reach for which.

Promote

POST /v1/sites/{siteID}/environments/{envID}/promote

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

Parameter	Type	Required	Description
to_env	string	yes	Target environment id, or production for the production target.

cURL

Promote staging to 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" }'

Go

Promote staging to production

job, err := client.Deployments.Promote(ctx, "site_01J7...", "env_01J8...",
    forge.PromoteTargetProduction)

mf CLI

Promote staging to production

mf deploy promote --site site_01J7... --to production --wait

Releases

GET /v1/sites/{siteID}/environments/{envID}/releases

deployments:read The release history for an environment — every artifact that has run and which one is current. A release’s id is the deployment id, so you can hand it straight to rollback to return to a known-good point.

Response

{
  "data": [
    {
      "id": "dep_01J9...",
      "artifact_id": "art_01J8...",
      "digest": "sha256:7c1e...",
      "ref": "refs/heads/main",
      "status": "live",
      "current": true,
      "deployed_at": "2026-06-24T14:36:40Z",
      "created_at": "2026-06-24T14:35:02Z"
    }
  ],
  "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.