# Agents

This page is an LLM-optimized reference for the Cursion Platform. It is intended to be used by AI agents, retrieval systems, and tool-using assistants that need canonical platform context in a single document.

Raw Markdown: <a href="/agents.md">`/agents.md`</a>

## Purpose

Use this page to answer these questions:

- what objects exist in Cursion
- how objects relate to each other
- what data each object stores
- which workflows create or consume each object
- what status fields, metric names, and configuration fields are canonical

## Platform Summary

Cursion is a website quality automation platform.

Primary capabilities:

- organize websites into `Site` and `Page`
- capture snapshots with `Scan`
- compare snapshots with `Test`
- define browser workflows with `Case`
- execute browser workflows with `CaseRun`
- orchestrate multi-step jobs with `Flow` and `FlowRun`
- track failures with `Issue`
- automate recurring work with `Schedule` and `Alert`
- generate summary PDFs with `Report`
- track async generation work with `Process`

## Canonical Object Graph

```text
Site
├─ Page
│  ├─ Scan
│  ├─ Test
│  └─ Schedule
├─ Case
│  └─ CaseRun
├─ Flow
│  └─ FlowRun
├─ Schedule
│  └─ Alert
├─ Report
├─ Issue
└─ Process
```

## Relationship Rules

| Rule | Canonical meaning |
| --- | --- |
| `Site` | top-level website container |
| `Page` | child URL of a `Site` |
| `Scan` | point-in-time snapshot of a `Page` |
| `Test` | comparison of two `Scans` for the same `Page` |
| `Case` | reusable functional test definition |
| `CaseRun` | execution of a `Case` for a specific `Site` |
| `Flow` | reusable orchestration graph |
| `FlowRun` | execution of a `Flow` for a specific `Site` |
| `Schedule` | recurring job definition at site or page scope |
| `Alert` | post-schedule conditional action set |
| `Issue` | durable failure record, usually from `Test` or `CaseRun` |
| `Report` | site-scoped PDF summary |
| `Process` | tracker for asynchronous generation actions |

## Object Reference

Each object section below follows the same pattern:

- `Role`: what the object is for
- `Parent`: what it belongs to
- `Key fields`: fields an agent should treat as primary
- `Statuses`: canonical status values if relevant
- `Create inputs`: high-signal creation inputs
- `Outputs`: high-signal output semantics

### `Site`

| Property | Value |
| --- | --- |
| Role | top-level website container |
| Parent | none |
| Children | `Page`, `CaseRun`, `FlowRun`, `Schedule`, `Issue`, `Report` |
| Key fields | `id`, `site_url`, `tags`, `time_crawl_started`, `time_crawl_completed`, `info.latest_scan`, `info.latest_test` |
| Create inputs | `site_url`, optional `page_urls`, optional `tags`, optional `no_scan`, optional `configs` |
| Outputs | site metadata plus summary info for latest scan and latest test |

Canonical facts:

- A `Site` represents a domain such as `https://example.com`.
- Site creation is asynchronous.
- Creating a site may crawl pages, generate baseline scans, and generate cases.
- Passing `page_urls` skips crawling and uses the supplied URLs.
- Passing `no_scan=true` skips the initial baseline scan.

### `Page`

| Property | Value |
| --- | --- |
| Role | single URL under a `Site` |
| Parent | `Site` |
| Children | `Scan`, `Test`, `Schedule` |
| Key fields | `id`, `site`, `page_url`, `tags`, `info.latest_scan`, `info.latest_test` |
| Create inputs | `site_id`, `page_url` or `page_urls`, optional `tags`, optional `no_scan`, optional `configs` |
| Outputs | page metadata plus latest scan and test summaries |

Canonical facts:

- A `Page` is URL-specific.
- A `Page` belongs to exactly one `Site`.

### `Scan`

| Property | Value |
| --- | --- |
| Role | page snapshot and raw evidence object |
| Parent | `Page` and `Site` |
| Children | none |
| Key fields | `id`, `site`, `page`, `paired_scan`, `type`, `configs`, `html`, `logs`, `lighthouse`, `security`, `images`, `time_created`, `time_completed` |
| Status indicator | `time_completed` being null usually means still running |
| Create inputs | `site_id`, optional `tags`, optional `type`, optional `configs` |
| Outputs | page source, logs, lighthouse data, security data, screenshots |

Canonical component types:

- `html`
- `logs`
- `images`
- `lighthouse`
- `security`

Canonical facts:

- A `Scan` is a snapshot of a page at a point in time.
- `images` is the visual regression input used later by `Test`.
- `lighthouse.audits` and `security.audits` point to remote JSON audit data.

### `Test`

| Property | Value |
| --- | --- |
| Role | regression comparison object |
| Parent | `Page` and `Site` |
| Inputs | two scans selected by the system for the requested page or site context |
| Key fields | `id`, `site`, `page`, `pre_scan`, `post_scan`, `type`, `threshold`, `status`, `score`, `component_scores`, `html_delta`, `logs_delta`, `lighthouse_delta`, `security_delta`, `images_delta`, `time_created`, `time_completed` |
| Create inputs | `page_id` or `site_id`, optional `type`, optional `tags`, optional `index`, optional `configs` |
| Outputs | component deltas plus overall composite score |

Canonical statuses:

- `working`
- `passed`
- `failed`
- `incomplete`

Canonical facts:

- A `Test` compares two `Scans` of the same `Page`.
- `score` is the composite regression score.
- `threshold` is the pass/fail cutoff.
- `component_scores` is the fastest high-signal summary for agents.
- `create_issue=true` can auto-create an `Issue` on failure.

### `Case`

| Property | Value |
| --- | --- |
| Role | reusable functional browser test definition |
| Parent | optionally associated with a `Site` |
| Children | `CaseRun` |
| Key fields | `id`, `title`, `steps.url`, `steps.num_steps`, `site`, `site_url`, `type`, `processed`, `tags` |
| Create inputs | `site_id`, `prompt`, optional `max_layers` |
| Outputs | reusable case metadata plus remote step definition |

Canonical case types:

- `generated`
- `recorded`

Canonical step schema:

```json
{
  "action": {
    "type": "click",
    "path": "/",
    "value": "",
    "key": "",
    "element": {
      "selector": "[id='menu-item-83']>A:nth-child(1)",
      "xpath": "id(\"menu-item-83\")/a[1]"
    }
  },
  "assertion": {
    "type": "match",
    "value": "",
    "element": {
      "selector": "",
      "xpath": ""
    }
  }
}
```

Canonical facts:

- A `Case` stores instructions called `steps`.
- Each step has `action` and `assertion`.
- Case generation returns a `Process`, not a completed case immediately.

### `CaseRun`

| Property | Value |
| --- | --- |
| Role | runtime execution of a `Case` |
| Parent | `Site`; references a `Case` |
| Key fields | `id`, `site`, `case`, `title`, `passed`, `configs`, `steps`, `time_created`, `time_completed`, `tags` |
| Create inputs | `site_id`, `case_id`, optional `updates`, optional `tags`, optional `configs` |
| Outputs | step-by-step runtime results including timestamps and exceptions |

Canonical facts:

- A `CaseRun` reuses a `Case` against a specific `Site`.
- `updates` can override step values by index before execution.
- `passed` is a boolean top-level outcome.
- `create_issue=true` can auto-create an `Issue` on failure.

### `Flow`

| Property | Value |
| --- | --- |
| Role | reusable orchestration graph |
| Parent | none |
| Children | `FlowRun` |
| Key fields | `id`, `title`, `nodes`, `edges`, `time_last_run` |
| Create inputs | graph-shaped `nodes` and `edges` payload |
| Outputs | orchestration definition for later execution |

Canonical node fields frequently seen in docs:

- `task_type`
- `type`
- `case_id`
- `updates`
- `threshold`
- `configs`
- `message`
- `subject`
- `uri`
- `payload`
- `headers`
- `request_type`
- `conditions`
- `start_if`

Canonical task types explicitly shown in docs:

- `scan`
- `slack`

Canonical facts:

- `nodes` define jobs.
- `edges` define execution relationships.
- A `Flow` is a definition object, not an execution record.

### `FlowRun`

| Property | Value |
| --- | --- |
| Role | runtime execution of a `Flow` |
| Parent | `Site`; references a `Flow` |
| Key fields | `id`, `flow`, `site`, `title`, `status`, `nodes`, `edges`, `logs`, `configs`, `time_created`, `time_completed` |
| Create inputs | `site_id`, `flow_id`, optional `configs.end_on_fail` |
| Outputs | node-level runtime state and run logs |

Canonical statuses:

- `working`
- `passed`
- `failed`

Canonical node runtime fields:

- `status`
- `objects`
- `finalized`
- `time_started`
- `time_completed`

Canonical facts:

- `FlowRun` is the execution record for a `Flow`.
- `logs` is the fastest place to inspect orchestration failures.

### `Issue`

| Property | Value |
| --- | --- |
| Role | durable failure record |
| Parent | account-scoped; references trigger and affected resource |
| Key fields | `id`, `title`, `status`, `labels`, `trigger`, `affected`, `details`, `time_created` |
| Create inputs | optional `id` for update, `trigger`, `affected`, `title`, `details` |
| Outputs | formatted failure record for humans and agents |

Canonical statuses:

- `open`
- `closed`

Canonical trigger types:

- `scan`
- `test`
- `caserun`

Canonical affected types:

- `site`
- `page`

Canonical facts:

- `details` is markdown.
- Issues are usually auto-generated from failed `Test` or `CaseRun` objects.

### `Schedule`

| Property | Value |
| --- | --- |
| Role | recurring automation definition |
| Parent | `Site` or `Page` |
| Children | optional `Alert` |
| Key fields | `id`, `site`, `page`, `task_type`, `timezone`, `begin_date`, `time`, `frequency`, `status`, `alert`, `extras`, `time_created` |
| Create inputs | `site_id` or `page_id`, `task_type`, `begin_date`, `time`, `timezone`, `frequency`, `configs`, optional `scan_type`, optional `test_type` |
| Outputs | recurring task definition and backend scheduling metadata |

Canonical task types:

- `scan`
- `test`
- `report`

Canonical frequencies:

- `daily`
- `weekly`
- `monthly`

Canonical statuses:

- `Active`
- `Paused`

Canonical facts:

- A site-level schedule runs across all child pages.
- `extras.configs` stores execution configuration.
- `extras.scan_type` and `extras.test_type` store task-specific scope.

### `Alert`

| Property | Value |
| --- | --- |
| Role | post-schedule conditional alert definition |
| Parent | `Schedule` |
| Key fields | `id`, `expressions`, `actions`, `schedule`, `name`, `time_created` |
| Create inputs | `schedule_id`, `site_id`, `expressions`, `actions`, `name`, optional `alert_id` for update |
| Outputs | threshold-based notification rules |

Canonical expression schema:

```json
{
  "joiner": "or",
  "data_type": "test_score",
  "operator": "<=",
  "value": "80"
}
```

Canonical action schema:

```json
{
  "action_type": "slack",
  "email": "",
  "phone": ""
}
```

Canonical action types:

- `slack`
- `phone`
- `email`

Canonical facts:

- One `Alert` is intended to service one `Schedule`.
- Alerts evaluate metric expressions after the scheduled task completes.
- Valid `data_type` values come from the platform data type catalog.

### `Report`

| Property | Value |
| --- | --- |
| Role | site-scoped PDF summary |
| Parent | `Site` |
| Key fields | `id`, `site`, `page`, `type`, `path`, `info.lookback_days`, `info.text_color`, `info.highlight_color`, `info.background_color`, `time_created` |
| Create inputs | `site_id`, `lookback_days`, `type`, `background_color`, `highlight_color`, `text_color`, optional `report_id` for update |
| Outputs | remote PDF path plus report metadata |

Canonical report sections:

- `issues`
- `tests`
- `caseruns`
- `performance`
- `security`

Canonical facts:

- Reports are site-scoped.
- `lookback_days` is one of `1`, `7`, `30`, `90`.

### `Process`

| Property | Value |
| --- | --- |
| Role | tracker for asynchronous generation or background work |
| Parent | references a `Site` or generated object context |
| Key fields | `id`, `site`, `type`, `progress`, `success`, `info`, `exception`, `object_id`, `time_created`, `time_completed` |
| Create inputs | not usually created directly by users; returned by other endpoints |
| Outputs | progress and completion state for async operations |

Canonical facts:

- `Process` is used for actions such as `case.generate`.
- Poll a `Process` until it completes.
- `object_id` usually identifies the created object when complete.

## Shared Config Schema

The platform reuses a `configs` object across several resources. Not every field appears on every object, but these are the canonical names that recur throughout the docs.

| Field | Meaning |
| --- | --- |
| `browser` | browser engine, usually `chrome` or `firefox` |
| `device` | user-agent or device class, usually `desktop` or `mobile` |
| `window_size` | browser window dimensions |
| `interval` | polling interval while waiting for page load |
| `max_wait_time` | max wait before moving on or failing |
| `min_wait_time` | minimum wait between checks or steps |
| `timeout` | hard timeout for the overall job |
| `mask_ids` | element IDs to mask in screenshots |
| `disable_animations` | disable animations for stable captures |
| `auto_height` | auto-resize to full page height |
| `create_issue` | auto-create issue on failed test or case run |
| `end_on_fail` | stop a flow after the first failed node |

Config rules:

- If an endpoint accepts `configs` and the docs say it is optional, passing it typically requires passing all subfields documented for that endpoint.
- `mask_ids`, `disable_animations`, and `auto_height` are important for stable visual regression output.

## Canonical Metric Vocabulary

These metric names are documented in the data guide and are important for alerts, summaries, and agent reasoning.

### Scan metrics

- `health`
- `logs`
- `lighthouse_average`
- `seo`
- `performance`
- `best_practices`
- `accessibility`
- `pwa`
- `crux`
- `security_average`
- `browser`
- `transport`
- `scripts`
- `forms`
- `compliance`

### Test metrics

- `test_score`
- `test_status`
- `current_health`
- `current_lighthouse_average`
- `seo_delta`
- `performance_delta`
- `best_practice_deltas`
- `accessibility_delta`
- `pwa_delta`
- `crux_delta`
- `current_security_average`
- `browser_delta`
- `transport_delta`
- `scripts_delta`
- `forms_delta`
- `compliance_delta`
- `html_score`
- `logs_score`
- `images_score`
- `lighthouse_score`
- `security_score`

### Runtime metrics

- `caserun_status`
- `flowrun_status`

## Canonical Status Vocabulary

| Object | Canonical status field or outcome |
| --- | --- |
| `Test` | `working`, `passed`, `failed`, `incomplete` |
| `CaseRun` | boolean `passed` |
| `FlowRun` | `working`, `passed`, `failed` |
| `Issue` | `open`, `closed` |
| `Schedule` | `Active`, `Paused` |

## API Conventions

### Base configuration

- `CURSION_API_BASE_URL=https://api.cursion.dev/v1/ops`
- `CURSION_API_TOKEN=Token <your_api_token>`

### Common REST patterns

| Pattern | Meaning |
| --- | --- |
| `POST /<object>` | create or update, depending on endpoint behavior |
| `GET /<object>/<id>` | retrieve one object |
| `DELETE /<object>/<id>` | delete one object |
| `GET /<object>?limit=10&offset=0` | retrieve paginated results |
| `GET /<object>/<id>/lean` | abbreviated retrieval when supported |
| `POST /<object>s/delete` | bulk delete for supported resources |

### Paginated list shape

```json
{
  "count": 30,
  "next": "https://api.cursion.dev/v1/ops/<object>?limit=10&offset=20",
  "previous": "https://api.cursion.dev/v1/ops/<object>?limit=10&offset=10",
  "results": []
}
```

## Workflow Reference

### Workflow: onboard a website

1. Create a `Site`.
2. Allow site crawl and page creation, or pass `page_urls`.
3. Allow baseline `Scans` unless `no_scan=true`.
4. Use resulting `Pages` for future scans, tests, schedules, and reports.

### Workflow: capture current page state

1. Select a `Site` or `Page`.
2. Create a `Scan`.
3. Wait until `time_completed` is populated.
4. Read `html`, `logs`, `lighthouse`, `security`, and `images`.

### Workflow: run regression comparison

1. Select a `Page` or `Site`.
2. Create a `Test`.
3. Wait for terminal `status`.
4. Read `score`, `threshold`, and `component_scores`.
5. Read delta objects for root cause analysis.

### Workflow: generate a browser test

1. Create a `Case` with `site_id` and `prompt`.
2. Receive a `Process`.
3. Poll the `Process`.
4. When complete, fetch the resulting `Case`.

### Workflow: execute a browser test

1. Create a `CaseRun` with `site_id` and `case_id`.
2. Optionally pass `updates` to replace step values by index.
3. Wait for completion.
4. Inspect `passed`, step timestamps, and step exceptions.

### Workflow: run orchestration

1. Define a `Flow`.
2. Create a `FlowRun`.
3. Track top-level `status`.
4. Inspect node runtime fields and `logs`.

### Workflow: schedule recurring work

1. Create a `Schedule`.
2. Set `task_type`, `time`, `timezone`, `begin_date`, and `frequency`.
3. Pass execution config and optional metric type arrays.
4. Optionally attach an `Alert`.

### Workflow: generate a report

1. Create a `Report` with `site_id`.
2. Select section `type`.
3. Set `lookback_days`.
4. Read the PDF from `path`.

## Agent Decision Rules

Use these rules when selecting objects:

- use `Site` for domain-wide tasks
- use `Page` for URL-specific tasks
- use `Scan` for evidence capture
- use `Test` for before-vs-after comparison
- use `Case` for reusable functional workflows
- use `CaseRun` for executed functional workflows
- use `Flow` for reusable orchestration
- use `FlowRun` for executed orchestration
- use `Schedule` for recurring automation
- use `Alert` for threshold-based notifications
- use `Issue` for durable failure tracking
- use `Report` for human-readable summaries
- use `Process` for async generation tracking

## Agent Debugging Rules

Use this order when debugging failures:

1. check top-level status and timestamps
2. inspect the most direct evidence object
3. inspect any generated `Issue`
4. inspect the `Process` if the task was generation-related

Direct evidence priority by object:

- for `Test`: `component_scores`, `images_delta`, `logs_delta`, `html_delta`
- for `CaseRun`: `passed`, `steps`, step exceptions
- for `FlowRun`: `status`, `logs`, node runtime state

## Polling Rules

- Poll `Process` for async generation tasks.
- Poll `Scan`, `Test`, `CaseRun`, and `FlowRun` until completion fields or terminal statuses are present.
- Treat null `time_completed` as still running unless a terminal exception or failure state is present.

## MCP Context

The hosted MCP endpoint documented by Cursion is:

`https://mcp.cursion.dev/sse`

High-level MCP tool groups documented:

- Sites
- Pages
- Scans
- Tests
- Issues
- Cases and CaseRuns
- Flows and FlowRuns
- Processes
- Search

MCP facts:

- authentication still uses the normal Cursion API token
- tools are user-scoped
- the built-in in-app Cursion Agent already has MCP wired in

## Minimum Retrieval Summary

If only a short summary is needed, use this:

- `Site` and `Page` define what is monitored
- `Scan` captures current state
- `Test` compares two states
- `Case` defines browser steps
- `CaseRun` executes browser steps
- `Flow` defines orchestration
- `FlowRun` executes orchestration
- `Issue` records failures
- `Schedule` automates recurring tasks
- `Alert` triggers actions from scheduled results
- `Report` summarizes recent activity
- `Process` tracks asynchronous generation