REST API¶

The new HTTP/JSON API exposes business operations from the MCP catalog without a JSON-RPC envelope. Available operations depend on the installed server version. It is an operation-oriented API, not a separate CRUD interface for each database table.

Access and permissions¶

Send an existing MCP API key as Authorization: Bearer <key>. MCP must be enabled globally and for the project. Project keys also require X-ZTM-Project-UniqueId. Global keys need explicit project access for project operations. Browser and Windows sign-in do not replace an API key.

User permissions, write gates, allowed capabilities and demo restrictions apply just as they do for MCP. Use HTTPS outside local tests. Never put keys in URLs, source code or logs. See Safe actions and MCP.

Discover operations¶

OpenAPI contains a concrete POST path for each available operation. Inputs use the same schemas as MCP. Project attachments and release comparisons/snapshots have typed output schemas. Other dynamic query/action results retain extensible JSON contracts. The catalog includes shared query and action tools; not every Web menu item has a dedicated endpoint.

$headers = @{
    Authorization = "Bearer $env:ZTM_API_KEY"
    'X-ZTM-Project-UniqueId' = $env:ZTM_PROJECT_UNIQUE_ID
}
$baseUrl = 'https://your-server.example'
Invoke-RestMethod "$baseUrl/api/v1/operations" -Headers $headers
Invoke-RestMethod "$baseUrl/api/v1/operations/ztm_usage_guide" `
    -Method Post -Headers $headers -ContentType 'application/json' -Body '{}'

These environment variables are read by the calling PowerShell script; they do not automatically configure the server. Route projects using headers, not operation arguments. JSON bodies are limited to 1 MiB and 32 nesting levels. Duplicate property names are rejected.

Writes and exports¶

Follow each operation's preview and explicit commit contract, for example ztm_project_action_prepare and ztm_project_action_commit. API access does not replace business approval. Keep previews, idempotency keys and commits bound to the same user and project context. After a timeout, check the action's status rather than blindly repeating a write.

Exports may return a resourceUri. Read it through POST /api/v1/resources/read with {"uri":"<resourceUri>"} using the same key and project. The response contains contents with text or Base64 data and a MIME type. Tickets may expire or allow a single read; treat resource URIs as confidential.

Errors¶

Errors return HTTP status and application/problem+json containing code and traceId: 400 invalid input, 401 missing/rejected authentication, 403 insufficient permissions, 404 unavailable object or operation, 409 action conflict, 413 oversized body, 415 unsupported content type, 500 internal failure. Conflicts require review, not automatic retries. Give support the traceId, never keys or confidential payloads.

Prerequisite rules and blocked tests¶

ztm_project_query includes rule for library and planned dependencies: 0 = Hint only, 1 = Must succeed, 2 = Must not have failed.

To change an existing library dependency, use ztm_project_action_context, then ztm_project_action_prepare with capabilityId: project.test-case.dependency.set-rule and arguments testCaseId, dependencyId, rule. Review the preview and confirm it with ztm_project_action_commit. The key requires this explicit write capability. Creation stays compatible: a new relationship starts as a hint; its rule can then be changed. Existing plans and runs are not synchronized automatically.

POST /api/v1/operations/ztm_test_prerequisites_read with {"plannedVariantId":123} evaluates a visible planned test. The response includes isBlocked, needsRecheck and blockers. Invisible or missing predecessors are not disclosed by name; hasHiddenPrerequisites indicates them. This point-in-time assessment does not grant execution rights or replace personal retest confirmation. The same operation is available through MCP.

Project attachments¶

ztm_project_attachments_read lists project attachments and their ownerId, with offset and limit (maximum 100). Supply attachmentId to download contentBase64 (maximum 32 MiB). An active project administrator or project manager is required. Dynamically linked files are listed but cannot be downloaded through this operation.

Writes require the separate project.attachment.upload, project.attachment.update or project.attachment.delete capability. Existing planning-attachment grants do not grant project-file access. Use the returned ownerId, which can be 0 for a project.

1. Upload: call ztm_project_attachment_stage with targetKind: "project", targetId: <ownerId>, fileName, mimeType and contentBase64. The existing staging limit is 512 KiB per file.
2. Call ztm_project_action_prepare with the capability, a new idempotencyKey and arguments. Upload arguments: ownerKind: "project", ownerId, the ticket's attachmentReferenceId, optional displayName and remarks. Metadata update: ownerKind, ownerId, attachmentId, displayName, remarks. Delete: ownerKind, ownerId, attachmentId.
3. Review the preview and confirm through ztm_project_action_commit with the same key. Concurrent edits cause a conflict; replaying a successful commit does not create another attachment.

Release comparisons and decisions¶

ztm_release_snapshots_list lists readable saved comparisons with an optional targetId filter. Pass the returned NextCursor as cursor to read the next page.

ztm_release_compare accepts baseId, targetId, explicit baseRunIds/targetRunIds and optional baseScopeRunIds/targetScopeRunIds arrays of { "runId": 123, "scopeRunId": 123 }. Optional baseSnapshotId/targetSnapshotId select saved evidence. It returns the Web comparison including Fingerprint, applying the same selection and object-permission rules.

To save evidence, explicitly grant project.release-review.snapshot-create and prepare/commit arguments query (the comparison argument object), name and fingerprint. Evidence changes are rejected. Read the saved comparison, decisionRevision and decision history with ztm_release_snapshot_read and snapshotId; historyBeforeRevision pages older decisions.

A decision also requires project.release-review.decision-record, project-management permission and explicit human authorization. Prepare accepts snapshotId, targetId, revision, outcome (1 accepted, 2 accepted with conditions, 3 rejected, 4 revoked), responsibleUserId, comment, openPoints (one per line) and humanConfirmed: true. The server records the authenticated actor; the flag does not replace actual human approval. Review the preview, then commit. Web rules still apply: current revision, eligible responsible user, explanation, complete scope and unchanged evidence. Historical project copies cannot receive a new decision.

Coverage and limits¶

REST and MCP share their operation catalog. This does not imply complete coverage of every Web feature. Project attachments now have a separate write contract; existing test-case, requirement and planning upload contracts remain separate. Deferred operations remain visible in the capability catalog.

Browser presentation, file-picker dialogs and interactive login do not need separate domain endpoints. Personal confirmation of an actual manual retest is not generated automatically on a tester's behalf. Release overview/PDF and automation imports use their existing operations; the REST transport does not expand their domain coverage. Project attachment writes and release comparison/decision operations are now available as described above. Arbitrary server paths and Local Bridge file links remain outside these API operations. Standalone variant copying and manifest file imports are not separate actions in the reviewed Web implementation. Typed outputs cover project attachments and release comparisons/snapshots; existing dynamic query/action outputs remain extensible JSON, not fully typed SDK models.

Test case versions¶

Test case versioning is available through POST /api/v1/operations/ztm_project_test_case_versions. Use operation: "list", testCaseID and optional skip and take for a bounded list with the current head. read also requires revisionID, while compare adds otherRevisionID; asset uses revisionID and assetID and returns base64-encoded bytes. restore-preview checks revisionID against expectedHead.

Prepare restoration through ztm_project_action_prepare, capability project.test-case-version.restore, and arguments testCaseID, revisionID, expectedHead, optional note and options. Confirm the returned token through ztm_project_action_commit. options may contain explicitly excluded excludedAttributeIDs and flattenUnavailableReusableSteps. Project binding, active user identity, object permissions, write scopes and demo protection still apply. Never put API keys into examples, logs or shell history.