POST /api/apps/{appId}/trigger

Schedule a new check for an app. The check is queued immediately and the response returns the new check ID so you can poll for results.

Authentication

Send a per-app API key as a Bearer token. See API authentication.

Request

POST /api/apps/{appId}/trigger HTTP/1.1
Host: qassandra.com
Authorization: Bearer qsk_...
Content-Type: application/json

{
  "git_commit_id": "abc123",
  "git_commit_message": "Fix login bug",
  "pull_request_id": "42",
  "pull_request_name": "Feature: Add dark mode",
  "branch": "feature/dark-mode",
  "discover_flows": true
}

Body parameters

All parameters are optional. An empty body is valid and triggers a default check.

Field	Type	Description
`git_commit_id`	string	The commit SHA being tested. Shown in the UI for traceability.
`git_commit_message`	string	The commit message. Used by the flow selector for relevance ranking.
`pull_request_id`	string	The PR number / identifier in your VCS.
`pull_request_name`	string	The PR title. Strongly recommended — the flow selector uses this heavily.
`branch`	string	The branch under test. Used for visual diff baseline lookup (a check on `main` becomes the next baseline).
`discover_flows`	boolean	Run an explicit flow discovery pass alongside execution. Defaults to `false` for apps that already have flows; bootstrap mode kicks in automatically for apps with zero flows.

Successful response

{
  "message": "Check triggered successfully",
  "check_id": "9f5c8b1e-...",
  "app_id": "8d4c2a91-...",
  "app_name": "myapp-prod",
  "status": "scheduled",
  "metadata": {
    "git_commit_id": "abc123",
    "branch": "feature/dark-mode",
    "discover_flows": true
  }
}

Error responses

Status	When
`401`	Missing or invalid `Authorization` header.
`404`	The `appId` doesn't exist or you don't have access.
`400`	The app has no URL configured. Set one in app settings first.
`500`	Server error. Check the response body for details.

Examples

Minimal — kick off a default check

curl -X POST https://qassandra.com/api/apps/$APP_ID/trigger \
  -H "Authorization: Bearer $QASSANDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

From GitHub Actions

name: Qassandra check
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  qassandra:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Qassandra check
        run: |
          curl -X POST "https://qassandra.com/api/apps/${{ vars.QASSANDRA_APP_ID }}/trigger" \
            -H "Authorization: Bearer ${{ secrets.QASSANDRA_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "$(cat <<EOF
          {
            "git_commit_id": "${{ github.event.pull_request.head.sha }}",
            "branch": "${{ github.head_ref }}",
            "pull_request_id": "${{ github.event.pull_request.number }}",
            "pull_request_name": "${{ github.event.pull_request.title }}"
          }
          EOF
          )"

Force a discovery pass after a redesign

curl -X POST https://qassandra.com/api/apps/$APP_ID/trigger \
  -H "Authorization: Bearer $QASSANDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "discover_flows": true,
    "git_commit_message": "Redesign of the dashboard"
  }'

★

Polling for results

The trigger endpoint returns immediately with status: "scheduled". To watch a check progress, open the dashboard or poll for the check by ID. A results-fetching endpoint is on the roadmap.