Introduction

curl -X POST "https://qarunbook.com/api/v1/issues" \
  -H "Authorization: Bearer $QARUNBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "Checkout",
    "check": "AUTH-01",
    "text": "Sign in does nothing on Safari 18.",
    "platforms": ["WL"]
  }'

What it is for

Your testers work in qarunbook itself, and your AI works through MCP. The API is for everything else — software that has something to say about a release and no one to type it in:

• A support desk files a customer's bug against the check it breaks, so the runbook shows it failing the moment it is reported. See the guide.
• A CI job records pass or fail for the checks its automated tests cover, next to the ones people test by hand. See the guide.
• A dashboard reads coverage, failing checks and open issues without anyone exporting a spreadsheet.

Base URL

Every endpoint lives under one versioned base. Requests and responses are JSON over HTTPS.

https://qarunbook.com/api/v1

Your first request

Create a key under API in your account menu (owners and admins; see Authentication), keep it in an environment variable, and ask the API who it thinks you are. It is the quickest way to prove the key works and to see what it can reach.

curl "https://qarunbook.com/api/v1" \
  -H "Authorization: Bearer $QARUNBOOK_KEY"

{
  "data": {
    "key": {
      "id": "mfs0a1b2c3d",
      "name": "Zendesk",
      "prefix": "qrk_live_Hq3v9sXa",
      "role": "tester",
      "apps": null
    },
    "workspace": {
      "id": "mfp9z8y7x6w",
      "name": "Acme",
      "plan": "Team"
    },
    "docs": "https://qarunbook.com/docs"
  }
}

Conventions

• Every success is { "data": … }, and every failure is { "error": { "code", "message" } }. Lists add next_cursor — see Pagination.
• Apps can be named by id or by name. Checks can be named by id, or by their ref — AUTH-01 — together with the app, which is usually what a person writing an integration has to hand.
• Status is a word: passed, failed, retest, untested or not_applicable. It is derived from results and issues on every read, exactly as the grid derives it.
• Timestamps are ISO 8601 in UTC. Ids are opaque strings.

Plans

The API is part of the Team and Business plans, and of Enterprise. On Free and Early access every call answers 402 plan_required, and keys can't be created — see pricing. Keys you already hold keep their settings through a downgrade and start working again the moment the workspace is back on a paid plan.

API or MCP?

They reach the same runbook through the same rules, so a key can do nothing a teammate with the same role could not. The difference is who is acting.