API Reference / Deployments

A Deployment is the stable production object for a published app/site/API. See Deploy / Overview for the conceptual model.

Endpoints

POST   /api/v1/projects/:project_id/deployments        # Phase 2B
GET    /api/v1/deployments
GET    /api/v1/deployments/:id
PATCH  /api/v1/deployments/:id
DELETE /api/v1/deployments/:id
POST   /api/v1/deployments/:id/publish                 # Phase 2B
POST   /api/v1/deployments/:id/rollback                # Phase 2B
POST   /api/v1/sandboxes/:id/deploy                    # Backward-compat

All endpoints require Authorization: Bearer <msk_*>. Mutations should include an Idempotency-Key header.

Create

POST /api/v1/projects/:project_id/deployments

Body:

{
  "name": "Smile Dental Landing",
  "source_type": "sandbox",
  "workspace_slug": "dr-smith-clinic",
  "workspace_name": "Dr. Smith Clinic",
  "project_slug": "smile-dental-landing",
  "project_name": "Smile Dental Landing",
  "external_workspace_id": "clinic_123",
  "external_user_id": "dr-smith-456",
  "external_project_id": "project_789",
  "metadata": { }
}

Ownership fields accepted on create: workspace_id, workspace_slug, workspace_name, project_id, project_slug, project_name, external_workspace_id, external_user_id, and external_project_id.

Scopes: deployments:write.

Publish

POST /api/v1/deployments/:id/publish

Body:

{
  "source_sandbox_id": "sbx_...",
  "kind": "auto",
  "environment": "production",
  "output_path": "/workspace",
  "build_command": "npm run build",
  "run_command": "npm start",
  "port": 3000,
  "health_check_path": "/_health",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440001",
  "external_workspace_id": "clinic_123"
}

Server-side behavior is documented in Publishing.

Response:

{
  "data": {
    "deployment": {
      "id": "dep_...",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "660e8400-e29b-41d4-a716-446655440001",
      "active_version_id": "ver_...",
      "state": "running",
      "public_url": "https://smile-dental.cliniciq.miosa.app"
    },
    "version": {
      "id": "ver_...",
      "kind": "static",
      "state": "ready",
      "artifact_uri": "s3://...",
      "artifact_sha256": "...",
      "source_sha256": "..."
    },
    "services": [
      { "id": "svc_...", "type": "static_web", "state": "healthy" }
    ],
    "promoted": true
  }
}

List

GET /api/v1/deployments
GET /api/v1/deployments?workspace_id=550e8400-e29b-41d4-a716-446655440000
GET /api/v1/deployments?project_id=660e8400-e29b-41d4-a716-446655440001
GET /api/v1/deployments?external_workspace_id=clinic_123
GET /api/v1/deployments?external_user_id=dr-smith-456
GET /api/v1/deployments?state=running

All filters are organization-scoped server-side. See Ownership and Attribution.

Get

GET /api/v1/deployments/:id

Returns the full deployment row including workspace_id, project_id, active_version_id, attribution, and metadata.

Update

PATCH /api/v1/deployments/:id

Body: any subset of mutable fields (name, auto_deploy, metadata, external_*).

Rollback

POST /api/v1/deployments/:id/rollback

Body:

{
  "version_id": "ver_..."
}

See Rollback.

Delete

DELETE /api/v1/deployments/:id

Tears down runtime instances, removes routes, marks the deployment deleted. Versions and releases are retained per the retention policy.