Documentation › REST API Reference

REST API Reference

Reference Programmatic access to cases, runs, suites, parameters and files.

Everything you do in the MaxTAF UI is backed by a REST API you can call yourself — to trigger a run from a pipeline, import a case, or pull results into a dashboard. Requests authenticate with an API key and a project id.

On this page

Base URL & paths
Authentication
Triggering runs
Reading results
Cases
Suites
Parameters
Files

Base URL & path model

SaaS base URL: https://mx1.maxtaf.com (on-premises: your own host).
Every endpoint is reached through the gateway with a service prefix. Two you'll use: /api/maxtaf (cases, runs, suites, params) and /api/storage (files).

So a "run a case by name" call is POST https://mx1.maxtaf.com/api/maxtaf/cases/name/api/runs.

Scope of this reference

This documents the customer-facing endpoints. The same credential technically reaches administrative and engine-internal routes too, but those are not part of the supported public surface and may change — don't build against them.

Authentication

Send your API key and project id as headers on every request:

X-Maxtaf-Api-Key: mx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Project-Id: your_project_id
Accept: application/json

Get your API key from Admin ▸ User Settings; you can invalidate and regenerate it there.
The key may also be sent as Authorization: Bearer <key>, and both tokens can be supplied as query parameters if headers are inconvenient (?X-Project-Id=…).
Treat the key like a password — see Security & Compliance.

Triggering runs

Use the /api/runs variants (they take a lightweight run-details body). Runs can be synchronous (SYNC — the call blocks until the run finishes) or asynchronous (ASYNC — returns immediately; poll for the result).

Method & path	Purpose
`POST /api/maxtaf/cases/name/api/runs?testName=<name>`	Run a case by name.
`POST /api/maxtaf/cases/{caseId}/api/runs`	Run a case by id.
`POST /api/maxtaf/suites/name/api/runs?suiteName=<name>`	Run a suite by name.
`POST /api/maxtaf/suites/{suiteId}/api/runs`	Run a suite by id.
`PUT /api/maxtaf/runs/{runResultId}/stop`	Stop a run.

The request is multipart/form-data with a JSON runDetails part (and an optional dataDrivenFile). Fields:

Field	Meaning	Default
`repeatRun`	How many times to run.	`1`
`syncAsync`	`SYNC` or `ASYNC`.	`ASYNC`
`parallelSerial`	Multi-run execution mode.	`SERIAL`
`dataDrivenParallelSerial`	Data-driven row execution mode.	`SERIAL`
`runParams`	Extra parameters for this run.	`""`
`runParamsType`	How `runParams` merge: `PRIORITY`, etc.	`PRIORITY`
`parentRunId`	Link this run under a parent.	`null`

Example — run a case by name and wait for the result

curl "https://mx1.maxtaf.com/api/maxtaf/cases/name/api/runs?testName=Nightly_WO_Smoke" \
  -H "X-Maxtaf-Api-Key: mx-xxxx" \
  -H "X-Project-Id: acme_maximo_regression" \
  -H "X-User-TimeZone-Id: Europe/London" \
  -H "Accept: application/json" \
  -F 'runDetails={
        "repeatRun": "1",
        "syncAsync": "SYNC",
        "parallelSerial": "SERIAL",
        "runParams": "",
        "runParamsType": "PRIORITY",
        "parentRunId": null
      };type=application/json'

The response contains the run result (id, state, result). For a CI gate, run SYNC and check the result field, or run ASYNC and poll the run endpoint. See CI/CD Integration for a complete pipeline recipe.

Reading run results

Method & path	Purpose
`GET /api/maxtaf/runs`	List runs (paged; filter by state, case, dates via query params).
`GET /api/maxtaf/runs/{id}`	Get one run — its state, result, start/complete dates and duration.
`GET /api/maxtaf/runs/summary`	Aggregate summary for a filter.
`GET /api/maxtaf/runs/{parentId}/children`	Child runs of a suite run.
`GET /api/maxtaf/runs/{id}/failures`	Failure messages/stack traces for a run.
`GET /api/maxtaf/runReport/{runResultId}`	The run's report.
`DELETE /api/maxtaf/runs/{id}`	Delete a run result.

A run's result tells you pass/fail; its state tells you whether it's finished. See run states for the full list.

Cases

Method & path	Purpose
`GET /api/maxtaf/cases`	List cases (paged; `CaseFilter` query params).
`GET /api/maxtaf/cases/{caseId}`	Get one case.
`GET /api/maxtaf/cases/name?caseName=<name>`	Get an active case by name.
`POST /api/maxtaf/cases`	Create a case (JSON `CaseDTO` body; optional `?templateName=`).
`PUT /api/maxtaf/cases/{caseId}`	Update a case.
`PUT /api/maxtaf/cases/{caseId}/params`	Update a case's parameters.
`POST /api/maxtaf/cases/{caseId}/duplicate`	Duplicate a case.
`DELETE /api/maxtaf/cases/{caseId}`	Move a case to the Bin.
`POST /api/maxtaf/import/cases?overwrite=false&compile=false`	Import/create cases from a file (multipart `importFile`). This is the recorder's upload path.
`GET /api/maxtaf/export/json/cases` · `…/xml/cases`	Export cases as JSON or XML.
`POST /api/maxtaf/export/transfer/cases/{caseId}?projectIds[]=`	Copy a case into other projects.

Example — import a case file

curl -X POST "https://mx1.maxtaf.com/api/maxtaf/import/cases?overwrite=false&compile=false" \
  -H "X-Maxtaf-Api-Key: mx-xxxx" \
  -H "X-Project-Id: acme_maximo_regression" \
  -H "Accept: application/json" \
  -F "importFile=@testcase.json"

The CaseDTO shape

Key fields: name, caseType (e.g. MXML, JAVA, AI), testingFramework, platform, code, params, description, pageObject. Importing uses a versioned JSON file (version: "2" with a cases array).

Suites

Method & path	Purpose
`GET /api/maxtaf/suites` · `…/suites/{suiteId}` · `…/suites/name?suiteName=`	List / get a suite.
`POST /api/maxtaf/suites` · `PUT …/suites/{suiteId}`	Create / update a suite.
`DELETE /api/maxtaf/suites/{suiteId}`	Move a suite to the Bin.
`GET /api/maxtaf/suites/cases/{caseId}`	Which suites contain a case.
`POST /api/maxtaf/import/suites` · `GET …/export/json/suites`	Import / export suites (includes their cases).
`POST /api/maxtaf/caseSuites/parent/{parentId}`	Add a case/suite to a suite.
`PUT /api/maxtaf/caseSuites/{caseSuiteId}/changeSequence`	Reorder a suite member (controls parallelism).

Project parameters

Method & path	Purpose
`GET /api/maxtaf/projectRunParams/list`	List all project parameters.
`GET /api/maxtaf/projectRunParams/findOne?paramName=<name>`	Get one parameter.
`PUT /api/maxtaf/projectRunParams`	Set a parameter (JSON `{name, value, …}`).
`PUT /api/maxtaf/projectRunParams/increment?paramName=<name>`	Increment a numeric parameter.
`DELETE /api/maxtaf/projectRunParams?paramName=<name>`	Delete a parameter.
`POST /api/maxtaf/import/projectParams` · `GET …/export/json/projectParams`	Import / export parameters.

Reserved mx.* parameters

Parameters whose names start with mx. are reserved/standard and can't be freely created through this API — set your own values, and use custom names for your own variables. See the Parameter reference.

Files (project file system)

Under the /api/storage prefix:

Method & path	Purpose
`GET /api/storage/files/name?directory=<dir>`	List file names in a directory.
`GET /api/storage/files?pathWithName=<path>`	Read a file.
`GET /api/storage/files/download?pathsWithNames=<…>`	Download files.
`POST /api/storage/files?pathWithName=&contents=&overwrite=false`	Create a file.
`PUT /api/storage/files?pathWithName=<path>`	Update a file (raw body).
`POST /api/storage/files/upload`	Upload a file (multipart `importFile` + `uploadPath`). Useful for data-driven CSVs.
`POST /api/storage/files/zip` · `…/files/unzip`	Zip / unzip.
`DELETE /api/storage/files?pathWithName=<path>`	Delete a file.
`POST /api/storage/folders?path=&folderName=&overwrite=false`	Create a folder.

CI/CD Integration shows these endpoints in a full pipeline. For data handling and key hygiene, see Security & Compliance.