Ghostly REST API: Runs, Projects, and Settings

The Ghostly API is a locally-hosted HTTP service that gives you programmatic access to every capability exposed by the Ghostly dashboard: starting and monitoring browser-automation runs, managing projects, generating AI-assisted test plans, handling user accounts, and configuring the LLM back-end. All communication uses standard JSON over HTTP, and the server starts automatically when you run ghostly up (or the bundled CLI).

Base URL & Versioning

The server binds to http://localhost:4000 by default. You can change the port with the --port flag or by setting API_PORT (or PORT) in your environment before launching the server. Every endpoint described in this reference lives under the /v1 path prefix:

http://localhost:4000/v1/<resource>

The single exception is the health-check endpoint (GET /health), which sits at the root and requires no authentication.

API_PORT takes precedence over PORT. If neither is set, the server falls back to port 3000 as the hard-coded default. The CLI (ghostly up) defaults to 4000, so make sure both sides use the same value when customising the port.

Authentication

Ghostly supports two authentication methods. Most routes accept either; a small number (API-key management, SSE event streams) are tied to one specific method.

API Key (X-Api-Key)
JWT Bearer Token

Pass your API key in the X-Api-Key request header:

curl http://localhost:4000/v1/runs \
  -H "X-Api-Key: <your-api-key>"

API keys are opaque 64-character hex strings (32 random bytes). Generate one with:

CLI — ghostly keygen
Dashboard — Settings → API Keys → Create

API key auth is the right choice for the CLI, MCP server (@ghostly-io/cli), the @ghostly-io/client SDK, CI pipelines, and any automated script where storing a long-lived credential is acceptable.

Exchange your email and password for a short-lived JWT by calling POST /v1/auth/login, then pass the token as a Bearer credential:

# 1 — Obtain a token
TOKEN=$(curl -s -X POST http://localhost:4000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@ghostly.local","password":"admin123"}' \
  | jq -r .token)

# 2 — Use the token
curl http://localhost:4000/v1/runs \
  -H "Authorization: Bearer $TOKEN"

Tokens are signed with HMAC-SHA256 using the value of the JWT_SECRET environment variable (default: "ghostly-secret") and expire after 7 days.JWT auth is used by the web dashboard and by the SSE event-stream endpoint, which accepts the token via a ?token= query parameter because the browser’s EventSource API does not support custom headers.

Change JWT_SECRET and the default admin password (admin123) before exposing the API on any network interface reachable by other machines. The defaults are designed for local-only use only.

Content Type & Request Bodies

All request bodies must be JSON. Set the header on every mutating request:

Content-Type: application/json

Responses are always JSON, including errors.

Error Format

Every error response follows a consistent envelope:

{
  "ok": false,
  "error": "human-readable message",
  "details": {}
}

The details field is optional and only present when additional structured context is available. Successful responses always include "ok": true at the top level.

Endpoint Summary

Method	Path	Auth	Description
`POST`	`/v1/auth/login`	None	Exchange credentials for a JWT token
`POST`	`/v1/auth/register`	JWT or API key (admin role)	Create a new user account
`GET`	`/v1/auth/me`	JWT or API key	Return the currently authenticated user
`POST`	`/v1/run`	API key or JWT	Start a browser-automation run
`GET`	`/v1/runs`	API key or JWT	List all runs (filterable by project)
`GET`	`/v1/runs/:id`	API key or JWT	Get the full detail of a single run
`POST`	`/v1/runs/:id/cancel`	API key or JWT	Cancel a run that is currently executing
`GET`	`/v1/runs/:id/events/stream`	JWT (via `?token=`)	SSE stream of live run events
`POST`	`/v1/plan`	API key or JWT	Generate an AI step plan from a natural-language goal
`GET`	`/v1/projects`	API key or JWT	List all projects
`POST`	`/v1/projects`	API key or JWT	Create a new project
`DELETE`	`/v1/projects/:id`	API key or JWT	Delete a project
`GET`	`/v1/api-keys`	JWT	List API keys for the current user
`POST`	`/v1/api-keys`	JWT	Create a new API key
`DELETE`	`/v1/api-keys/:id`	JWT	Delete an API key
`GET`	`/v1/settings/llm`	JWT	Get the current LLM configuration
`PUT`	`/v1/settings/llm`	JWT	Update LLM provider and model settings
`POST`	`/v1/settings/llm/test`	JWT	Test the current LLM connection
`GET`	`/v1/settings/llm/providers`	JWT	List available LLM providers
`GET`	`/v1/settings/llm/models`	JWT	List models for a given provider
`GET`	`/v1/ping`	JWT or API key	LLM configuration state and server status
`GET`	`/health`	None	Server health check

Quick Examples

With API Key
With JWT Bearer
Health Check

# List projects
curl http://localhost:4000/v1/projects \
  -H "X-Api-Key: <your-api-key>"

# Start a run
curl -X POST http://localhost:4000/v1/run \
  -H "X-Api-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://example.com",
    "project": "my-project",
    "steps": [
      { "action": "goto", "url": "https://example.com" },
      { "action": "snapshot" }
    ]
  }'

# Login
TOKEN=$(curl -s -X POST http://localhost:4000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@ghostly.local","password":"admin123"}' \
  | jq -r .token)

# List API keys
curl http://localhost:4000/v1/api-keys \
  -H "Authorization: Bearer $TOKEN"

# Get current user
curl http://localhost:4000/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:4000/health
# { "status": "ok" }

Explore the API

Authentication

Start a Run

Fire off a browser-automation run from a step list or an AI-generated plan.

Projects

Organise runs into projects, create new ones, and clean up old entries.

LLM Settings

Configure the AI provider and model Ghostly uses to generate and heal test plans.

Overview

Authentication

Runs

Projects

Settings

Ghostly REST API: Runs, Projects, and Settings

Base URL & Versioning

Authentication

Content Type & Request Bodies

Error Format

Endpoint Summary

Quick Examples

Explore the API

Authentication

Start a Run

Projects

LLM Settings

Build docs developers (and LLMs) love

Overview

Authentication

Runs

Projects

Settings

Documentation Index

​Base URL & Versioning

​Authentication

​Content Type & Request Bodies

​Error Format

​Endpoint Summary

​Quick Examples

​Explore the API

Authentication

Start a Run

Projects

LLM Settings

Build docs developers (and LLMs) love

Base URL & Versioning

Authentication

Content Type & Request Bodies

Error Format

Endpoint Summary

Quick Examples

Explore the API