Deploy
The Deploy API lets you trigger builds, monitor deployment status, stream build logs, scale replicas, and manage traffic routing between revisions. All operations are scoped to a workspace.
Trigger Deploy
/workspaces/{wsId}/deployTriggers a new build and deployment for an app. Optionally specify a branch or an exact commit SHA to deploy. If neither is provided the app's configured branch is used and the latest commit is fetched.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| appId | string | required | ID of the app to deploy |
| gitBranch | string | optional | Branch to deploy from. Overrides the app's default branch for this deployment only. |
| gitCommitSha | string | optional | Exact commit SHA to build. Takes precedence over gitBranch when both are provided. |
Response
{
"id": "dep_01hx...",
"status": "queued",
"appId": "app_01hx...",
"gitBranch": "main",
"gitCommitSha": "a1b2c3d4e5f6...",
"gitCommitMessage": "feat: add new endpoint",
"buildpack": "nixpacks",
"createdAt": "2025-04-17T12:00:00Z"
}curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy" \
-H "Authorization: Bearer dor_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"appId": "app_01hx...",
"gitBranch": "main"
}'List Deployments
/workspaces/{wsId}/deployReturns a paginated list of deployments for a specific app. Results are ordered by creation date, newest first.
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| appId | string | required | ID of the app to list deployments for |
| page | integer | optional | Page number starting at 1. Default: 1 |
| limit | integer | optional | Items per page. Default: 20, max: 100 |
| status | string | optional | Filter by status: queued | building | deploying | succeeded | failed | cancelled |
Response
{
"data": [
{
"id": "dep_01hx...",
"status": "succeeded",
"gitBranch": "main",
"gitCommitSha": "a1b2c3d",
"gitCommitMessage": "feat: add new endpoint",
"durationSeconds": 52,
"createdAt": "2025-04-17T12:00:00Z"
},
{
"id": "dep_00hx...",
"status": "succeeded",
"gitBranch": "main",
"gitCommitSha": "z9y8x7w",
"gitCommitMessage": "fix: correct response shape",
"durationSeconds": 48,
"createdAt": "2025-04-16T09:00:00Z"
}
],
"meta": { "total": 24, "page": 1, "limit": 20, "totalPages": 2 }
}curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy?appId=app_01hx...&page=1&limit=20" \
-H "Authorization: Bearer dor_sk_your_key_here"Get Deployment
/workspaces/{wsId}/deploy/{deployId}Retrieves full details for a single deployment, including build timing, git metadata, and the resulting container image reference.
Response
{
"id": "dep_01hx...",
"status": "succeeded",
"appId": "app_01hx...",
"gitBranch": "main",
"gitCommitSha": "a1b2c3d4e5f6...",
"gitCommitMessage": "feat: add new endpoint",
"buildpack": "nixpacks",
"imageRef": "registry.dooor.ai/org/my-api:sha256-abc123",
"revisionName": "my-api-00005",
"durationSeconds": 52,
"startedAt": "2025-04-17T12:00:05Z",
"finishedAt": "2025-04-17T12:00:57Z",
"createdAt": "2025-04-17T12:00:00Z"
}curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/{deployId}" \
-H "Authorization: Bearer dor_sk_your_key_here"Runtime Status
/workspaces/{wsId}/deploy/{deployId}/runtime-statusReturns the Kubernetes runtime health for a specific deployment, including pod readiness counts and condition messages.
Response
{
"phase": "Running",
"ready": 2,
"total": 2,
"conditions": [
{
"type": "Available",
"status": "True",
"lastTransitionTime": "2025-04-17T12:01:10Z"
},
{
"type": "Progressing",
"status": "True",
"lastTransitionTime": "2025-04-17T12:00:58Z"
}
]
}curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/{deployId}/runtime-status" \
-H "Authorization: Bearer dor_sk_your_key_here"Build Logs
/workspaces/{wsId}/deploy/{deployId}/logsReturns the full build log for a deployment as an array of lines. Available once the build has started. For streaming logs during an active build, use the WebSocket endpoint described in the Monitoring section.
Response
{
"logs": [
"[nixpacks] Detected Node.js project",
"[nixpacks] Installing dependencies...",
"added 312 packages in 14s",
"[nixpacks] Running build command: npm run build",
"Route (app) Size",
"...",
"[nixpacks] Build succeeded",
"[registry] Pushing image to registry...",
"[registry] Push complete: sha256:abc123..."
]
}curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/{deployId}/logs" \
-H "Authorization: Bearer dor_sk_your_key_here"Scale App
/workspaces/{wsId}/deploy/scaleManually sets the desired replica count for a running app. Pass replicas: 0 to stop the app without deleting it.
maxReplicas configured, the Kubernetes HPA will continue autoscaling between minReplicas and maxReplicas. Scaling manually below minReplicas will only hold temporarily until the HPA reconciles.Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| appId | string | required | ID of the app to scale |
| replicas | integer | required | Desired number of replicas. Range: 0-10. Set to 0 to stop the app. |
Response
{
"appId": "app_01hx...",
"name": "my-api",
"requestedReplicas": 3,
"currentReplicas": 2,
"status": "scaling"
}curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/scale" \
-H "Authorization: Bearer dor_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"appId": "app_01hx...",
"replicas": 3
}'Rollback
/workspaces/{wsId}/deploy/{deployId}/rollbackCreates a new deployment by re-deploying the container image from a previous successful deployment. The deployId in the path refers to the deployment you want to roll back to - not the current one. A new deployment record is created with status deploying.
releaseCommand configured on the app (e.g. database migrations) will run again as part of the rollback deployment. Ensure your migrations are backward-compatible before rolling back.Response
{
"id": "dep_02hx...",
"status": "deploying",
"appId": "app_01hx...",
"rolledBackFrom": "dep_01hx...",
"gitCommitSha": "z9y8x7w6v5u4...",
"gitCommitMessage": "fix: correct response shape",
"createdAt": "2025-04-17T13:00:00Z"
}curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/{deployId}/rollback" \
-H "Authorization: Bearer dor_sk_your_key_here"List Revisions
/workspaces/{wsId}/deploy/apps/{appId}/revisionsLists all Kubernetes revisions for an app, ordered from newest to oldest. Each revision corresponds to a deployed container image. The trafficPercent field shows how much live traffic the revision is currently receiving.
Response
[
{
"revisionName": "my-api-00005",
"imageRef": "registry.dooor.ai/org/my-api:sha256-abc123",
"trafficPercent": 100,
"createdAt": "2025-04-17T12:00:57Z"
},
{
"revisionName": "my-api-00004",
"imageRef": "registry.dooor.ai/org/my-api:sha256-def456",
"trafficPercent": 0,
"createdAt": "2025-04-16T09:05:00Z"
}
]curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/apps/{appId}/revisions" \
-H "Authorization: Bearer dor_sk_your_key_here"Set Traffic
/workspaces/{wsId}/deploy/apps/{appId}/trafficSets the traffic split between revisions for gradual canary or blue-green deployments. The percent values across all splits must sum to exactly 100.
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| splits | array | required | Array of traffic split objects. The sum of all percent values must equal 100. |
| splits[].revisionName | string | required | Kubernetes revision name (e.g. my-api-00005) |
| splits[].percent | integer | required | Percentage of traffic to send to this revision (0-100) |
| splits[].tag | string | optional | Optional named tag for the split (e.g. canary, stable). Enables tagged URL access. |
Example - Canary Release (10% to new revision)
curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/apps/{appId}/traffic" \
-H "Authorization: Bearer dor_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"splits": [
{ "revisionName": "my-api-00005", "percent": 10, "tag": "canary" },
{ "revisionName": "my-api-00004", "percent": 90, "tag": "stable" }
]
}'Response
{
"appId": "app_01hx...",
"splits": [
{ "revisionName": "my-api-00005", "percent": 10, "tag": "canary" },
{ "revisionName": "my-api-00004", "percent": 90, "tag": "stable" }
],
"updatedAt": "2025-04-17T14:00:00Z"
}Promote Revision
/workspaces/{wsId}/deploy/revisions/{revisionName}/promotePromotes a revision to receive 100% of traffic, removing all other splits. This is a shortcut for setting a single-revision traffic allocation - equivalent to calling Set Traffic with {"splits": [{"revisionName": "...", "percent": 100}]}.
Response
{
"appId": "app_01hx...",
"promotedRevision": "my-api-00005",
"splits": [
{ "revisionName": "my-api-00005", "percent": 100 }
],
"updatedAt": "2025-04-17T14:30:00Z"
}curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/deploy/revisions/{revisionName}/promote" \
-H "Authorization: Bearer dor_sk_your_key_here"