API – Doc Holiday Documentation

API

Doc Holiday’s API allows for easy integration into any release pipeline!

You can:

Ask Doc Holiday to create release notes and/or documentation updates for one or more publications.
Poll a job to track its state: requested → running → done or errored.
List jobs to review recent activity.

Authentication

Doc Holiday uses the standard HTTP Authorization header along with API keys to authenticate. Every call to the Doc Holiday API requires authentication.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" 
  ...

Creating an API key

In the UI, open the Settings page → API Keys.
Click Add API Key.
Enter a Name and optional Expires At value.
Create the key, then copy the token shown on creation and store it in your secret manager. The token cannot be retrieved later within the UI.

Jobs API

The Jobs API can be used to trigger and monitor Doc Holiday’s work.

Create a job

Endpoint: POST /api/v1/jobs

Create a job to write or edit documentation.

Request:

title (required) the title of your request. Doc will use this to name PRs and commits.
body (required) your request to Doc for what you want written.
comments (optional) any additional requests to doc.
publications (optional) the publications to target.
sourceConnection (required) the connection initiating the request (this will be used for commit references).
relevantLinks (optional) links to additional content for doc to read (from any connection that Doc can read or any publicly available HTTP link).
eventType (optional) supply either “release” or “merge” to force Doc Holiday to only write release notes and documentation updates for this request. The body contents will be used for context and all other instructions will be ignored.
changes (optional) provide an explicit list of change ranges for Doc Holiday to analyze with this request. Changes specified in the body will be ignored.

Example Request Body:

{
  "docRequest": {
    "title": "Update docs for last week",
    "body": "Generate guides for recent commits.",
    "comments": [
      "Include API changes",
      "Prefer updating existing guides"
    ],
    "labels": ["docs", "automation"],
    "time": "2025-10-29T15:00:00Z",
    "publications": ["my-publication"],
    "sourceConnection": "github-conn-1"
  }
}

Example Response:

{
  "id": "job-…",
  "orgId": "org-…",
  "type": "doc-request",
  "state": "requested"
}

cURL Example:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "docRequest": {
          "title": "Weekly docs",
          "publications": ["my-publication"],
          "labels": ["weekly"],
          "body": "Write new documentation for the last week, focusing on user facing changes"
        }
      }' \
  https://api.doc.holiday/api/v1/jobs

Commit Selection and Ranges:

Specific commits: “for commits abc123, def456, 3099d2c”
Since a commit: “since abc123”
From one commit to another: “from abc123 to def456”
Last N commits: “last 10 commits”
Time windows: “past week”, “since last month”, “for Q3”

Example:

{
  "docRequest": {
    "title": "Update docs",
    "body": "Update documentation for commits from 017df07d to 3099d2c6",
    "publications": ["my-publication"],
    "sourceConnection": "github-conn-1"
  }
}

The changes specified in changes must be in one of the following formats (provide only one). Changes specified here will override any changes specified in the body:

Releases
- {"releases": {"count": 2}} → use commits from the last 2 releases
Time range
- {"timeRange": {"start": "2006-01-02T15:04:05Z", "end": "2006-01-02T17:04:05Z"}}
Commit count
- {"commits": {"count": 10}} → use the last 10 commits on the main branch
Since commit SHA
- {"commits": {"startSha": "abc123"}} → use commits from abc123 up to the current head
Specific commits
- {"commits": {"shas": ["abc123", "def456"]}}
Commit range
- {"commits": {"startSha": "abc123", "endSha": "def456", "includeStartCommit": true}}
Since tag
- {"tags": {"start": "v1.2.3"}} → use commits from tag v1.2.3 to the current head
Tag range
- {"tags": {"start": "v1.2.3", "end": "v1.2.4"}}

Example:

{
  "docRequest": {
    "title": "Update docs",
    "eventType": "release",
    "changes": [{
        "releases": {"count": 1}
    },{
        "commits": {"shas": ["mysha"]}
    }],
    "publications": ["my-publication"],
    "sourceConnection": "github-conn-1"
  }
}

Targeting publications and connections:

The publications field accepts publication IDs or names. If a name is passed that matches more than one publication, the request will fail. In that case, use an ID instead.
The sourceConnection field accepts a connection ID or name. If publications are omitted and sourceConnection set, the job will run for all publications associated with that connection.
If a publication uses multiple source repositories and sourceConnection is omitted, the request will fail.

Get a job

Endpoint: GET /api/v1/jobs/{id}

Auth: Authorization: Bearer
Returns 200 with the job.

Job states:

requested: accepted and queued
running: in progress
done: completed successfully
errored: failed; check activity logs in the app

curl -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/jobs/job-abcdef0123456789

List jobs

Endpoint: GET /api/v1/jobs

Auth: Authorization: Bearer
Returns 200 with a paginated list of jobs and an optional nextPageToken.

Example:

curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  https://api.doc.holiday/api/v1/jobs

Sample 200 response (truncated):

{"jobs":[
  {"id":"job-0000000000007118","orgId":"org-49440c77dc13f38d","state":"done"},
  {"id":"job-0000000000007117","orgId":"org-49440c77dc13f38d","state":"done"},
  {"id":"job-00000000000070de","orgId":"org-49440c77dc13f38d","state":"done"},
], "nextPageToken":"28361"}

Example Using nextPageToken:

curl -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  'https://api.doc.holiday/api/v1/jobs?next=28361'

Interacting with Doc Holiday Connections