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.

Authorization

BearerAuth

AuthorizationBearer <token>

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

In: header

Request Body

application/json

matrix*array<>

A list of entries to execute. Each entry produces one result per test, and the same test appearing in multiple entries fans out across platforms and accounts. At least one entry is required.

An entry targets either a web URL or an Android binary, and specifies which tests to run against it.

Entry fields

Field	Type	Required	Description
`platform`	`string`	yes	One of `web` or `android`. Determines which target fields are accepted.
`web_url`	`string`	conditional	URL to test. Web platform only. Mutually exclusive with `binary_url` and `target_id`.
`binary_url`	`string`	conditional	Publicly reachable APK URL. Android platform only. Mutually exclusive with `web_url` and `target_id`.
`target_id`	`string`	conditional	ID of an existing target. Mutually exclusive with `web_url` and `binary_url`.
`test_ids`	`string[]`	conditional	A list of test IDs to execute. At least one of `test_ids` or `category_ids` is required.
`category_ids`	`string[]`	conditional	A list of category IDs. Expanded at run time to every non-hidden test in each category.
`artifacts`	`Artifact[]`	no	A list of per-entry artifact overrides. Only `authentication` artifacts are recognized.

Exactly one of web_url, binary_url, or target_id is required per entry, and must be valid for the entry's platform.

Authentication artifact

Field	Type	Required	Description
`type`	`string`	yes	Always `authentication`.
`strategy`	`string`	yes	One of `none`, `generated`, or `specific`. `none` runs unauthenticated. `generated` provisions a fresh account per session. `specific` uses the account referenced by `account_id`.
`account_id`	`string`	conditional	ID of the account to use. Required when `strategy` is `specific`. Must belong to the authenticated company.

If multiple authentication artifacts are provided for the same entry, the first is used. Omit artifacts entirely to default to strategy: "none".

Response Body

`application/json`

curl -X POST "https://api.doksi.ai/external/integration/cicd/runs" \  -H "Content-Type: application/json" \  -d '{    "matrix": [      {        "platform": "web",        "web_url": "https://staging.example.com",        "test_ids": [          "abc123"        ]      }    ]  }'

{
  "run_id": "string",
  "results": [
    {
      "result_id": "string",
      "test_id": "string",
      "url": "http://example.com"
    }
  ]
}

{
  "error": "string"
}

{
  "error": "string"
}

{
  "error": "string",
  "requested": 0,
  "remaining": 0
}

{
  "error": "string"
}

Examples

Single web entry

The minimum request. Runs one test against a web URL with no authentication.

curl -X POST "https://api.doksi.ai/external/integration/cicd/runs" \
  -H "Authorization: Bearer $DOKSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matrix": [
      {
        "platform": "web",
        "web_url": "https://staging.example.com",
        "test_ids": ["abc123"]
      }
    ]
  }'

Android with a publicly hosted APK

Doksi downloads the APK from binary_url at session start.

curl -X POST "https://api.doksi.ai/external/integration/cicd/runs" \
  -H "Authorization: Bearer $DOKSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matrix": [
      {
        "platform": "android",
        "binary_url": "https://builds.example.com/app.apk",
        "test_ids": ["abc123"]
      }
    ]
  }'

Android with an uploaded target

Registers the APK once via POST /targets and then references target_id for every run.

# 1. Create the presigned URL.
MINT=$(curl -sX POST "$BASE/uploads" \
  -H "Authorization: Bearer $DOKSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"storefront"}')
UPLOAD_ID=$(echo "$MINT" | jq -r '.upload_id')
UPLOAD_URL=$(echo "$MINT" | jq -r '.upload_url')

# 2. Upload the APK.
zip app.zip app/build/outputs/apk/release/app-release.apk
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @app.zip

# 3. Register the target.
TARGET=$(curl -sX POST "$BASE/targets" \
  -H "Authorization: Bearer $DOKSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"upload_id\":\"$UPLOAD_ID\"}")
TARGET_ID=$(echo "$TARGET" | jq -r '.target_id')

# 4. Trigger the run.
curl -sX POST "$BASE/runs" \
  -H "Authorization: Bearer $DOKSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"matrix\":[
      {\"platform\":\"android\",\"target_id\":\"$TARGET_ID\",\"test_ids\":[\"abc123\"]}
    ]
  }"

Category expansion

Provide category_ids in place of test_ids to run every non-hidden test in a category.

curl -X POST "https://api.doksi.ai/external/integration/cicd/runs" \
  -H "Authorization: Bearer $DOKSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matrix": [
      {
        "platform": "android",
        "target_id": "bin_abc123",
        "category_ids": ["cat_smoke"]
      }
    ]
  }'

Authentication

Each matrix entry controls its own authentication through the artifacts array. Three strategies are supported.

`none`

Runs the test unauthenticated. This is the default when artifacts is omitted.

{
  "matrix": [
    {
      "platform": "web",
      "web_url": "https://staging.example.com",
      "test_ids": ["abc123"]
    }
  ]
}

`generated`

Provisions a fresh account for each session. Useful when every test needs its own clean state.

{
  "matrix": [
    {
      "platform": "android",
      "target_id": "bin_abc123",
      "test_ids": ["abc123"],
      "artifacts": [
        { "type": "authentication", "strategy": "generated" }
      ]
    }
  ]
}

`specific`

Uses an account registered in the dashboard under Platform > Accounts. The account_id is required and must belong to the authenticated company.

{
  "matrix": [
    {
      "platform": "web",
      "web_url": "https://staging.example.com",
      "test_ids": ["abc123"],
      "artifacts": [
        { "type": "authentication", "strategy": "specific", "account_id": "acc_789" }
      ]
    }
  ]
}

Fanning out across platforms

Include the same test in multiple entries to execute it against different platforms or authentication strategies in a single run.

curl -X POST "https://api.doksi.ai/external/integration/cicd/runs" \
  -H "Authorization: Bearer $DOKSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "matrix": [
      {
        "platform": "web",
        "web_url": "https://staging.example.com",
        "test_ids": ["abc123"],
        "artifacts": [
          { "type": "authentication", "strategy": "specific", "account_id": "acc_789" }
        ]
      },
      {
        "platform": "android",
        "target_id": "bin_abc123",
        "test_ids": ["abc123"],
        "artifacts": [
          { "type": "authentication", "strategy": "generated" }
        ]
      }
    ]
  }'

Create a run

Entry fields

Authentication artifact

201application/json

400application/json

401application/json

402application/json

403application/json

Entry fields

Authentication artifact

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`