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.
labels (optional) tags you can use to categorize and later locate related jobs.
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'

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",
  "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 (TODO: Check)
branch (optional)
outputUrl (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/work_states/{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/work_states/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, will trigger a sync after the connection is created.
paused (optional) boolean; when set, will disable 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
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.
confluence: username, apiToken, url
jiraProject: username, apiToken, url, project
azureBlob: accountName, accountKey, containerName

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

githubApp: installationId
- These must be created via an authentication handshake with github, starting from https://app.doc.holiday.

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,
  "notify": 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,
        "notify": 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
sync (optional) boolean
notify (optional) boolean
paused (optional) boolean

Example Request Body:

{
  "name": "GitHub repository via personal token (updated)",
  "config": {
    "githubAccessToken": {
      "accessToken": "ghp_exampletoken1234567890",
      "repositoryUrl": "sandgardenhq/example",
      "mainBranch": "main"
    }
  },
  "sync": true,
  "notify": false,
  "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"
          }
        },
        "sync": true,
        "notify": false,
        "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

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.
enabled (required) boolean

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

The top-level enabled field is the switch that determines whether the automation is active.

The styleGuide object can include optional releaseNotes and documentation sections. Each section may contain warmth, audience, and additionalInstructions.

Example Request Body:

{
  "name": "Product docs writer",
  "config": {
    "writer": {
      "sourceRepos": [
        "cnn-0000000000001001",
        "cnn-0000000000001002"
      ],
      "docsRepo": "cnn-0000000000002001",
      "styleGuide": {
        "documentation": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Summarize changes in short, factual bullets."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": true,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true
    }
  },
  "enabled": true
}

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": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Summarize changes in short, factual bullets."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": true,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true
    }
  },
  "enabled": true,
  "createdAt": "2026-03-30T14:28:03Z",
  "updatedAt": "2026-03-30T14:28:03Z",
  "deletedAt": null
}

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": {
                "warmth": "polishedProfessional",
                "audience": "technical",
                "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
              },
              "releaseNotes": {
                "warmth": "polishedProfessional",
                "audience": "technical",
                "additionalInstructions": "Summarize changes in short, factual bullets."
              }
            },
            "reactToPullRequests": true,
            "reactToNewIssues": true,
            "reactToIssueComments": true,
            "reactToReleases": true,
            "writeReleaseNotes": true,
            "writeDocumentation": true
          }
        },
        "enabled": true
      }' \
  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": {
              "warmth": "polishedProfessional",
              "audience": "technical",
              "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
            },
            "releaseNotes": {
              "warmth": "polishedProfessional",
              "audience": "technical",
              "additionalInstructions": "Summarize changes in short, factual bullets."
            }
          },
          "reactToPullRequests": true,
          "reactToNewIssues": true,
          "reactToIssueComments": true,
          "reactToReleases": true,
          "writeReleaseNotes": true,
          "writeDocumentation": true
        }
      },
      "enabled": true,
      "createdAt": "2026-03-30T14:28:03Z",
      "updatedAt": "2026-03-30T14:28:03Z",
      "deletedAt": null
    }
  ]
}

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": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Summarize changes in short, factual bullets."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": true,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true
    }
  },
  "enabled": true,
  "createdAt": "2026-03-30T14:28:03Z",
  "updatedAt": "2026-03-30T14:28:03Z",
  "deletedAt": null
}

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
enabled (optional) boolean

Example Request Body:

{
  "name": "Product docs writer (staging)",
  "config": {
    "writer": {
      "sourceRepos": [
        "cnn-0000000000001001"
      ],
      "docsRepo": "cnn-0000000000002001",
      "styleGuide": {
        "documentation": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Summarize changes in short, factual bullets."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": false,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true
    }
  },
  "enabled": false
}

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": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
        },
        "releaseNotes": {
          "warmth": "polishedProfessional",
          "audience": "technical",
          "additionalInstructions": "Summarize changes in short, factual bullets."
        }
      },
      "reactToPullRequests": true,
      "reactToNewIssues": false,
      "reactToIssueComments": true,
      "reactToReleases": true,
      "writeReleaseNotes": true,
      "writeDocumentation": true
    }
  },
  "enabled": false,
  "createdAt": "2026-03-30T14:28:03Z",
  "updatedAt": "2026-03-30T15:12:48Z",
  "deletedAt": null
}

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": {
                "warmth": "polishedProfessional",
                "audience": "technical",
                "additionalInstructions": "Prefer concise API examples and customer-facing terminology."
              },
              "releaseNotes": {
                "warmth": "polishedProfessional",
                "audience": "technical",
                "additionalInstructions": "Summarize changes in short, factual bullets."
              }
            },
            "reactToPullRequests": true,
            "reactToNewIssues": false,
            "reactToIssueComments": true,
            "reactToReleases": true,
            "writeReleaseNotes": true,
            "writeDocumentation": true
          }
        },
        "enabled": false
      }' \
  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

Interacting with Doc Holiday Connections