Start run

Overview

Start run dispatches validation for a project against an execution environment with explicit test case or suite IDs. This powers CI gates, scheduled jobs, and custom orchestration without Console clicks.

Who should read this

• Platform engineers integrating CI/CD, internal tooling, or data pipelines with Zof.

Prerequisites

• Valid organization API key with permission for this resource
• Resource ID when path includes {id}, copy from Console or list endpoint
• Staging environment for first integration test

When to use this workflow

• Invoke start run from deployment pipelines or scheduled jobs
• Synchronize Zof state with internal CMDB or release management tools
• Automate workflows that would otherwise require Console manual steps

Step-by-step procedure

Key concepts

Permission

Requires runs:create.

project_id

Reliability project containing cases to execute.

environment

staging | production | custom label matching Admin → Environments.

test_case_ids

Array of case IDs; omit when using test_suite_id instead.

Best practices

• Use idempotency keys for POST operations in automation
• Handle 429 responses with exponential backoff and jitter
• Log X-Request-Id from response headers for support escalation
• Test against staging project IDs before production automation

Common issues

404 on {id}

Resource deleted, wrong organization scope, or typo in ID.

403 Forbidden

API key role lacks permission; use service account with appropriate role.

409 Conflict

Illegal state transition, e.g., canceling a completed run.

Start run (curl)

curl -X POST https://api.zof.ai/v1/runs \
  -H "Authorization: Bearer $ZOF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc",
    "environment": "staging",
    "test_suite_id": "suite_pr_smoke"
  }'

API operations

Related documentation