API Overview

The Drizz REST API in one page — the auth model, the 24-hour token, rate limits, and the three calls that get a build running.

The Drizz REST API covers three operations: authenticate, upload a build, trigger a test plan.

In the examples below, the shell variable DRIZZ_BASE_URL holds that value, and DRIZZ_API_KEY holds the access token returned by the auth call.

At a glance

POST <DRIZZ_API_BASE_URL>/testplan/run

Auth	OAuth 2.0 client credentials → a bearer token, sent as x-api-key
Token life	24 hours (expires_in: 86400)
Rate limit	~4 requests/second, burst ~20, per client → HTTP 429 over that
Upload cap	500 MB per binary
Watch out	There is no endpoint to poll a run or fetch results. Trigger is where the API ends

Prerequisites

• Active Drizz organization account

• Client ID and client secret, issued by Drizz

• Auth host and audience string, issued by Drizz

• API base URL for your organization

• At least one registered app, with its package name or bundle ID

• At least one test plan, with its ID

• curl and jq, or an equivalent HTTP client

Copy this

# 1 — set these once
export DRIZZ_BASE_URL="<DRIZZ_API_BASE_URL>"
export DRIZZ_AUTH_DOMAIN="<auth-domain>"
export DRIZZ_CLIENT_ID="<your_client_id>"
export DRIZZ_CLIENT_SECRET="<your_client_secret>"
export DRIZZ_AUDIENCE="<DRIZZ_API_AUDIENCE>"

# 2 — authenticate. The token is valid for 24 hours
export DRIZZ_API_KEY=$(curl -s -X POST "https://${DRIZZ_AUTH_DOMAIN}/oauth/token" \
  -H "Content-Type: application/json" \
  -d "{
    \"client_id\": \"${DRIZZ_CLIENT_ID}\",
    \"client_secret\": \"${DRIZZ_CLIENT_SECRET}\",
    \"audience\": \"${DRIZZ_AUDIENCE}\",
    \"grant_type\": \"client_credentials\"
  }" | jq -r .access_token)

# 3 — upload the build. Skip this if the version is already registered
curl -s -X POST "${DRIZZ_BASE_URL}/apk/upload" \
  -H "x-api-key: ${DRIZZ_API_KEY}" \
  -F "file=@app-release.apk"

# 4 — trigger the test plan. Returns an execution_id
curl -s -X POST "${DRIZZ_BASE_URL}/testplan/run" \
  -H "x-api-key: ${DRIZZ_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "test_plan_id": "ADuF4ViN",
    "apks": { "com.shopease.android": "1.0.0" }
  }'

Endpoints

#	Call	Method and endpoint	Required	Returns
1	Authenticate	POST https://<auth-domain>/oauth/token	Yes	access_token, valid 24 hours
2	Upload a build	POST <DRIZZ_API_BASE_URL>/apk/upload	No — only when the version changes	Package name, version name, version code
3	Trigger a run	POST <DRIZZ_API_BASE_URL>/testplan/run	Yes	execution_id
3b	Trigger a batch	POST <DRIZZ_API_BASE_URL>/testplan/run/batch	No	successful_executions, failed_executions

If the version under test is already registered, skip call 2 and name the version in apks on call 3.

Request headers

Header	Value	Applies to
x-api-key	Access token from the auth call	Every call except /oauth/token
Content-Type	application/json	/oauth/token, /testplan/run, /testplan/run/batch
Content-Type	multipart/form-data	/apk/upload

The token header is x-api-key, not Authorization: Bearer. An Authorization: Bearer header is ignored and the call is rejected as unauthenticated. See Authenticate.

Scope

In scope	Not in scope
Authenticating an external system with client credentials	Polling a run's status
Uploading a mobile app binary	Fetching results, reports or artifacts
Triggering one test plan	JUnit, JSON or Allure export
Triggering several test plans in a batch	Webhooks or any callback on completion
	Creating or editing test plans, tests, modules or datasets

A pipeline can start a run. It cannot wait for one or gate a build on the outcome. See CI/CD.

Rate limits

Limit	Value
Sustained rate	~4 requests per second, per client
Burst allowance	~20 requests
Over the limit	HTTP 429
Batch of plans	Use POST /testplan/run/batch — one request instead of one per plan

Back off with jitter after a 429. See Errors & limits.

Error codes

Code	Meaning	What to do
200	Success	Request accepted
207	Multi-Status	Batch partially succeeded — inspect failed_executions
400	Bad Request	Validate the payload and parameters
404	Not Found	Verify the test plan ID and that the app version is registered
409	Conflict	This app version already exists — bump the version or skip the upload
429	Too Many Requests	Over the rate limit. Back off and retry
500	Server Error	Contact [e-mail]
502	Bad Gateway	Retry, or check service availability

Common mistakes

What you did	What happens
Sent Authorization: Bearer <token>	Rejected. The header is x-api-key
Cached the token for a week	It expired after 24 hours. Requests start failing
Looped single triggers for 40 plans	HTTP 429. Use the batch endpoint
Waited for the run to finish in your script	There is nothing to poll. The API ends at trigger
Uploaded the build on every pipeline run	Re-uploading an existing version returns 409

Next

• Authenticate — get a token

• Trigger a run — start a test plan

• Errors & limits — status codes and retry behavior

---

Last updated: 6 August 2026