POST /v1/run — Start a New Test Run

The POST /v1/run endpoint accepts a structured browser automation plan and launches it as a background job. The server responds with HTTP 202 and a { ok, id, status } envelope as soon as the run is registered — execution continues asynchronously. Use GET /v1/runs/:id to poll the final result or GET /v1/runs/:id/events/stream for live Server-Sent Events.

Authentication

Pass either an API key via the X-Api-Key header or a JWT via the Authorization: Bearer <token> header. Every request also requires Content-Type: application/json.

Request Body

project

string

required

Slug of an existing project that belongs to your account. The run is associated with this project for filtering and grouping.

baseUrl

string (URL)

required

The root URL of the application under test (e.g. https://app.example.com). All goto step URLs must share the same origin as baseUrl.

steps

Step[]

required

Ordered list of browser actions to execute. At least one step is required for non-assisted runs. Maximum 25 steps by default.

Show Step variants

Each step object must include an action discriminant plus action-specific fields:

`action`	Additional fields
`goto`	`url: string` — absolute URL (same origin as `baseUrl`)
`click`	`selector: string` — CSS / text / role selector
`fill`	`selector: string`, `value: string`
`press`	`key: string` — keyboard key name (e.g. `"Enter"`, `"Tab"`)
`waitForSelector`	`selector: string`, `timeoutMs?: number`
`snapshot`	(no extra fields) — captures accessibility tree snapshot

headless

boolean

default:"true"

Run the Chromium browser in headless mode. Set to false only for local debugging.

captureScreenshotAfterEachStep

boolean

default:"false"

Save a PNG screenshot after every step. Paths are returned in each StepOutcome.screenshotPath.

Capture the full accessibility tree after each step and attach it to the corresponding StepOutcome.a11y field.

recordVideoOnFailure

boolean

default:"false"

Record a WebM video of the session and persist it when the run ends in fail status. The path is returned as RunRecord.videoPath.

artifactsDir

string

default:"artifacts"

Local directory (relative to the runner process) where screenshots and videos are written.

defaultTimeoutMs

number

default:"30000"

Per-step timeout in milliseconds. Must not exceed 120 000 ms. Individual waitForSelector steps may override this via their own timeoutMs field.

contextId

string

Arbitrary string that links this run to an external context, such as a Git commit SHA or CI build ID.

assisted

object

Metadata produced by the Ghostly AI planner (v1). Present when the run was generated by POST /v1/plan.

Show AssistedMeta fields

assisted.goal

string

required

Natural-language goal the AI used to generate the plan.

assisted.model

string

required

LLM model identifier used at plan time (e.g. "gpt-4o").

assisted.generatedAt

string (ISO 8601)

required

Timestamp when the plan was generated.

assisted.promptVersion

string

required

Internal version of the planning prompt template.

assist

object

Enables AI-assisted v2 mode — the engine drives the browser autonomously toward a goal using horizon-based planning and self-healing. Cannot be combined with a manually authored steps array as the primary plan.

Show AssistV2 fields

assist.v2

true

required

Must be the literal true to activate v2 mode.

assist.goal

string

required

Natural-language description of what the test should accomplish.

assist.isFullPlan

boolean

When true, the planner treats the initial step list as a complete plan rather than a seed.

assist.maxHealingAttemptsPerStep

number

How many times the healer may retry a failing step (0–3).

assist.observerMaxNodes

number

Maximum nodes included in the accessibility-tree snapshot sent to the LLM (50–1000).

assist.victory

object

Optional exit criteria. The run is marked pass as soon as all specified conditions are met.

Show Victory conditions

assist.victory.textIncludes

string[]

Page must contain all listed text strings.

assist.victory.selectorVisible

string[]

All listed selectors must be visible.

assist.victory.urlIncludes

string[]

Current URL must include all listed substrings.

assist.victory.mustAll

boolean

When true, every condition must be satisfied simultaneously.

assist.maxHorizons

number

Maximum planning horizons before the run fails (1–50).

assist.stepsPerHorizon

number

Steps planned per horizon iteration (1–10).

assist.maxLoopMs

number

Hard wall-clock timeout for the entire assisted loop in milliseconds (10 000–3 600 000).

Maximum time in milliseconds to wait for modal loading indicators to disappear before planning or between steps (3 000–600 000).

assist.memoryMode

"off" | "runtime" | "adaptive"

Controls whether learned step sequences are persisted and replayed. "adaptive" seeds the run with the most-recently successful flow for the same goal and project.

codeHints

object

Static context about the application’s component library, forms, routes, and selectors. Helps the AI planner produce more accurate selectors.

Show CodeHints fields

codeHints.components

array

List of UI component descriptors with optional testIds, ariaLabels, and roles.

codeHints.forms

array

Form descriptors including input fields (testId, ariaLabel, id, name, placeholder, type) and submit button info.

codeHints.routes

array

Application routes with path and optional component name.

codeHints.selectors

object

Lookup maps: byTestId and byAriaLabel keyed by semantic name.

plan

object

An alternative envelope for passing run configuration, used by the Ghostly MCP submit_plan tool. Top-level fields take precedence over any matching keys inside plan.

Guardrails

The server enforces the following hard limits regardless of what you pass:

Guardrail	Default
`maxSteps`	25
`maxTimeoutMs`	120 000 ms
`enforceSameOrigin`	`true` — all `goto` URLs must share the origin of `baseUrl`

Responses

true

Always true on a successful 202 response.

string (UUID)

Unique identifier for the newly created run. Use it with GET /v1/runs/:id, POST /v1/runs/:id/cancel, and the SSE stream endpoint.

status

"running"

Always "running" in the 202 response — the run has been accepted and is executing in the background.

Error Responses

Status	Body
`400`	`{ ok: false, error: "validación", details: object }` — Zod validation failure
`400`	`{ ok: false, error: "project requerido" }` — missing or blank `project` field
`400`	`{ ok: false, error: "project inválido" }` — project not found for your account
`400`	`{ ok: false, error: "codeHints inválido", details: object }`
`400`	`{ ok: false, error: "assisted inválido", details: object }`
`400`	`{ ok: false, error: "assist inválido", details: object }` — `assist` object failed validation
`409`	`{ ok: false, error: "assist v2 deshabilitado" }` — v2 not enabled on this server
`500`	`{ ok: false, error: "no se pudo crear run", message: string }`

Examples

curl -X POST https://api.ghostly.dev/v1/run \
  -H "X-Api-Key: gly_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "baseUrl": "https://staging.example.com",
    "steps": [
      { "action": "goto", "url": "https://staging.example.com/login" },
      { "action": "fill", "selector": "#email", "value": "user@example.com" },
      { "action": "fill", "selector": "#password", "value": "s3cr3t" },
      { "action": "click", "selector": "button[type=submit]" },
      { "action": "waitForSelector", "selector": ".dashboard", "timeoutMs": 10000 }
    ],
    "captureScreenshotAfterEachStep": true,
    "recordVideoOnFailure": true
  }'

The run executes in the background — the 202 response is returned before the browser flow completes. Use GET /v1/runs/:id to poll the final result, or subscribe to GET /v1/runs/:id/events/stream for real-time progress events.

Overview

Authentication

Runs

Projects

Settings

POST /v1/run — Start a New Test Run

Authentication

Request Body

Guardrails

Responses

Error Responses

Examples

Build docs developers (and LLMs) love

Overview

Authentication

Runs

Projects

Settings

Documentation Index

​Authentication

​Request Body

​Guardrails

​Responses

​Error Responses

​Examples

Build docs developers (and LLMs) love

Authentication

Request Body

Guardrails

Responses

Error Responses

Examples