Skip to content
KontruaDocs
Get started

CI / API Trigger

Start a correction run directly from any CI pipeline.

The API trigger lets you start a correction run from GitHub Actions, GitLab CI, or any shell script. Use it when you want corrections to run on your own schedule rather than on pull request approval. It is available on every plan.

This starts a metered run. Verdicts need no trigger and no token: Kontrua audits a connected repository on connect, on push and on every pull request, for free.

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 SHA-256 hash, so you cannot retrieve it again.

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

Endpoint

Authentication is a bearer token in the Authorization header, and nothing else: no signature, no query parameter, no cookie. The header must read Bearer <token> exactly. Kontrua hashes what you send and looks the hash up; the token identifies one repository, so the request body never names one.

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
}

prHeadBranch is validated too: at most 256 characters, and only letters, digits and . _ - /.

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 default branch with the regenerated artifacts and the corrections it made
Pre-mergeInclude prHeadBranchKontrua commits the updates directly to that branch so the context ships in the same PR as the code

GitHub Actions

.github/workflows/context.yml
name: Update repo context with Kontrua

on:
  push:
    branches: [main]

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

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

.github/workflows/context-pre-merge.yml
name: Update repo context 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.KONTRUA_URL }}/api/trigger \
            -H "Authorization: Bearer ${{ secrets.KONTRUA_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-context:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script:
    - |
      curl -sS -X POST $KONTRUA_URL/api/trigger \
        -H "Authorization: Bearer $KONTRUA_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{
          \"beforeSha\": \"$CI_COMMIT_BEFORE_SHA\",
          \"afterSha\":  \"$CI_COMMIT_SHA\"
        }"

Response

Status codes returned by POST /api/trigger
StatusBodyMeaning
200{ "ok": true, "runId": "...", "runUrl": "..." }Run created and dispatched
400{ "error": "<what is wrong>" }Body is not JSON, a SHA is missing or is not 7 to 40 hex characters, or prHeadBranch is too long or has invalid characters
401{ "error": "Unauthorized" }No Bearer token, or the token is not one Kontrua issued
403{ "error": "Repository is disabled..." }The repository is disabled in the dashboard
429{ "error": "quota_exceeded", "message": "...", "usage": { "runsUsed": 30, "runsLimit": 30 } }Monthly correction allowance is spent. No run is created by this call, so retry once the allowance renews or you upgrade
429{ "error": "Too Many Requests" }Rate limited: 30 requests a minute per token, and 60 a minute across all tokens in the organisation. The Retry-After header says how long to wait

Ready to prove your context is true?

Connect your first repository and Kontrua tells you how much of what your docs claim is still true, before it writes anything.

Get started for freeView pricing