API Reference

Critical Journey (CJ) is fore ai's AI-powered test automation platform. You describe what a test should do in plain language; an AI pipeline turns that description into executable browser and mobile steps, runs those tests on demand or on a schedule, reports on the results, and can automatically heal tests that break when your app changes.

Base URL

https://cj-backend.foreai.co

All paths in this document are relative to that base URL. An interactive Swagger UI is available at /docs and a ReDoc view at /redoc.

---

Authentication

All endpoints require Authorization: Bearer <token> on each request.

---

Core concepts

Organization is the top-level tenant (your company). It owns members, settings, network proxies, and optional SAML SSO. Almost every resource is scoped to an organization.

Test suite is a project inside an organization — usually one suite per application or website under test. A suite holds your test cases organized into a folder tree, along with suite-level configuration: shared parameters, browser states, notification channels, and reusable test modules.

Test case is a single test described in natural language (name + step-by-step description), pointed at a website or a mobile app binary. When you submit it, the AI generation pipeline produces a sequence of executable steps. A test case moves through a lifecycle captured by its state (see Status enumerations).

Test run is one execution of a generated test case. It records status, timing, per-step results, screenshots, error details, and downloadable artifacts.

Collection is a named grouping of test cases within a suite that can be run together. Collections support a cron schedule, run-setting overrides, and notification channels.

Healing is the self-repair mechanism. When a test breaks because the app's UI changed, CJ produces a healed version, shows a diff against the original, and lets you approve or reject it.

Assets are files you upload — for example, mobile app binaries (.apk / .ipa) or documents used as context for test generation.

Parameters inject data into tests. Shared parameters are key/value pairs reused across tests in a suite; asset parameters reference an uploaded asset file.

Browser state is a saved browser storage snapshot (cookies and local storage) used to start a test already authenticated, skipping the login flow on every run.

Notification channels and reports deliver results. Channels can be Email, Slack, or MS Teams and attach to collections. Reports aggregate metrics and charts for an organization or suite and can be delivered on a daily, weekly, or monthly subscription.

---

A typical workflow

1. Get your organizations — GET /auth/get-user-organizations. The response includes each org's org_id, which you'll need for almost every subsequent call.
2. Pick or create a test suite — GET /organizations/{org_id}/test-suites to list existing suites, or POST /test-suites to create a new one.
3. Create a test case — POST /test-cases/ with a name, plain-language description, website, and test_suite_id. The AI generation pipeline starts immediately.
4. Poll generation state — GET /test-case/state/{test_case_id} repeatedly until state reaches completed (or failed).
5. Run the test — POST /test-run/{test_case_id}, optionally passing RunSettings to override the URL, browser, or parameters.
6. Check results — GET /test-run/{test_run_id} for full detail; GET /artifacts/{test_run_id} to download recordings.
7. Automate — group tests into a collection with a cron schedule and attach a notification channel so failures reach your team.

---

Status enumerations

TestState

State of a test case's generation pipeline.

Value	Meaning
created	Record exists, generation not yet queued
pending	Queued for generation
waiting_for_executor	Waiting for an available runner
running	Actively generating steps
replaying_steps	Re-executing recorded steps
completed	Generation finished successfully
failed	Generation failed
resources_exceeded	Ran out of compute resources
cancelled	Cancelled before completion
aborted	Aborted by the system
error	Internal error during generation
executor_not_available	No executor available

A newly created test case follows this path: pending → waiting_for_executor → running → completed. Poll GET /test-case/state/{test_case_id} every few seconds until state is completed or a terminal state (failed, resources_exceeded, error, executor_not_available).

TestRunStatus

Status of an individual test execution.

Value	Meaning
pending	Run is queued
waiting_for_executor	Waiting for a runner
running	Actively executing
passed	All steps passed
failed	One or more steps failed
not_runnable	Test cannot currently be run
cancelled	Cancelled before completion
aborted	Aborted by the system

---

Error responses

Validation error — a malformed or incomplete request returns 422 Unprocessable Entity:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Generic success message — many mutating endpoints return a ServerMessage:

{ "message": "Operation completed successfully." }

---

What can you do with the API?

The CJ API gives you full programmatic access to the platform: test creation, execution, results, healing, and reporting. Some popular use cases:

Using an LLM as your CJ interface

Drop the OpenAPI schema into any capable LLM available in your organization — Claude, GPT-4, Gemini — and you can talk to CJ in plain English without touching the raw HTTP layer. Ask it to create a test case, kick off a collection run, pull the latest failure report, or check healing status. The model handles parameter construction, endpoint selection, and response parsing. What would take twenty minutes of documentation-reading and curl-wrangling can take thirty seconds of conversation.

Link to internal dashboards and analytics

GET /reports returns structured chart and metric cards you can feed into any internal tool — Grafana, Retool, a data warehouse, whatever your team already uses. The response shape is predictable and typed (metric, list, chart), so it's easy to transform. Scoped to a test_suite_id you get per-project visibility; without it, org-wide aggregates. Pair with a cron job and test health sits alongside deploy frequency, error rates, and pass rates in one place.

Multi-environment coverage

One test case, multiple environments. website_url_override, geolocation_override, accept_language_override, and proxy settings can all be varied per run without touching the underlying test. Running the same suite against multiple deployments simultaneously, with appropriate locale settings for each, is a single orchestration script.