Site Discovery

Discoveries automatically explore a website by spawning multiple agents across several phases. Starting from a URL, agents map pages, forms, and interactions, then the system identifies gaps and sends agents to explore further.

Overview

A discovery is an automated exploration of a website. You provide a starting URL and the system spawns multiple agents that navigate the site, cataloging every page, form, and interaction they find. The result is a structured map of the application that can be used to generate test journeys.

Discoveries run in multiple phases. The first phase explores from the entry URL. After the agents finish, the system analyzes their findings, identifies unexplored areas and gated pages (areas behind login or authentication), and spawns a second wave of agents to cover the gaps. This continues for up to three phases, with up to three agents per phase, progressively building a more complete picture of the site.

Lifecycle

A discovery moves through several statuses: running (agents are actively exploring), building (the system is processing the findings from a phase and deciding whether to spawn more agents), and completed when all phases are done. It can also be stopped manually or failed if something goes wrong.

The final output is an app map: a structured JSON representation of all discovered pages, their relationships, forms, and interactive elements. This map is stored on the project and used as context for future agent runs and journey generation.

POST /api/v1/discoveries

Create a new discovery

Creates a site discovery and enqueues a test run to explore the target URL.

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	body	Yes	ID of the project this site discovery belongs to
`url`	string	body	Yes	Entry URL to start discovering from (https:// is prepended if no scheme is provided)
`persona_id`	uuid	body	No	Optional persona for browser session (cookies, credentials, email)
`role_id`	uuid	body	No	Optional role for prompt injection context (defaults to Discovery role)
`model`	string	body	No	LLM model to use
`browser_type`	string	body	No	Browser to use (chrome, firefox, edge) (default: chrome)
`record_video`	boolean	body	No	Save recordings for all runs. When false (default), only failed runs are saved. (default: false)

Status Codes

Code	Description
`201`	Discovery created
`400`	Validation error
`401`	Unauthorized
`402`	Discovery limit reached
`404`	Project not found

Response Body

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com",
  "status": "running",
  "phase": 1,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

API Key

project_id *

url *

persona_id

role_id

model

browser_type

record_video

cURL

Response

GET /api/v1/discoveries

List discoveries

Parameters

Parameter	Type	In	Required	Description
`limit`	integer	query	No	Number of results to return (default: 20)
`cursor`	uuid	query	No	Cursor for pagination
`project_id`	uuid	query	No	Filter by project ID (alias: project)

Status Codes

Code	Description
`200`	OK
`401`	Unauthorized

Response Body

{
  "discoveries": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "660e8400-e29b-41d4-a716-446655440000",
      "url": "https://example.com",
      "status": "completed",
      "phase": 3,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:00:00Z",
      "completed_at": "2025-01-15T11:00:00Z"
    }
  ],
  "next_cursor": "990e8400-e29b-41d4-a716-446655440000"
}

API Key

limit

cursor

project_id

cURL

Response

GET /api/v1/discoveries/{id}

Get discovery by ID

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Discovery ID

Status Codes

Code	Description
`200`	OK
`400`	Invalid UUID
`401`	Unauthorized
`404`	Discovery not found

Response Body

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com",
  "status": "running",
  "phase": 1,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

API Key

id *

cURL

Response

DELETE /api/v1/discoveries/{id}

Delete a discovery

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Discovery ID

Status Codes

Code	Description
`204`	Discovery deleted
`400`	Invalid UUID
`401`	Unauthorized
`404`	Discovery not found

API Key

id *

cURL

Response

POST /api/v1/discoveries/{id}/stop

Stop a running discovery

Stops all non-terminal test runs in the site discovery and finalizes the app map.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Discovery ID

Status Codes

Code	Description
`200`	Discovery stopped
`400`	Discovery already in terminal state
`401`	Unauthorized
`404`	Discovery not found

Response Body

{
  "discovery": {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "project_id": "660e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com",
    "status": "completed",
    "phase": 3,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T11:00:00Z",
    "completed_at": "2025-01-15T11:00:00Z"
  },
  "agents_stopped": 2
}

API Key

id *

cURL

Response

GET /api/v1/discoveries/{id}/agents

List agents for a discovery

Returns the test runs spawned by this site discovery.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Discovery ID

Status Codes

Code	Description
`200`	OK
`400`	Invalid UUID
`401`	Unauthorized
`404`	Discovery not found

Response Body

{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "660e8400-e29b-41d4-a716-446655440000",
      "project_id": "770e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "prompt": "...",
      "model": "gemini-2.5-flash",
      "browser_type": "chrome",
      "record_video": false,
      "agent_type": "discovery",
      "messages": [],
      "iteration": 20,
      "max_iterations": 115,
      "tokens_used": 8000,
      "discovery_id": "880e8400-e29b-41d4-a716-446655440000",
      "source": "discovery",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:45:00Z"
    }
  ]
}

API Key

id *

cURL

Response