API

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

  1. In the UI, open the Settings page → API Keys.
  2. Click Add API Key.
  3. Enter a Name and optional Expires At value.
  4. 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.

Work History API

The Work History API can be used to poll for information about the Work History log. It is backed by endpoints under /api/v1/work_states.

Work State object

Most Work History endpoints return a Work State object with this shape:

{
  "id": "wst-...",
  "jobId": "job-...",
  "outId": "string",
  "orgId": "org-...",
  "status": "running",
  "publicationId": "aut-...",
  "connectionId": "con-...",
  "publicationName": "My Publication",
  "triggerType": "User Requested",
  "operationType": "assessment_pending",
  "createdAt": "2026-03-31T12:34:56Z",
  "updatedAt": "2026-03-31T12:35:12Z",
  "branch": "string",
  "title": "string",
  "summary": "string",
  "summaryExtended": "string",
  "outputUrl": "string",
  "staged": true,
  "excludedFiles": ["docs/a.md"],
  "entries": [
    {
      "id": "whs-...",
      "orgId": "org-...",
      "requestId": "req-...",
      "publicationId": "aut-...",
      "publicationName": "My Publication",
      "triggerType": "User Requested",
      "status": "running",
      "operationType": "assessment_pending",
      "whOutputId": "string",
      "summary": "string",
      "notes": "string",
      "createdAt": "2026-03-31T12:34:56Z",
      "updatedAt": "2026-03-31T12:35:12Z"
    }
  ]
}

Notes:

  • entries is included on GET /api/v1/work_states/{id} responses.
  • entries is typically omitted in list responses.

List work states

Endpoint: GET /api/v1/work_states

  • Auth: Authorization: Bearer

Query parameters:

  • next (optional): pagination cursor
  • pageSize (optional): items per page
  • orderBy (optional): server-supported sort column
  • ascending (optional): sort direction
  • token (optional): encoded pagination token
  • branch (optional)
  • outputUrl (optional)
  • jobId (optional)
  • publicationId (optional)
  • operationType (optional)
  • status (optional)
  • summary (optional)
  • staged (optional boolean)

cURL Example:

curl -H "Authorization: Bearer <token>" \
  'https://api.doc.holiday/api/v1/work_states?pageSize=50&next=<cursor>'

Sample 200 response (truncated):

{
  "workStates": [
    {
      "id": "wst-...",
      "status": "running",
      "publicationName": "My Publication"
    }
  ],
  "nextPageToken": "..."
}

Get a work state

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

  • Auth: Authorization: Bearer

Returns a Work State object (including entries).

curl -H "Authorization: Bearer <token>" \
  'https://api.doc.holiday/api/v1/work_states/wst-123'

Create a work state

Endpoint: POST /api/v1/work_states/

  • Auth: Authorization: Bearer

Request:

  • body (required): work request text
  • publication (required): publication ID or name
  • relevantLinks (optional): reference links
  • changes (optional): explicit change ranges

cURL Example:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Update docs for this week",
    "publication": "my-publication"
  }' \
  'https://api.doc.holiday/api/v1/work_states/'

Returns 200 with a Work State object.

Add a comment to an existing work state

Endpoint: POST /api/v1/conversations/{id}/comments

  • Auth: Authorization: Bearer

Request:

  • body (required): additional instruction
  • relevantLinks (optional)
  • changes (optional)

cURL Example:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Also include API parameter docs"
  }' \
  'https://api.doc.holiday/api/v1/conversations/wst-123/comments'

Returns 200.

Update a work state

Endpoint: PUT /api/v1/work_states/{id}

  • Auth: Authorization: Bearer

Request:

  • excludedFiles (optional string[])
  • prTitle (optional string)

cURL Example:

curl -X PUT \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "excludedFiles": ["docs/internal-notes.md"]
  }' \
  'https://api.doc.holiday/api/v1/work_states/wst-123'

Returns 200 with a Work State object.

List diffs for a work state

Endpoint: GET /api/v1/work_states/{id}/diffs

  • Auth: Authorization: Bearer

Sample 200 response:

{
  "diffs": [
    {
      "filename": "docs/api.md",
      "additions": 10,
      "deletions": 2,
      "changes": 12,
      "status": "modified",
      "patch": "@@ ..."
    }
  ]
}

Connections API

The Connections API creates and manages connection records for supported providers.

Create a connection

Endpoint: POST /api/v1/connections

Create a connection record. The request body uses a provider-specific config object.

Request:

  • name (required) string
  • config (required) object. In practice, this is where the provider-specific connection settings are supplied
  • sync (optional) boolean; when set, triggers a sync after creation.
  • paused (optional) boolean; when set, pauses background sync jobs for the connection.

Provider-specific config:

Populate exactly one provider configuration from the following within a given request:

  • documentation: url, optional username and password for basic authentication
  • githubApp: installationId
  • githubRepo: githubAppConnectionId, repositoryUrl, optional mainBranch
    • mainBranch will default to main if not specified.
    • githubAppConnectionId must be the doc holiday ID of a githubApp connection.
  • githubAccessToken: accessToken, repositoryUrl, optional mainBranch
  • notion: integrationKey
  • gcp: serviceAccountJSON
  • aws: accessKeyID, secretAccessKey, region
  • linear: apiKey
  • gitlab: projectId, accessToken, optional mainBranch
  • gitlabProvider: accessToken
  • gitlabProject: gitlabProviderConnectionId, projectId, optional mainBranch
  • gitlabProviderConnectionId must be the doc holiday ID of a gitlabProvider connection.
  • bitbucketRepo: workspace, repoSlug, accessToken, optional mainBranch
  • bitbucketProvider: workspace, accessToken
  • bitbucketProject: bitbucketProviderConnectionId, repoSlug, optional mainBranch
    • bitbucketProviderConnectionId must be the doc holiday ID of a bitbucketProvider connection.
  • confluence: username, apiToken, url
  • jiraProject: username, apiToken, url, project
  • azureBlob: accountName, accountKey, containerName
  • zendesk: url, email, apiKey

The following types cannot be functionally created but can be listed:

  • githubApp: installationId

Secret-bearing fields such as tokens, passwords, keys, and service-account JSON are sensitive credentials and should be stored securely by API clients.

Example Request Body:

{
  "name": "GitHub repository via personal token",
  "config": {
    "githubAccessToken": {
      "accessToken": "ghp_exampletoken1234567890",
      "repositoryUrl": "sandgardenhq/example",
      "mainBranch": "main"
    }
  },
  "sync": true,
  "paused": false
}

Example Response:

{
  "id": "cnn-01hzy4m8j2m3n4p5q6r7s8t9u",
  "orgId": "org-49440c77dc13f38d",
  "name": "GitHub repository via personal token",
  "type": "githubAccessToken",
  "config": {
    "githubAccessToken": {
      "accessToken": "ghp_exampletoken1234567890",
      "repositoryUrl": "sandgardenhq/example",
      "mainBranch": "main"
    }
  },
  "healthy": true,
  "paused": false,
  "createdAt": "2026-03-30T14:22:11Z",
  "updatedAt": "2026-03-30T14:22:11Z",
  "deletedAt": null
}

cURL Example:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "GitHub repository via personal token",
        "config": {
          "githubAccessToken": {
            "accessToken": "ghp_exampletoken1234567890",
            "repositoryUrl": "sandgardenhq/example",
            "mainBranch": "main"
          }
        },
        "sync": true,
        "paused": false
      }' \
  https://api.doc.holiday/api/v1/connections

List connections

Endpoint: GET /api/v1/connections

Return a list of connection records for the authenticated user’s organization.

Response:

  • Returns a list of connection records

Example Response:

{
  "connections": [
    {
      "id": "cnn-01hzy4m8j2m3n4p5q6r7s8t9u",
      "orgId": "org-49440c77dc13f38d",
      "name": "GitHub repository via personal token",
      "type": "githubAccessToken",
      "config": {
        "githubAccessToken": {
          "accessToken": "ghp_exampletoken1234567890",
          "repositoryUrl": "sandgardenhq/example",
          "mainBranch": "main"
        }
      },
      "healthy": true,
      "paused": false,
      "createdAt": "2026-03-30T14:22:11Z",
      "updatedAt": "2026-03-30T14:22:11Z",
      "deletedAt": null
    }
  ]
}

cURL Example:

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

Get a connection

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

Return the matching connection record.

Path parameters:

  • id (required) connection ID

Response:

  • Returns the requested connection record

Example Response:

{
  "id": "cnn-01hzy4m8j2m3n4p5q6r7s8t9u",
  "orgId": "org-49440c77dc13f38d",
  "name": "GitHub repository via personal token",
  "type": "githubAccessToken",
  "config": {
    "githubAccessToken": {
      "accessToken": "ghp_exampletoken1234567890",
      "repositoryUrl": "sandgardenhq/example",
      "mainBranch": "main"
    }
  },
  "healthy": true,
  "paused": false,
  "createdAt": "2026-03-30T14:22:11Z",
  "updatedAt": "2026-03-30T14:22:11Z",
  "deletedAt": null
}

cURL Example:

curl -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/connections/cnn-01hzy4m8j2m3n4p5q6r7s8t9u

Update a connection

Endpoint: PUT /api/v1/connections/{id}

Update an existing connection record.

Path parameters:

  • id (required) connection ID

Request:

  • name (optional) string
  • config (optional) object
  • paused (optional) boolean

Example Request Body:

{
  "name": "GitHub repository via personal token (updated)",
  "config": {
    "githubAccessToken": {
      "accessToken": "ghp_exampletoken1234567890",
      "repositoryUrl": "sandgardenhq/example",
      "mainBranch": "main"
    }
  },
  "paused": true
}

Example Response:

{
  "id": "cnn-01hzy4m8j2m3n4p5q6r7s8t9u",
  "orgId": "org-49440c77dc13f38d",
  "name": "GitHub repository via personal token (updated)",
  "type": "githubAccessToken",
  "config": {
    "githubAccessToken": {
      "accessToken": "ghp_exampletoken1234567890",
      "repositoryUrl": "sandgardenhq/example",
      "mainBranch": "main"
    }
  },
  "healthy": true,
  "paused": true,
  "createdAt": "2026-03-30T14:22:11Z",
  "updatedAt": "2026-03-30T15:03:44Z",
  "deletedAt": null
}

cURL Example:

curl -X PUT \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "GitHub repository via personal token (updated)",
        "config": {
          "githubAccessToken": {
            "accessToken": "ghp_exampletoken1234567890",
            "repositoryUrl": "sandgardenhq/example",
            "mainBranch": "main"
          }
        },
        "paused": true
      }' \
  https://api.doc.holiday/api/v1/connections/cnn-01hzy4m8j2m3n4p5q6r7s8t9u

Delete a connection

Endpoint: DELETE /api/v1/connections/{id}

Remove the specified connection record.

Path parameters:

  • id (required) connection ID

Response:

  • Returns a success-oriented response when the connection is removed

Example Response:

{
  "success": true
}

cURL Example:

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/connections/cnn-01hzy4m8j2m3n4p5q6r7s8t9u

Sync a connection

Endpoint: POST /api/v1/connections/{id}/sync

Start syncing background information for the specified connection.

Path parameters:

  • id (required) connection ID

Response:

  • Returns a success-oriented response for the sync request

Example Response:

{
  "success": true
}

cURL Example:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/connections/cnn-01hzy4m8j2m3n4p5q6r7s8t9u/sync

List Bitbucket repositories

Endpoint: GET /api/v1/bitbucket/repos

List repositories available to a Bitbucket workspace access token. This endpoint supports repository discovery for bitbucketProvider and bitbucketProject connection setup.

Query parameters:

  • workspace (required) Bitbucket workspace slug
  • token (required) Bitbucket workspace access token

Example Response:

{
  "repos": [
    {
      "slug": "example-repo",
      "fullName": "workspace/example-repo"
    }
  ]
}

cURL Example:

curl -H "Authorization: Bearer <token>" \
  'https://api.doc.holiday/api/v1/bitbucket/repos?workspace=my-workspace&token=<bitbucket-workspace-token>'

Get connection health

Endpoint: GET /api/v1/connections/{id}/health

Check whether a connection is healthy and can be successfully used.

Path parameters:

  • id (required) connection ID

Response:

  • Returns whether the requested connection can be used successfully or whether there is some configuration error.

Example Response:

{
  "status": "unhealthy",
  "message": "an error message encountered when checking the connection"
}

cURL Example:

curl -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/connections/cnn-01hzy4m8j2m3n4p5q6r7s8t9u/health

Automations API

The Automations API creates and manages automation records.

NOTE - Automations within the Doc Holiday UI have been renamed Publications. Whenever interacting with an Automation, please remember that it refers to Publications. This naming conflict will be updated in a future release.

Create an automation

Endpoint: POST /api/v1/automations

Create an automation record.

Request:

  • name (required) string
  • config (optional) object supporting multiple types of automation; writer is the only valid key currently.

Underneath config.writer:

  • sourceRepos connection IDs the automation listens to for changes
  • docsRepo connection ID for the documentation repository to update
  • styleGuide optional style guide settings object
  • reactToPullRequests boolean
  • reactToNewIssues boolean
  • reactToIssueComments boolean
  • reactToReleases boolean
  • writeReleaseNotes boolean
  • writeDocumentation boolean
  • writeChangelogs boolean
  • prCommitInstructions optional string
  • planningInstructions optional string

The styleGuide object can include optional releaseNotes, documentation, and changelogs sections. Each section supports additionalInstructions.

Example Request Body:

{
  "name": "Product docs writer",
  "config": {
    "writer": {
      "sourceRepos": [
        "cnn-0000000000001001",
        "cnn-0000000000001002"
      ],
      "docsRepo": "cnn-0000000000002001",
      "styleGuide": {
        "documentation": {
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "additionalInstructions": "Summarize changes in short, factual bullets."
        },
        "changelogs": {
          "additionalInstructions": "Keep entries concise and chronological."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": true,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true,
      "writeChangelogs": true,
      "prCommitInstructions": "Use short imperative commit messages.",
      "planningInstructions": "Prefer updating existing pages before creating new ones."
    }
  }
}

Example Response:

{
  "id": "aut-01hzy4p1v2w3x4y5z6a7b8c9d",
  "orgId": "org-49440c77dc13f38d",
  "name": "Product docs writer",
  "type": "writer",
  "config": {
    "writer": {
      "sourceRepos": [
        "cnn-0000000000001001",
        "cnn-0000000000001002"
      ],
      "docsRepo": "cnn-0000000000002001",
      "styleGuide": {
        "documentation": {
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "additionalInstructions": "Summarize changes in short, factual bullets."
        },
        "changelogs": {
          "additionalInstructions": "Keep entries concise and chronological."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": true,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true,
      "writeChangelogs": true,
      "prCommitInstructions": "Use short imperative commit messages.",
      "planningInstructions": "Prefer updating existing pages before creating new ones."
    }
  },
  "healthy": true,
  "createdAt": "2026-03-30T14:28:03Z",
  "updatedAt": "2026-03-30T14:28:03Z"
}

cURL Example:

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Product docs writer",
        "config": {
          "writer": {
            "sourceRepos": [
              "cnn-0000000000001001",
              "cnn-0000000000001002"
            ],
            "docsRepo": "cnn-0000000000002001",
            "styleGuide": {
              "documentation": {
                "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
              },
              "releaseNotes": {
                "additionalInstructions": "Summarize changes in short, factual bullets."
              },
              "changelogs": {
                "additionalInstructions": "Keep entries concise and chronological."
              }
            },
            "reactToPullRequests": true,
            "reactToNewIssues": true,
            "reactToIssueComments": true,
            "reactToReleases": true,
            "writeReleaseNotes": true,
            "writeDocumentation": true,
            "writeChangelogs": true,
            "prCommitInstructions": "Use short imperative commit messages.",
            "planningInstructions": "Prefer updating existing pages before creating new ones."
          }
        }
      }' \
  https://api.doc.holiday/api/v1/automations

List automations

Endpoint: GET /api/v1/automations

Return a list of automation records for the authenticated user’s organization.

Response:

  • Returns a list of automation records

Example Response:

{
  "automations": [
    {
      "id": "aut-01hzy4p1v2w3x4y5z6a7b8c9d",
      "orgId": "org-49440c77dc13f38d",
      "name": "Product docs writer",
      "type": "writer",
      "healthy": true,
      "config": {
        "writer": {
          "sourceRepos": [
            "cnn-0000000000001001",
            "cnn-0000000000001002"
          ],
          "docsRepo": "cnn-0000000000002001",
          "styleGuide": {
            "documentation": {
              "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
            },
            "releaseNotes": {
              "additionalInstructions": "Summarize changes in short, factual bullets."
            },
            "changelogs": {
              "additionalInstructions": "Keep entries concise and chronological."
            }
          },
          "reactToPullRequests": true,
          "reactToNewIssues": true,
          "reactToIssueComments": true,
          "reactToReleases": true,
          "writeReleaseNotes": true,
          "writeDocumentation": true,
          "writeChangelogs": true,
          "prCommitInstructions": "Use short imperative commit messages.",
          "planningInstructions": "Prefer updating existing pages before creating new ones."
        }
      },
      "createdAt": "2026-03-30T14:28:03Z",
      "updatedAt": "2026-03-30T14:28:03Z"
    }
  ]
}

cURL Example:

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

Get an automation

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

Return the matching automation record.

Path parameters:

  • id (required) automation ID

Response:

  • Returns the requested automation record

Example Response:

{
  "id": "aut-01hzy4p1v2w3x4y5z6a7b8c9d",
  "orgId": "org-49440c77dc13f38d",
  "name": "Product docs writer",
  "type": "writer",
  "healthy": true,
  "config": {
    "writer": {
      "sourceRepos": [
        "cnn-0000000000001001",
        "cnn-0000000000001002"
      ],
      "docsRepo": "cnn-0000000000002001",
      "styleGuide": {
        "documentation": {
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "additionalInstructions": "Summarize changes in short, factual bullets."
        },
        "changelogs": {
          "additionalInstructions": "Keep entries concise and chronological."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": true,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true,
      "writeChangelogs": true,
      "prCommitInstructions": "Use short imperative commit messages.",
      "planningInstructions": "Prefer updating existing pages before creating new ones."
    }
  },
  "createdAt": "2026-03-30T14:28:03Z",
  "updatedAt": "2026-03-30T14:28:03Z"
}

cURL Example:

curl -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/automations/aut-01hzy4p1v2w3x4y5z6a7b8c9d

Update an automation

Endpoint: PUT /api/v1/automations/{id}

Update an existing automation record.

Path parameters:

  • id (required) automation ID

Request:

  • name (optional) string
  • config (optional) object

Example Request Body:

{
  "name": "Product docs writer (staging)",
  "config": {
    "writer": {
      "sourceRepos": [
        "cnn-0000000000001001"
      ],
      "docsRepo": "cnn-0000000000002001",
      "styleGuide": {
        "documentation": {
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "additionalInstructions": "Summarize changes in short, factual bullets."
        },
        "changelogs": {
          "additionalInstructions": "Keep entries concise and chronological."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": false,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true,
      "writeChangelogs": true,
      "prCommitInstructions": "Use short imperative commit messages.",
      "planningInstructions": "Prefer updating existing pages before creating new ones."
    }
  }
}

Example Response:

{
  "id": "aut-01hzy4p1v2w3x4y5z6a7b8c9d",
  "orgId": "org-49440c77dc13f38d",
  "name": "Product docs writer (staging)",
  "type": "writer",
  "healthy": true,
  "config": {
    "writer": {
      "sourceRepos": [
        "cnn-0000000000001001"
      ],
      "docsRepo": "cnn-0000000000002001",
      "styleGuide": {
        "documentation": {
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "additionalInstructions": "Summarize changes in short, factual bullets."
        },
        "changelogs": {
          "additionalInstructions": "Keep entries concise and chronological."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": false,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true,
      "writeChangelogs": true,
      "prCommitInstructions": "Use short imperative commit messages.",
      "planningInstructions": "Prefer updating existing pages before creating new ones."
    }
  },
  "createdAt": "2026-03-30T14:28:03Z",
  "updatedAt": "2026-03-30T15:12:48Z"
}

cURL Example:

curl -X PUT \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Product docs writer (staging)",
        "config": {
          "writer": {
            "sourceRepos": [
              "cnn-0000000000001001"
            ],
            "docsRepo": "cnn-0000000000002001",
            "styleGuide": {
              "documentation": {
                "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
              },
              "releaseNotes": {
                "additionalInstructions": "Summarize changes in short, factual bullets."
              },
              "changelogs": {
                "additionalInstructions": "Keep entries concise and chronological."
              }
            },
            "reactToPullRequests": true,
            "reactToNewIssues": false,
            "reactToIssueComments": true,
            "reactToReleases": true,
            "writeReleaseNotes": true,
            "writeDocumentation": true,
            "writeChangelogs": true,
            "prCommitInstructions": "Use short imperative commit messages.",
            "planningInstructions": "Prefer updating existing pages before creating new ones."
          }
        }
      }' \
  https://api.doc.holiday/api/v1/automations/aut-01hzy4p1v2w3x4y5z6a7b8c9d

Delete an automation

Endpoint: DELETE /api/v1/automations/{id}

Remove the specified automation record.

Path parameters:

  • id (required) automation ID

Response:

  • Removes the automation record for the specified ID

Example Response:

{
  "success": true
}

cURL Example:

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/automations/aut-01hzy4p1v2w3x4y5z6a7b8c9d

Get automation health

Endpoint: GET /api/v1/automations/{id}/health

Check whether an automation is healthy and can be successfully used.

Path parameters:

  • id (required) connection ID

Response:

  • Returns whether the requested automation can be successfully used, or whether there is a configuration error.

Example Response:

{
  "status": "unhealthy",
  "message": "an error message encountered when checking the automation"
}

cURL Example:

curl -H "Authorization: Bearer <token>" \
  https://api.doc.holiday/api/v1/automations/aut-01hzy4p1v2w3x4y5z6a7b8c9d/health

Jobs API

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

Note: The Jobs endpoint is deprecated and Doc Holiday will remove it in a future release.

Create a job

Endpoint: POST /api/v1/jobs

Create a job to write or edit documentation.

Request:

  • title (optional) the title of your request. Doc Holiday uses it for naming pull requests and commits.
  • body (optional) the main writing request.
  • comments (optional) additional instructions for the request.
  • labels (optional) tags for categorizing related jobs and work.
  • time (optional) the request time.
  • relevantLinks (optional) links Doc Holiday should read before writing.
  • changes (optional) explicit change ranges to analyze. Values here override changes implied in body.
  • stage (optional) stage the work without immediately opening a pull request.
  • addTo (optional) append the work to an existing or staged pull request.
  • eventType (optional) identify the event that triggered the request, such as release or merge.
  • publications (optional) target publications by ID or name.
  • sourceConnection (optional) identify the connection to use for commit references by ID or name.
  • turn (optional) associate the request with an existing interactive turn.

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",
    "relevantLinks": [
      "https://github.com/sandgardenhq/mono/pull/5278"
    ],
    "publications": ["my-publication"],
    "sourceConnection": "github-conn-1",
    "stage": true
  }
}

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'
InteractionsConnections