promote deployment api

Author: isshaddad

docs/docs.json

@@ -269,6 +269,10 @@
               "management/envvars/update",
               "management/envvars/delete"
             ]
+          },
+          {
+            "group": "Deployments API",
+            "pages": ["management/deployments/promote"]
           }
         ]
       },

docs/management/deployments/promote.mdx

@@ -0,0 +1,4 @@
+---
+title: "Promote deployment"
+openapi: "v3-openapi POST /api/v1/deployments/{version}/promote"
+---

docs/v3-openapi.yaml

@@ -505,6 +505,74 @@ paths:
 
             await runs.cancel("run_1234");
 
+  "/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"