Pith - AI-powered documentation

CI / API Trigger

Trigger documentation runs directly from any CI pipeline.

The API trigger lets you invoke Pith from GitHub Actions, GitLab CI, or any shell script. This is useful if you want Pith 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. Pith 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

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

Mode	How to use	Result
Post-merge	Omit `prHeadBranch`	Pith opens a separate PR targeting your main branch with the updated docs
Pre-merge	Include `prHeadBranch`	Pith 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 Pith

on:
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Pith
        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 Pith (pre-merge)

on:
  pull_request:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Pith
        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

Status	Body	Meaning
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 Pith will handle the rest.

Get started for free View pricing