Deployments API

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

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

bash
holydocs status --project $PROJECT_ID

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

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

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

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 for setup details.

Error Codes