Documentation
API Reference

Retrieve a run

Retrieves the current status and per-result details for a run. The top-level `status` rolls up across every result in the run, and is safe to poll for build gating.

GET
/runs/{run_id}

Authorization

BearerAuth
AuthorizationBearer <token>

API key issued from Settings > Integrations > CI/CD. Keys have the format dk_live_<40-hex>.

In: header

Path Parameters

run_id*string

Unique identifier of the run to retrieve.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://api.doksi.ai/external/integration/cicd/runs/string"
{
  "run_id": "string",
  "status": "queued",
  "tests_total": 0,
  "tests_passed": 0,
  "tests_failed": 0,
  "tests_running": 0,
  "duration_seconds": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "results": [
    {
      "result_id": "string",
      "test_id": "string",
      "test_name": "string",
      "status": "queued",
      "duration_seconds": 0,
      "url": "http://example.com",
      "destination": {
        "platform": "web",
        "web_url": "http://example.com"
      }
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}

Examples

Retrieving a run

curl "https://api.doksi.ai/external/integration/cicd/runs/$RUN_ID" \
  -H "Authorization: Bearer $DOKSI_API_KEY"
{
  "run_id": "k3n2mPq9Rxyz",
  "status": "running",
  "tests_total": 3,
  "tests_passed": 1,
  "tests_failed": 0,
  "tests_running": 2,
  "duration_seconds": 42,
  "created_at": "2026-04-14T14:22:10.000Z",
  "updated_at": "2026-04-14T14:22:44.000Z",
  "results": [
    {
      "result_id": "res_aa11",
      "test_id": "abc123",
      "test_name": "Checkout flow",
      "status": "passed",
      "duration_seconds": 22,
      "url": "https://app.doksi.ai/verify/tests/abc123/runs/res_aa11",
      "destination": { "platform": "web", "web_url": "https://staging.example.com" }
    }
  ]
}

Polling for completion

Poll the endpoint until status is passed or failed. Any other value means the run is still in progress.

while true; do
  RES=$(curl -s "https://api.doksi.ai/external/integration/cicd/runs/$RUN_ID" \
    -H "Authorization: Bearer $DOKSI_API_KEY")
  STATUS=$(echo "$RES" | jq -r '.status')
  echo "Status: $STATUS"
  case "$STATUS" in
    passed) exit 0 ;;
    failed) exit 1 ;;
  esac
  sleep 10
done

GitHub Actions step

- name: Wait for Doksi
  run: |
    while true; do
      STATUS=$(curl -s "https://api.doksi.ai/external/integration/cicd/runs/${{ steps.trigger.outputs.run_id }}" \
        -H "Authorization: Bearer ${{ secrets.DOKSI_API_KEY }}" | jq -r '.status')
      [ "$STATUS" = "passed" ] && exit 0
      [ "$STATUS" = "failed" ] && exit 1
      sleep 15
    done

Create a run

Creates a run from a matrix of entries, each pairing a target with a set of tests and authentication settings. Returns immediately with a `run_id`. Poll `GET /runs/{run_id}` until the run completes.

Upload an Android binary

Upload an APK to Doksi-hosted storage and register it as a reusable target. Call POST /uploads to create a presigned S3 URL, PUT the APK zip to it, then call POST /targets to parse the manifest and mint a target_id you can reuse across runs.