CI Runs API

These endpoints are for systems that need direct HTTP control.

Create run

Headers

Header	Value
Content-Type	application/json
X-API-Key	your API key
Idempotency-Key	recommended

Body

{
  "projectSlug": "my-app",
  "environmentKey": "staging",
  "processSlug": "smoke-suite",
  "repository": "org/repo",
  "ref": "main",
  "commitSha": "a1b2c3d4",
  "event": "push",
  "externalUrl": "https://ci.example.com/build/123"
}

Notes:

• projectSlug is required.
• environmentKey is optional; if omitted, the default project environment is used.
• Specify exactly one of:
  • processSlug (recommended), or
  • tags (non-empty array)
• Use Idempotency-Key to prevent duplicate runs on retried CI jobs.

Example request

CERTYN_API_URL="https://api.certyn.io"

curl -sS -X POST "$CERTYN_API_URL/api/ci/runs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CERTYN_API_KEY" \
  -H "Idempotency-Key: $CI_JOB_ID" \
  -d '{
    "projectSlug": "my-app",
    "environmentKey": "staging",
    "processSlug": "smoke-suite",
    "commitSha": "a1b2c3d4"
  }'

Get run status

Status fields used for gating

• state (in_progress, completed, cancelled)
• failed
• blocked
• appUrl
• retryAfterSeconds

Polling guidance

• Poll every 10-30 seconds.
• Prefer retryAfterSeconds when returned.
• Gate fail condition: failed > 0 || blocked > 0.

Example polling loop

#!/usr/bin/env bash
set -euo pipefail

CERTYN_API_URL="${CERTYN_API_URL:-https://api.certyn.io}"
RUN_ID="${1:?Usage: $0 <run-id>}"
MAX_ATTEMPTS=60

for i in $(seq 1 "$MAX_ATTEMPTS"); do
  resp="$(curl -sS -H "X-API-Key: $CERTYN_API_KEY" "$CERTYN_API_URL/api/ci/runs/$RUN_ID")"
  state="$(echo "$resp" | jq -r '.state')"
  failed="$(echo "$resp" | jq -r '.failed')"
  blocked="$(echo "$resp" | jq -r '.blocked')"
  interval="$(echo "$resp" | jq -r '.retryAfterSeconds // 15')"

  echo "poll=$i state=$state failed=$failed blocked=$blocked"

  if [ "$state" = "completed" ] || [ "$state" = "cancelled" ]; then
    if [ "$failed" != "0" ] || [ "$blocked" != "0" ]; then
      exit 1
    fi
    exit 0
  fi

  sleep "$interval"
done

echo "Timed out waiting for run completion"
exit 1

Cancel run

Optional JSON body:

{
  "reason": "Cancelled by pipeline"
}