KontruaDocs
Get started

CI / API Trigger

Trigger documentation runs directly from any CI pipeline.

The API trigger lets you invoke Kontrua from GitHub Actions, GitLab CI, or any shell script. This is useful if you want Kontrua to run on every push rather than on PR approval, or if you prefer to control the trigger yourself.

Create an API token

API tokens are per-repository. Go to Dashboard - [your repo] - Integration and click Generate token. The raw token is shown once - copy it immediately. Kontrua stores only a hash, so you cannot retrieve it again.

Store the token as a secret in your CI environment (PITH_API_TOKEN). Never commit it to your repository.

Endpoint

POST /api/trigger
POST /api/trigger
Authorization: Bearer <token>
Content-Type: application/json

{
  "beforeSha": "<parent-commit-sha>",   // required - 7-40 hex chars
  "afterSha":  "<head-commit-sha>",     // required - 7-40 hex chars
  "prHeadBranch": "<branch-name>"       // optional - enables pre-merge mode
}

Post-merge vs pre-merge mode

Kontrua supports two delivery modes controlled by whether you include prHeadBranch in the request:

ModeHow to useResult
Post-mergeOmit prHeadBranchKontrua opens a separate PR targeting your main branch with the updated docs
Pre-mergeInclude prHeadBranchKontrua commits the updated docs directly to that branch so docs ship in the same PR

GitHub Actions

.github/workflows/docs.yml
name: Update docs with Kontrua

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Kontrua
        run: |
          curl -sS -X POST ${{ vars.PITH_URL }}/api/trigger \
            -H "Authorization: Bearer ${{ secrets.PITH_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "beforeSha": "${{ github.event.before }}",
              "afterSha":  "${{ github.sha }}"
            }'

For pre-merge mode (docs included in the same PR):

.github/workflows/docs-pre-merge.yml
name: Update docs with Kontrua (pre-merge)

on:
  pull_request:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Kontrua
        run: |
          curl -sS -X POST ${{ vars.PITH_URL }}/api/trigger \
            -H "Authorization: Bearer ${{ secrets.PITH_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "beforeSha":    "${{ github.event.pull_request.base.sha }}",
              "afterSha":     "${{ github.event.pull_request.head.sha }}",
              "prHeadBranch": "${{ github.head_ref }}"
            }'

GitLab CI

.gitlab-ci.yml
update-docs:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - |
      curl -sS -X POST $PITH_URL/api/trigger \
        -H "Authorization: Bearer $PITH_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{
          \"beforeSha\": \"$CI_COMMIT_BEFORE_SHA\",
          \"afterSha\":  \"$CI_COMMIT_SHA\"
        }"

Response

StatusBodyMeaning
200{ "ok": true, "runId": "...", "runUrl": "..." }Run created successfully
200{ "error": "quota_exceeded", "usage": {...} }Monthly limit reached - run is queued
401{ "error": "unauthorized" }Token missing or invalid
429{ "error": "rate_limit" }Too many requests (30 req/min per token)

Ready to stop writing docs by hand?

Connect your first repository and Kontrua will handle the rest.

Get started for freeView pricing