Case

A Case is used to store a list of instructions, called steps which are utilized by the CaseRun object during a run. Each step contains two primary subcomponents:

Component	Description
action	an object which describes the action to be taken, e.g. "click", "navigate", "change" etc.
assertion	an object which describes an assertion to be tested e.g. "match", "exists"

Case object

{
   "id":"e458dbb0-0d29-4d01-a67a-b39899614504",       // uuid specific to the case
   "title":"Contact form",                            // desctiptive title 
   "time_created":"2022-06-30T14:41:14.541196Z",      // timestamp of Case creation
   "user": "admin",                                   // username of Case creator
   "steps": {                                         // step data
      "url": "https://storage-scanerr.sfo3.digitaloceanspaces.com/static/cases/2fb0071d-da58-4b75-b4f2-91f984d3cbd9/fee5558e-fb79-42b7-985b-30839a7e809d.json",
      "num_steps": 16
   },
   "tags": [null],                                    // optional tags object
   "account": "76a0f3a8-e8d0-469e-8830-0584a481206d", // account id
   "site": "72eba795-becb-41b0-8afd-af8481e9570c",    // associated site id
   "type": "generated",                               // one of "generated" or "recorded"
   "site_url": "https://styleofmen.com",              // url string of associated site
   "processed": true                                  // true if Case has completed a pre-run
}

Step object

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

Create a Case

Use this endpoint to generate a new Case object. This endpoint retuns a Process object, which can be fetched to determine the status of the the request.

data in this request:

"data": {
   "site_id"   : "72eba795-becb-41b0-8afd-af8481e9570c",             // <required> uuid of the associated site
   "max_layers": 10,                                                 // maximum number of steps the system should generate | overages can occur
   "prompt"    : "Create a Case that tests my sites's contact form."  // <required> The prompt telling the LLM what kind of Case to generate.
}

POST - /case/generate

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{CURSION_API_BASE_URL}/case'
headers = {
   "content-type": "application/json",
   "Authorization" : CURSION_API_TOKEN
}
data = {
   "site_id"   : "72eba795-becb-41b0-8afd-af8481e9570c",
   "max_layers": 10,
   "prompt"    : "Create a Case that tests my sites's contact form."
}

# send the request
res = requests.post(
   url=url,
   headers=headers,
   data=json.dumps(data)
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "id": "dbd7d10c-2a51-4ba2-abb2-7efa82516c89",
   "site": "72eba795-becb-41b0-8afd-af8481e9570c",
   "type": "case.generate",
   "time_created": "2026-05-01T19:52:24.226311Z",
   "time_completed": null,
   "success": false,
   "info_url": null,
   "progress": 1.0,
   "info": {
      "task_id": "5de0b5e2-ad4e-4c7e-a01f-644af0a50731"
   },
   "exception": null,
   "object_id": null
}

Retrieve a Case

This endpoint returns a single Case object and is useful as a simple "detailed view" of the case.

GET - /case/<case:id>

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/case/<case:id>'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.get(
    url=url,
    headers=headers,
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "id":"e458dbb0-0d29-4d01-a67a-b39899614504",       
   "title":"Contact form",                          
   "time_created":"2022-06-30T14:41:14.541196Z",  
   "user": "admin",                                
   "steps": {                                         
      "url": "https://storage-scanerr.sfo3.digitaloceanspaces.com/static/cases/2fb0071d-da58-4b75-b4f2-91f984d3cbd9/fee5558e-fb79-42b7-985b-30839a7e809d.json",
      "num_steps": 16
   },
   "tags": [null],                                    
   "account": "76a0f3a8-e8d0-469e-8830-0584a481206d",
   "site": "72eba795-becb-41b0-8afd-af8481e9570c",    
   "type": "generated",                              
   "site_url": "https://styleofmen.com",             
   "processed": true
}

Retrieve many Cases

This endpoint returns a paginated response with all Cases objects filtered by your account and ordered by time_created. This endpoint is useful when needing to displaying your cases in a table view for example.

The limit parameter specifies the total number of objects you want returned per "group" (we recommend keeping this under 10 for best performance). The offset parameter specfies which "group" to return. For example, limit=10&offset=10 in a total dataset of 30 objects would return 10 cases in range case #10 - case #20.

Info

You may optionally pass a site_id to filter the Cases by a specific Site.

GET - /case?limit=10&offset=0

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/case?limit=10&offset=0'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.get(
    url=url,
    headers=headers,
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "count":30,
   "next":"https://api.cursion.dev/v1/ops/case?limit=10&offset=20",
   "previous":"https://api.cursion.dev/v1/ops/case?limit=10&offset=10", 
   "results":[
      {
         "id":"e458dbb0-0d29-4d01-a67a-b39899614504",       
         "title":"Contact form",                          
         "time_created":"2022-06-30T14:41:14.541196Z",  
         "user": "admin",                                
         "steps": {                                         
            "url": "https://storage-scanerr.sfo3.digitaloceanspaces.com/static/cases/2fb0071d-da58-4b75-b4f2-91f984d3cbd9/fee5558e-fb79-42b7-985b-30839a7e809d.json",
            "num_steps": 16
         },
         "tags": [null],                                    
         "account": "76a0f3a8-e8d0-469e-8830-0584a481206d",
         "site": "72eba795-becb-41b0-8afd-af8481e9570c",    
         "type": "generated",                              
         "site_url": "https://styleofmen.com",             
         "processed": true
      },
      {
         "id":"e458dbb0-0d29-4d01-a67a-b39899614504",
         "time_created":"2022-06-30T14:41:14.541196Z",   
         "title":"Check out flow",                          
         "user": "admin",                                
         "steps": {                                         
            "url": "https://storage-scanerr.sfo3.digitaloceanspaces.com/static/cases/2fb0071d-da58-4b75-b4f2-91f984d3cbd9/fee5558e-fb79-42b7-985b-30839a7e809d.json",
            "num_steps": 16
         },
         "tags": [null],                                    
         "account": "76a0f3a8-e8d0-469e-8830-0584a481206d",
         "site": "72eba795-becb-41b0-8afd-af8481e9570c",    
         "type": "generated",                              
         "site_url": "https://styleofmen.com",             
         "processed": true
      }
            
      ### SHORTENED FOR DISPLAY PURPOSES ###
   ]
}

Delete a Case

Caution

Please use caution with this endpoint as it is irreversible.

DELETE - /case/<case:id>

import requests, os

# import env vars
CURSION_API_BASE_URL = os.environ.get('CURSION_API_BASE_URL')
CURSION_API_TOKEN = os.environ.get('CURSION_API_TOKEN')

# setup configs
url = f'{BASE_URL}/case/<case:id>'
headers = {
    "content-type": "application/json",
    "Authorization" : CURSION_API_TOKEN
}

# send the request
res = requests.delete(
    url=url, 
    headers=headers, 
)

# retrieve response data
json_response = res.json()
print(json_response)

View Full Output

{
   "message": "case deleted successfully"
}