REST API

The web application talks to the server through a JSON REST API under /api. You can use it to automate anything the application does: import tests, start runs, collect results.

Conventions

Base URL	http://127.0.0.1:4100/api (or your server’s address)
Format	JSON request and response bodies (content-type: application/json)
Authentication	A session cookie (atx_session) from POST /api/auth/login. Every route requires it except sign-in, registration and password reset.
Project	List and create routes act on the project named in the x-project-id header. Routes for one record (/api/tests/:id) use that record’s own project.
Errors	{ "error": "message" }, with issues for validation errors. 401 not signed in, 403 not allowed, 404 not found, 409 conflict (e.g. a Ready test), 422 invalid, 429 too many sign-in attempts.
Permissions	Exactly as in the app: see roles

The cookie is HttpOnly and SameSite=Strict, so use a cookie jar (as below) rather than reading it.

Worked example: import a test, run it, read the result

# 1. Sign in (stores the session cookie in cookies.txt)
curl -s -c cookies.txt -H "content-type: application/json" \
     -d '{"email":"you@example.com","password":"…"}' \
     http://127.0.0.1:4100/api/auth/login

# 2. Find your project and environment ids
curl -s -b cookies.txt http://127.0.0.1:4100/api/context
curl -s -b cookies.txt -H "x-project-id: prj_…" http://127.0.0.1:4100/api/environments

# 3. Import a test file
curl -s -b cookies.txt -H "content-type: application/json" -H "x-project-id: prj_…" \
     --data @examples/create-purchase-order.json \
     http://127.0.0.1:4100/api/tests/import
#  → { "test": { "id": "tc_…", … }, "version": 1, … }

# 4. Start a run
curl -s -b cookies.txt -H "content-type: application/json" -H "x-project-id: prj_…" \
     -d '{"testId":"tc_…","environmentId":"env_…"}' \
     http://127.0.0.1:4100/api/runs
#  → { "runId": "run_…" }

# 5. Get the result: 202 while running, 200 when finished
curl -s -b cookies.txt http://127.0.0.1:4100/api/runs/run_…
#  → { "status": "passed", "passed": 18, "total": 18, "durationMs": 5025, "result": { "steps": [ … ] }, … }

For live progress, read the server-sent events stream GET /api/runs/:id/events instead of polling. Events are run.started, step.started, step.retry, step.finished, artifact, log and run.finished.

Endpoints

Authentication and session

Method	Path	Body / notes
POST	/api/auth/login	{ email, password }. Sets the session cookie. Public.
POST	/api/auth/logout	Ends the session
GET	/api/auth/session	The signed-in user, or null. Public.
POST	/api/auth/register	{ name, email, password }. Self-registration. Public.
POST	/api/auth/forgot	{ email }. Sends (prints) a reset link. Public.
POST	/api/auth/reset	{ token, password }. Public.
POST	/api/auth/password	{ currentPassword, newPassword }. Change own password; signs out your other sessions.
GET	/api/context	Signed-in user, organizations and projects with your role in each
GET	/api/profile	Your profile and recent runs
GET	/api/roles	The role → permission matrix

Tests

Method	Path	Notes
GET	/api/tests	Tests you can see in the project
POST	/api/tests	Create from a test document
POST	/api/tests/import	Import a DSL document: migrated, validated, new id, shared, owned by you
GET	/api/tests/:id	Current version, with owner, visibility and what you can do (can)
PUT	/api/tests/:id	Save. A Draft is saved over its current version; 422 with issues if invalid; 409 for a Ready or Deprecated test.
DELETE	/api/tests/:id	Delete the test and all versions
POST	/api/tests/:id/validate	Validate a document without saving
POST	/api/tests/:id/revisions	Start a new Draft revision of a Ready test
POST	/api/tests/:id/duplicate	Copy into a new Draft you own
PUT	/api/tests/:id/sharing	{ visibility?, ownerId? }
GET	/api/tests/:id/versions	Version history
GET	/api/tests/:id/versions/:version	One version
POST	/api/tests/:id/versions/:version/restore	Restore as a new version
POST	/api/script	The readable Script rendering of a test document
POST	/api/scripts/try	Try a custom code snippet (editor’s Run code)
GET	/api/registry	Step types and their parameters

Runs

Method	Path	Notes
GET	/api/runs	Runs in the project
POST	/api/runs	{ testId, environmentId?, headed?, screenshots? } → { runId }. screenshots defaults to every step; false limits to failures.
GET	/api/runs/:id	The result. 202 while running.
GET	/api/runs/:id/events	Server-sent events, live
GET	/api/runs/:id/artifacts/:name	A screenshot or other artifact
GET	/api/runs/:id/rows/:row	One row’s full result in a data-driven run
GET	/api/runs/:id/rows/:row/artifacts/:name	A row’s artifact
GET	/api/dashboard	Dashboard figures

Environments, secrets, applications

Method	Path	Notes
GET / POST	/api/environments	List; create or update ({ id?, name, variables, secrets, applicationId? })
DELETE	/api/environments/:id
GET / POST	/api/secrets	Secret inventory; set a secret: { environmentId, name, value }
GET / POST	/api/applications	List; create or update
DELETE	/api/applications/:id

Secret values are write-only: no endpoint returns them.

Suites, components, test data

Method	Path	Notes
GET / POST	/api/suites	List; add
PUT / DELETE	/api/suites/:name	Rename (moves its tests); delete (only when empty)
GET / POST	/api/components	List; create from a source test
GET / PUT / DELETE	/api/components/:id	Detail with versions and usages; update name/description; delete
POST	/api/components/:id/versions	Publish a new version
GET	/api/components/:id/versions/:version	One version
GET	/api/components/:id/impact	What upgrading each caller would change
POST	/api/components/:id/upgrade	Upgrade chosen callers
GET / POST	/api/test-data	Data sets: list; create or update
GET / DELETE	/api/test-data/:id
GET / POST	/api/data-pools	Pools: list; create or update
GET / DELETE	/api/data-pools/:id
POST	/api/data-pools/:id/reset	Release leases or restore consumed records

Recording, picking, AI

Method	Path	Notes
POST	/api/record/start	Start a recording session
GET	/api/record/:id	Captured steps so far
POST	/api/record/:id/stop	Stop
GET	/api/record/:id/preview	Screenshot where recording ended
POST	/api/pick/start, /api/pick/:id/mode, /api/pick/:id/close	Element picker session
GET	/api/pick/:id	Picked element and its locators
POST	/api/language/generate	{ text, testId?, environmentId? } → draft steps (needs ANTHROPIC_API_KEY)
GET / POST / DELETE	/api/language/examples	The project’s learned examples

People and tenancy

Method	Path	Notes
GET / POST	/api/members	Sign-in accounts (platform administrators)
DELETE	/api/members/:id
POST	/api/orgs	Create an organization
PUT / DELETE	/api/orgs/:id	Rename / delete
GET / POST	/api/orgs/:id/members	List / invite
PUT / DELETE	/api/orgs/:id/members/:userId	Change organization role / remove
GET / POST	/api/orgs/:id/projects	List / create projects
PUT / DELETE	/api/projects/:id	Rename / delete a project
GET	/api/projects/:id/members	Project members
PUT / DELETE	/api/projects/:id/members/:userId	Set / remove a project role
GET / POST	/api/settings	The project’s suite list: { modules: [...] }

AutoTestX Agent

Method	Path	Notes
GET	/api/agent	Your paired computers and whether an agent is needed
DELETE	/api/agent/:id	Disconnect a computer
GET	/api/agent/download	The Windows agent installer
GET / POST	/api/agent/pair/:code	Pairing approval
WebSocket	/api/agent/connect	The agent’s own connection (authenticated in its first message)

Security notes

• Every route requires a session unless it is explicitly public. The check is central, so a new route cannot accidentally be left open.
• A record from another project is refused even with a valid id, and the attempt is written to the audit log (audit.log in the data folder).
• Passwords are stored as scrypt hashes; session and reset tokens only as SHA-256 digests.