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 on every plan, Free included. On Free, issues raised through it count towards the monthly allowance like any other — when it is used up, raising answers 402 limit_reached until the 1st or an upgrade. See pricing.

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.