# API — AgentReady Monitor

> Everything the UI does, the API does too.

## Authentication

Every request needs a bearer token:

```http
Authorization: Bearer ark_live_...
```

You create API keys in the dashboard under Account. The plaintext is shown exactly once; only a SHA-256 hash is stored.

## Conventions

- Base URL: `https://ai-agent-ready.com/api/v1`
- Response format: JSON, always with a `meta` field.
- `meta.pricing` is currently `{"model":"free"}`. The field exists so agents can handle a 402 flow later without the schema changing.
- Errors come back as `{ "error": { "code", "message" }, "meta": {...} }`.

## Endpoints

### GET /api/v1/cases

Returns every case belonging to the account behind the API key, including the current overall score and the time of the last run.

MCP tool: `list_cases`

Response:

```json
{
  "cases": [
    {
      "id": "4f1e9b2c-0d8a-4f7b-9d21-1b7c0c9a55e1",
      "name": "Beispiel CRM",
      "domain": "beispiel-crm.de",
      "kategorie": "CRM software for trade businesses",
      "konkurrenten": [
        "Craftnote",
        "Meisterwerk",
        "ToolTime"
      ],
      "status": "active",
      "latest_score": 44,
      "last_run_at": "2026-08-01T03:12:00.000Z"
    }
  ],
  "meta": {
    "pricing": {
      "model": "free"
    },
    "generated_at": "2026-08-25T09:12:44.000Z",
    "docs": "https://ai-agent-ready.com/docs/api"
  }
}
```

Errors:

- `401 unauthorized` — Bearer token missing or unknown.
- `403 no_account` — No Monitor account exists for this key.

### GET /api/v1/cases/{id}/summary

The result of the most recent finished run: overall score, score per model, share of answer against every competitor, top gaps and the delta to the previous run.

MCP tool: `get_case_summary`

Parameters:

- `id` (path, required): Case id (UUID).

Response:

```json
{
  "case": {
    "id": "4f1e9b2c-0d8a-4f7b-9d21-1b7c0c9a55e1",
    "name": "Beispiel CRM"
  },
  "run": {
    "id": "9a0c...",
    "label": "Aug 26",
    "kind": "monthly",
    "finished_at": "2026-08-01T03:41:00.000Z"
  },
  "summary": {
    "total_score": 44,
    "per_model": {
      "openai": 48,
      "anthropic": 39,
      "perplexity": 51,
      "google": 38
    },
    "share_of_answer": [
      {
        "name": "Craftnote",
        "share": 0.8,
        "mentions": 8,
        "total": 10,
        "is_self": false
      },
      {
        "name": "Beispiel CRM",
        "share": 0.4,
        "mentions": 4,
        "total": 10,
        "is_self": true
      }
    ],
    "top_gaps": [
      "Preise werden nicht genannt",
      "Keine Aussage zur Testphase"
    ],
    "delta": {
      "total_score": -6,
      "per_model": {
        "openai": -4
      },
      "previous_run_id": "7c21..."
    }
  },
  "meta": {
    "pricing": {
      "model": "free"
    },
    "generated_at": "2026-08-25T09:12:44.000Z",
    "docs": "https://ai-agent-ready.com/docs/api"
  }
}
```

Errors:

- `404 not_found` — Case does not exist or belongs to another account.
- `409 no_run` — No run has finished for this case yet.

### GET /api/v1/cases/{id}/runs

All measurement runs of a case, newest first, with status, overall score and the delta to the preceding run.

MCP tool: `list_runs`

Parameters:

- `id` (path, required): Case id (UUID).
- `limit` (query): Maximum number of runs (1–100).

Response:

```json
{
  "runs": [
    {
      "id": "9a0c...",
      "label": "Aug 26",
      "kind": "monthly",
      "status": "done",
      "scheduled_for": "2026-08-01T03:00:00.000Z",
      "finished_at": "2026-08-01T03:41:00.000Z",
      "total_score": 44,
      "delta": -6
    }
  ],
  "meta": {
    "pricing": {
      "model": "free"
    },
    "generated_at": "2026-08-25T09:12:44.000Z",
    "docs": "https://ai-agent-ready.com/docs/api"
  }
}
```

Errors:

- `404 not_found` — Case does not exist or belongs to another account.

### POST /api/v1/cases/{id}/runs

Queues a run. The worker picks it up within seconds. Pro plan only; a run that is already queued or in progress for the same case is not duplicated.

MCP tool: `create_run`

Parameters:

- `id` (path, required): Case id (UUID).

Body:

```json
{
  "label": "After relaunch"
}
```

Response:

```json
{
  "run": {
    "id": "b71f...",
    "label": "After relaunch",
    "kind": "manual",
    "status": "queued"
  },
  "meta": {
    "pricing": {
      "model": "free"
    },
    "generated_at": "2026-08-25T09:12:44.000Z",
    "docs": "https://ai-agent-ready.com/docs/api"
  }
}
```

Errors:

- `402 plan_required` — The plan does not allow manual re-runs.
- `409 run_pending` — A run is already queued or in progress for this case.

## OpenAPI

- Spec: https://ai-agent-ready.com/api/v1/openapi.json

## MCP

The MCP server ships as a small Cloudflare Worker and consumes only this REST API. The mapping is one to one:

- `list_cases` → `GET /api/v1/cases`
- `get_case_summary` → `GET /api/v1/cases/{id}/summary`
- `list_runs` → `GET /api/v1/cases/{id}/runs`
- `create_run` → `POST /api/v1/cases/{id}/runs`

A product by The Autopilot — https://the-autopilot.com