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: /agents.md

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

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:

{
  "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:

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

Canonical action schema:

{
  "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

{
  "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

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

Workflow: capture current page state

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

Workflow: run regression comparison

Select a Page or Site.
Create a Test.
Wait for terminal status.
Read score, threshold, and component_scores.
Read delta objects for root cause analysis.

Workflow: generate a browser test

Create a Case with site_id and prompt.
Receive a Process.
Poll the Process.
When complete, fetch the resulting Case.

Workflow: execute a browser test

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

Workflow: run orchestration

Define a Flow.
Create a FlowRun.
Track top-level status.
Inspect node runtime fields and logs.

Workflow: schedule recurring work

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

Workflow: generate a report

Create a Report with site_id.
Select section type.
Set lookback_days.
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:

check top-level status and timestamps
inspect the most direct evidence object
inspect any generated Issue
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