Skip to content

docs: add deployment API docs #2963

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
isshaddad wants to merge 3 commits into from
Closed

docs: add deployment API docs #2963

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
15d3783
promote deployment api
isshaddad Jan 28, 2026
756a3a0
deployment GET api endpoints
isshaddad Jan 28, 2026
a2c0f3b
issues fixed
isshaddad Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,14 @@
"management/envvars/update",
"management/envvars/delete"
]
},
{
"group": "Deployments API",
"pages": [
"management/deployments/retrieve",
"management/deployments/get-latest",
"management/deployments/promote"
]
}
]
},
Expand Down
4 changes: 4 additions & 0 deletions docs/management/deployments/get-latest.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "Get latest deployment"
openapi: "v3-openapi GET /api/v1/deployments/latest"
---
4 changes: 4 additions & 0 deletions docs/management/deployments/promote.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "Promote deployment"
openapi: "v3-openapi POST /api/v1/deployments/{version}/promote"
---
4 changes: 4 additions & 0 deletions docs/management/deployments/retrieve.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: "Get deployment"
openapi: "v3-openapi GET /api/v1/deployments/{deploymentId}"
---
239 changes: 239 additions & 0 deletions docs/v3-openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -505,6 +505,245 @@ paths:

await runs.cancel("run_1234");

"/api/v1/deployments/{deploymentId}":
parameters:
- in: path
name: deploymentId
required: true
schema:
type: string
description: The deployment ID.
get:
operationId: get_deployment_v1
summary: Get deployment
description: Retrieve information about a specific deployment by its ID.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The deployment ID
status:
type: string
enum: ["PENDING", "INSTALLING", "BUILDING", "DEPLOYING", "DEPLOYED", "FAILED", "CANCELED", "TIMED_OUT"]
description: The current status of the deployment
contentHash:
type: string
description: Hash of the deployment content
shortCode:
type: string
description: The short code for the deployment
version:
type: string
description: The deployment version (e.g., "20250228.1")
imageReference:
type: string
nullable: true
description: Reference to the deployment image
imagePlatform:
type: string
description: Platform of the deployment image
externalBuildData:
type: object
nullable: true
description: External build data if applicable
errorData:
type: object
nullable: true
description: Error data if the deployment failed
worker:
type: object
nullable: true
description: Worker information if available
properties:
id:
type: string
version:
type: string
tasks:
type: array
items:
type: object
properties:
id:
type: string
slug:
type: string
filePath:
type: string
exportName:
type: string
"401":
description: Unauthorized - Access token is missing or invalid
"404":
description: Deployment not found
tags:
- deployments
security:
- personalAccessToken: []
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Outdated
x-codeSamples:
- lang: typescript
source: |-
// Note: This endpoint requires a personal access token, not a secret key
const response = await fetch(
`https://api.trigger.dev/api/v1/deployments/${deploymentId}`,
{
method: "GET",
headers: {
"Authorization": `Bearer ${personalAccessToken}`,
},
}
);
const deployment = await response.json();
- lang: curl
source: |-
curl -X GET "https://api.trigger.dev/api/v1/deployments/deployment_1234" \
-H "Authorization: Bearer your_personal_access_token"

"/api/v1/deployments/latest":
get:
operationId: get_latest_deployment_v1
summary: Get latest deployment
description: Retrieve information about the latest unmanaged deployment for the authenticated project.
responses:
"200":
description: Successful request
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The deployment ID
status:
type: string
enum: ["PENDING", "INSTALLING", "BUILDING", "DEPLOYING", "DEPLOYED", "FAILED", "CANCELED", "TIMED_OUT"]
description: The current status of the deployment
contentHash:
type: string
description: Hash of the deployment content
shortCode:
type: string
description: The short code for the deployment
version:
type: string
description: The deployment version (e.g., "20250228.1")
imageReference:
type: string
nullable: true
description: Reference to the deployment image
imagePlatform:
type: string
description: Platform of the deployment image
externalBuildData:
type: object
nullable: true
description: External build data if applicable
errorData:
type: object
nullable: true
Comment thread
devin-ai-integration[bot] marked this conversation as resolved.
Outdated
description: Error data if the deployment failed
"401":
description: Unauthorized - Access token is missing or invalid
"404":
description: No deployment found
tags:
- deployments
security:
- personalAccessToken: []
x-codeSamples:
- lang: typescript
source: |-
// Note: This endpoint requires a personal access token, not a secret key
const response = await fetch(
"https://api.trigger.dev/api/v1/deployments/latest",
{
method: "GET",
headers: {
"Authorization": `Bearer ${personalAccessToken}`,
},
}
);
const deployment = await response.json();
- lang: curl
source: |-
curl -X GET "https://api.trigger.dev/api/v1/deployments/latest" \
-H "Authorization: Bearer your_personal_access_token"

"/api/v1/deployments/{version}/promote":
parameters:
- in: path
name: version
required: true
schema:
type: string
description: The deployment version to promote (e.g., "20250228.1").
post:
operationId: promote_deployment_v1
summary: Promote deployment
description: Promote a previously deployed version to be the current version for the environment. This makes the specified version active for new task runs.
responses:
"200":
description: Deployment promoted successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The deployment ID
version:
type: string
description: The deployment version (e.g., "20250228.1")
shortCode:
type: string
description: The short code for the deployment
"400":
description: Invalid request
content:
application/json:
schema:
type: object
properties:
error:
type: string
"401":
description: Unauthorized - Access token is missing or invalid
"404":
description: Deployment not found
tags:
- deployments
security:
- personalAccessToken: []
x-codeSamples:
- lang: typescript
source: |-
// Note: This endpoint requires a personal access token, not a secret key
// The SDK doesn't currently expose this endpoint, but you can call it directly:
const response = await fetch(
`https://api.trigger.dev/api/v1/deployments/${version}/promote`,
{
method: "POST",
headers: {
"Authorization": `Bearer ${personalAccessToken}`,
"Content-Type": "application/json",
},
}
);
const result = await response.json();
- lang: curl
source: |-
curl -X POST "https://api.trigger.dev/api/v1/deployments/20250228.1/promote" \
-H "Authorization: Bearer your_personal_access_token" \
-H "Content-Type: application/json"

"/api/v1/runs/{runId}/reschedule":
parameters:
- $ref: "#/components/parameters/runId"
Expand Down