Run API

Quick start

1. In CogentRun, open Settings → API keys and generate a key. It is shown once; store it in your tool's secret store. 2. Start a run:

curl -X POST https://www.cogentrun.com/api/v1/runs \
  -H "Authorization: Bearer $COGENTRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal": "Log in as the demo user and check the cart total is $42"}'

The run is queued and the call returns at once:

HTTP/1.1 202 Accepted
{
  "run_id": "3f6c…",
  "status": "pending",
  "created": true,
  "status_url": "https://www.cogentrun.com/api/v1/runs/3f6c…",
  "report_url": "https://www.cogentrun.com/runs/3f6c…"
}

3. Poll status_url until finished is true. A run usually takes a few minutes.

Authentication

Every request carries the organization API key as Authorization: Bearer <key> (or X-API-Key: <key> for tools that cannot set a bearer header). The key decides which organization the run belongs to and is billed to — there is no organization field. Regenerating the key in Settings stops the old one immediately. Treat it like a password: anyone holding it can start runs.

Start a run — POST /api/v1/runs

Any other field is rejected with 422, so a typo fails loudly rather than being ignored.

Mobile runs need a build: either app_url, or a product_id whose environment has an uploaded build. Upload one from CI with POST /api/products/environments/<environment id>/builds (multipart field file, same API key); the environment id is in GET /api/v1/products.

Read a run — GET /api/v1/runs/{run_id}

{
  "run_id": "3f6c…",
  "status": "failed",          // pending | running | success | failed | error | stopped
  "finished": true,
  "result": "failed",          // passed | failed | error | stopped, null until finished
  "platform": "web",
  "summary": "FAILED: The agent reported completion, but these goal requirements were not carried out: …",
  "unmet_requirements": ["The cart total shows $42"],
  "status_note": null,         // e.g. "Waiting for a device" while pending
  "jira_issue_key": "PROJ-123",
  "report_url": "https://www.cogentrun.com/runs/3f6c…",
  "created_at": "2026-09-22T08:01:12+00:00",
  "updated_at": "2026-09-22T08:05:40+00:00"
}

• failed — the application did not do what the goal asked. This is a finding.
• error — the test platform could not complete the run (a device or model outage). It says nothing about your application; runs that fail on our side are not charged.

Stop a run with POST /api/v1/runs/{run_id}/stop. A finished run is returned unchanged.

List products — GET /api/v1/products

[
  {
    "id": "a1b2…", "name": "Shop", "type": "website",
    "environments": [
      { "id": "e5f6…", "name": "staging", "base_url": "https://staging.shop.example",
        "has_android_build": true, "has_ios_build": false }
    ]
  }
]

Jira Automation: test when a ticket moves to In Review

In Jira: Project settings → Automation → Create rule.

• Trigger: Work item transitioned → to status In Review (or whichever status means “ready to test”).
• Action: Send web request.
• URL: https://www.cogentrun.com/api/v1/runs · Method: POST · Body: Custom data.
• Headers: Authorization = Bearer <your key> (tick Hidden), Content-Type = application/json.

{
  "goal": "Verify the change described in this ticket works end to end on staging",
  "product_id": "<product id>",
  "environment": "staging",
  "jira_issue_key": "{{issue.key}}",
  "idempotency_key": "{{issue.key}}-{{now.jiraDate}}"
}

The ticket's description becomes context for the run, and the result is commented on the ticket with a link to the full report. The idempotency key makes it one run per ticket per day, however often Jira retries the request or the ticket bounces between statuses; leave it out to test on every transition.

GitHub Actions: test after a deploy

- name: CogentRun smoke test
  env:
    COGENTRUN_API_KEY: ${{ secrets.COGENTRUN_API_KEY }}
  run: |
    RUN=$(curl -sf -X POST https://www.cogentrun.com/api/v1/runs \
      -H "Authorization: Bearer $COGENTRUN_API_KEY" -H "Content-Type: application/json" \
      -d '{"goal":"Sign up, then log in with the new account","product_id":"<product id>","environment":"staging","idempotency_key":"${{ github.run_id }}"}')
    ID=$(echo "$RUN" | jq -r .run_id)
    while :; do
      S=$(curl -sf -H "Authorization: Bearer $COGENTRUN_API_KEY" https://www.cogentrun.com/api/v1/runs/$ID)
      [ "$(echo "$S" | jq -r .finished)" = "true" ] && break
      sleep 20
    done
    echo "$S" | jq -r .summary
    [ "$(echo "$S" | jq -r .result)" = "passed" ]

Bitbucket Pipelines

- step:
    name: CogentRun smoke test
    script:
      - >
        curl -sf -X POST https://www.cogentrun.com/api/v1/runs
        -H "Authorization: Bearer $COGENTRUN_API_KEY" -H "Content-Type: application/json"
        -d "{\"goal\":\"Check checkout works\",\"product_id\":\"<product id>\",\"idempotency_key\":\"$BITBUCKET_BUILD_NUMBER\"}"

Add COGENTRUN_API_KEY as a secured repository variable. Poll the status URL as in the GitHub example to gate the pipeline on the result.

Errors

• 400 — the request cannot run as described (unknown environment, no build, disallowed URL). The detail says what to change.
• 401 — missing, wrong or revoked API key.
• 402 — the organization is out of credit or its platform fee is past due.
• 404 — the product or run does not exist in this organization.
• 422 — a field is missing, malformed or not part of the API.
• 429 — the organization's concurrent-run limit is reached. Retry later with the same idempotency key.

Pull request review

Pull request reviews are started by GitHub and Bitbucket webhooks, not by this API. Choose which events start a review — opened, new commits, reopened, ready for review, a review label, target branches, skipped authors — per repository under Settings → PR review. Anyone with write access can comment /cogentrun review on a pull request to review its latest commit on demand.