Deployments API

Programmatically manage your application deployments. Create, monitor, cancel, and audit deployments directly from your scripts, CI/CD pipelines, or internal tools.

⚡ The Deployments API requires deploy:write or deploy:admin scope. Read-only access grants deploy:read.

Authentication

All requests must include a valid API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Generate tokens in your dashboard under Settings → API Keys. Tokens are scoped per project and environment.

Base URL

All endpoints are relative to:

https://api.git.dev/v1

Rate Limits

Plan	Requests/min	Burst
Starter	100	20
Pro	1,000	200
Enterprise	Unlimited	Configurable

Rate limit headers are included in every response:
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints

POST /deployments Create a new deployment

Triggers a new deployment for the specified project and branch.

Request Body

Parameter	Type	Description
project_id Required	string	UUID of the target project
branch Required	string	Source branch name (e.g., `main`)
commit_sha Optional	string	Specific commit to deploy (defaults to branch HEAD)
env_vars Optional	object	Key-value pairs for runtime environment variables

curl -X POST https://api.git.dev/v1/deployments \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_8f3k29",
    "branch": "main",
    "commit_sha": "a1b2c3d4e5f6",
    "env_vars": { "NODE_ENV": "production" }
  }'

import requests

response = requests.post(
    "https://api.git.dev/v1/deployments",
    headers={"Authorization": "Bearer sk_live_xxxx"},
    json={
        "project_id": "proj_8f3k29",
        "branch": "main",
        "commit_sha": "a1b2c3d4e5f6"
    }
)
print(response.json())

const fetch = require('node-fetch');

fetch('https://api.git.dev/v1/deployments', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_xxxx' },
  body: JSON.stringify({ project_id: 'proj_8f3k29', branch: 'main' })
})
.then(res => res.json())
.then(console.log);

Response (201 Created)

{
  "id": "dep_9x2m4p",
  "status": "queued",
  "project_id": "proj_8f3k29",
  "branch": "main",
  "commit_sha": "a1b2c3d4e5f6",
  "created_at": "2025-03-14T10:32:00Z",
  "url": "https://dep_9x2m4p.git.dev"
}

GET /deployments List deployments

Returns a paginated list of deployments for the authenticated project.

Query Parameters

Parameter	Type	Description
limit Optional	integer	Number of results (default: 20, max: 100)
offset Optional	integer	Pagination cursor
status Optional	string	Filter by status: `queued`, `building`, `deploying`, `success`, `failed`

Response (200 OK)

{
  "data": [
    {
      "id": "dep_9x2m4p",
      "status": "success",
      "branch": "main",
      "created_at": "2025-03-14T10:32:00Z"
    }
  ],
  "meta": {
    "total": 142,
    "limit": 20,
    "offset": 0
  }
}

GET /deployments/:id Get deployment details

Retrieve full details for a specific deployment including build logs, metrics, and rollback status.

Response (200 OK)

{
  "id": "dep_9x2m4p",
  "status": "success",
  "project_id": "proj_8f3k29",
  "branch": "main",
  "commit_sha": "a1b2c3d4e5f6",
  "build_duration": "14.2s",
  "deploy_url": "https://dep_9x2m4p.git.dev",
  "logs_url": "https://api.git.dev/v1/deployments/dep_9x2m4p/logs",
  "created_at": "2025-03-14T10:32:00Z",
  "completed_at": "2025-03-14T10:32:14Z"
}

PATCH /deployments/:id/cancel Cancel deployment

Stops a deployment currently in queued, building, or deploying state. Cannot be undone.

Response (200 OK)

{
  "id": "dep_9x2m4p",
  "status": "cancelled",
  "cancelled_by": "user_7k2m",
  "cancelled_at": "2025-03-14T10:35:00Z"
}

DELETE /deployments/:id Delete deployment record

Permanently removes the deployment from your project history. The hosted URL becomes inaccessible immediately.

Response (204 No Content)

// Empty response body

Error Handling

The API uses standard HTTP status codes and returns detailed error objects:

Code	Meaning	Common Cause
400	Bad Request	Missing required fields or invalid JSON
401	Unauthorized	Invalid or expired API token
404	Not Found	Deployment or project ID does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	.git infrastructure issue (auto-retried)

{
  "error": {
    "code": "invalid_branch",
    "message": "Branch 'develop' does not exist in repository",
    "details": { "project_id": "proj_8f3k29" }
  }
}