Discoveries

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 tests.

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 test generation.

List discoveries

Parameters

Example Request

curl "http://app.aiqaramba.com/api/v1/discoveries" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)

Start a discovery

Creates a discovery against the given entry URL and returns it in the pending state; a background coordinator then runs the pipeline — an optional login stage using the supplied credentials, a deterministic crawl, and a review producing suggested tests and findings. Poll GET /discoveries/{id} to follow progress. Credentials are write-only and never returned; supply non-sensitive test credentials only — they are shared with an LLM during login.

Request Body (application/json)

Example Request

curl -X POST "http://app.aiqaramba.com/api/v1/discoveries" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "<uuid>",
    "entry_url": "https://example.com"
  }'

Status Codes

Response Fields (201)

Get a discovery

Parameters

Example Request

curl "http://app.aiqaramba.com/api/v1/discoveries/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)

Delete a discovery

Parameters

Example Request

curl -X DELETE "http://app.aiqaramba.com/api/v1/discoveries/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Cancel a discovery

Requests cancellation of a non-terminal discovery. Cancellation is asynchronous: the run stops at its next safe point and moves to the canceled state. The response echoes the discovery with cancel_requested set; poll GET /discoveries/{id} for the terminal state.

Parameters

Example Request

curl -X POST "http://app.aiqaramba.com/api/v1/discoveries/<id>/cancel" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)

Get the crawled map

Returns the state-flow graph discovered so far: one node per distinct UI state, one edge per observed transition. Available while the crawl is still running — nodes and edges appear as they are discovered.

Parameters

Example Request

curl "http://app.aiqaramba.com/api/v1/discoveries/<id>/map" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)

List a discovery's suggestions

Returns the reviewer's drafted tests and findings for a discovery. Populated once the review stage completes; empty before then. These are drafts — accepting one into a real test or finding is a separate action.

Parameters

Example Request

curl "http://app.aiqaramba.com/api/v1/discoveries/<id>/suggestions" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)