Builds API / Triggers

Use the Builds API to trigger documentation rebuilds without pushing new commits. This is useful for CI pipelines, scheduled rebuilds, or content generated outside your docs directory.

Authentication

All requests use a project API key:

Authorization: Bearer YOUR_API_KEY

Find your API key in Settings → API for the project.

Trigger a Rebuild

POST https://api.jamdesk.com/projects/{project_id}/rebuild

Example Request

curl -X POST "https://api.jamdesk.com/projects/YOUR_PROJECT_ID/rebuild" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Successful requests return 200 OK with build metadata you can use to track progress.

{
  "buildId": "build_8f3k2j",
  "status": "queued",
  "createdAt": "2026-02-05T10:30:00Z",
  "commit": {
    "sha": "a1b2c3d",
    "message": "Update API docs",
    "author": "jane@example.com"
  },
  "project": {
    "id": "proj_abc123",
    "name": "My Docs"
  }
}

If you receive a 429 response, retry with exponential backoff. Contact support if you need higher limits.

Response Fields

buildIdstring

Unique build identifier. Use this to reference the build in the dashboard.

statusstring

Current build status. One of: queued, building, deployed, failed.

createdAtstring

ISO 8601 timestamp of when the build was created.

commit.shastring

Short commit hash that triggered the build.

commit.messagestring

Commit message from the source repository.

commit.authorstring

Email address of the commit author.

project.idstring

Project identifier matching your dashboard project.

project.namestring

Display name of the project.

Tracking Build Status

Build status is visible in the dashboard under Deployments. Each build moves through these stages:

queued -- The build is waiting in the queue.
building -- The build service is compiling your documentation.
deployed -- The build completed and your site is live.
failed -- Something went wrong. Check the build logs for details.

If your repository is connected to GitHub, commit status checks update automatically. A green check appears on the commit when the build deploys, or a red X if the build fails. You do not need to poll the API for status updates.

Error Response Format

Error responses follow a consistent structure:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "status": 401
  }
}

error.codestring

Machine-readable error code. See the table below for possible values.

error.messagestring

Human-readable description of what went wrong.

error.statusnumber

HTTP status code matching the response status.

Error Codes

Status	Code	Message	Fix
401	`unauthorized`	Invalid API key	Regenerate the key in Settings → API
403	`forbidden`	Unauthorized project access	Confirm the project ID matches the API key's project
404	`project_not_found`	Project not found	Verify the project ID in the dashboard
429	`rate_limited`	Too many requests	Back off and retry with exponential backoff
500	`internal_error`	Internal server error	Retry after a few seconds. Contact support if it persists

Triggering Builds

Manual and automatic build triggers

Monitoring Builds

Track build status and queue