> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployments API

REST API endpoints for listing deployments, triggering builds, and checking deployment status.

## Overview

The Deployments API provides programmatic access to your project's build and deployment pipeline. Use it to trigger builds, check status, and list deployment history.

**Base path:** `https://api.holydocs.com/api/v1/deployments`

## List Deployments

Retrieve deployments for a project, ordered by most recent first.

```bash
GET /api/v1/deployments?projectId=PROJECT_ID
```

Copy as context

**cURL**

```bash
    curl "https://api.holydocs.com/api/v1/deployments?projectId=$PROJECT_ID" \
      -H "Authorization: Bearer $HOLYDOCS_API_KEY"
    ```
  **CLI**

```bash
    holydocs status --project $PROJECT_ID
    ```
  **SDK**

```ts
    import { HolyDocs } from '@holydocs/sdk';
    const client = new HolyDocs({ apiKey: process.env.HOLYDOCS_API_KEY });
    const { data: deployments } = await client.deployments.list({ projectId });
    ```

### Query Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `projectId` | string | Yes | Project ID to list deployments for |
| `page` | number | No | Page number (default: 1) |
| `perPage` | number | No | Results per page (default: 20, max: 100) |

### Response

```json
{
  "data": [
    {
      "id": "dep_abc123",
      "projectId": "proj_xyz",
      "status": "success",
      "commitSha": "a1b2c3d4e5f6",
      "branch": "main",
      "message": "Update API reference",
      "pagesBuilt": 42,
      "buildDuration": 15000,
      "createdAt": 1708200000000,
      "completedAt": 1708200015000
    },
    {
      "id": "dep_def456",
      "projectId": "proj_xyz",
      "status": "failed",
      "commitSha": "b2c3d4e5f6g7",
      "branch": "main",
      "error": "Invalid docs.json: colors.primary must be a hex color",
      "createdAt": 1708100000000,
      "completedAt": 1708100003000
    }
  ],
  "meta": {
    "total": 87,
    "page": 1,
    "perPage": 20,
    "totalPages": 5
  }
}
```

## Get Deployment

Retrieve details of a specific deployment.

```bash
GET /api/v1/deployments/:deploymentId
```

### Response

```json
{
  "data": {
    "id": "dep_abc123",
    "projectId": "proj_xyz",
    "status": "success",
    "commitSha": "a1b2c3d4e5f6",
    "branch": "main",
    "message": "Update API reference",
    "pagesBuilt": 42,
    "assetsUploaded": 15,
    "buildDuration": 15000,
    "indexDuration": 3400,
    "createdAt": 1708200000000,
    "completedAt": 1708200015000,
    "logs": [
      { "timestamp": 1708200001000, "level": "info", "message": "Build started" },
      { "timestamp": 1708200005000, "level": "info", "message": "Processed 42 pages" },
      { "timestamp": 1708200012000, "level": "info", "message": "Assets uploaded to R2" },
      { "timestamp": 1708200015000, "level": "info", "message": "Deployment complete" }
    ]
  }
}
```

## Trigger Deployment

Manually trigger a new deployment for a project.

```bash
POST /api/v1/deployments
```

### Request Body

```json
{
  "projectId": "proj_xyz",
  "branch": "main"
}
```

### Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `projectId` | string | Yes | Project to deploy |
| `branch` | string | No | Branch to deploy from (default: project's configured branch) |

### Response

```json
{
  "data": {
    "id": "dep_new789",
    "projectId": "proj_xyz",
    "status": "queued",
    "branch": "main",
    "createdAt": 1708200500000
  }
}
```

Deployments are processed asynchronously. The API returns immediately with status `queued`. Poll the deployment endpoint or use webhooks to track progress.

## Deployment Statuses

| Status | Description |
|---|---|
| `queued` | Job is in the build queue |
| `building` | Build is in progress |
| `success` | Build completed and content is live |
| `failed` | Build failed — check the `error` field |
| `cancelled` | Deployment was cancelled |

## Polling for Status

To wait for a deployment to complete, poll the GET endpoint:

```javascript
async function waitForDeployment(deploymentId, apiKey) {
  while (true) {
    const response = await fetch(
      `https://api.holydocs.com/api/v1/deployments/${deploymentId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const { data } = await response.json();

    if (data.status === 'success') return data;
    if (data.status === 'failed') throw new Error(data.error);

    // Wait 2 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}
```

## Webhook Alternative

Instead of polling, subscribe to deployment events via outbound webhooks:

```json
{
  "url": "https://your-server.com/hooks",
  "events": ["deployment.completed", "deployment.failed"]
}
```

See [Webhooks](/webhooks) for setup details.

## Error Codes

| Code | Status | Description |
|---|---|---|
| `NOT_FOUND` | 404 | Deployment or project not found |
| `VALIDATION_ERROR` | 400 | Missing `projectId` parameter |
| `LIMIT_EXCEEDED` | 429 | Daily build limit reached |