Ingest API v2 reference

GET /healthz

Liveness probe - Liveness probe. No authentication. Same response shape as /api/ingest/health, and any server implementing this contract should serve both. Prefer /api/ingest/health when probing through an edge or proxy that forwards only certain path prefixes: on m00nreport.com this path is answered by the web app rather than by this API, so it returns 200 with HTML. Validate the body for ok: true rather than trusting the status, and treat the result as advisory - this contract never requires a probe before reporting.

{
  "ok": true,
  "service": "ingest"
}

Responses: 200 (Service is alive)

GET /api/ingest/health

Liveness probe (cloud-routable) - Liveness probe. No authentication. Same semantics as /healthz, but routable through an edge or proxy that forwards only certain path prefixes, such as /api/* - including m00nreport.com, where /healthz is not one of them. Probe this path first. Validate the body for ok: true rather than trusting the status, and treat the result as advisory - this contract never requires a probe before reporting.

{
  "ok": true,
  "service": "ingest"
}

Responses: 200 (Service is alive)

POST /api/ingest/v2/run/start

Start a run - Creates a run. The project is derived from the API key. Returns the server-generated runId used by all subsequent calls.

{
  "launch": "Nightly regression",
  "tags": [
    "smoke"
  ],
  "total": 42,
  "startedAt": "2026-07-17T21:00:00.000Z"
}

Responses: 200 (Success), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 500 (Unexpected server error)

POST /api/ingest/v2/test/start

Register a test attempt (fire-and-forget) - Registers a client-generated testId so steps can stream before the test finishes. Safe to send without awaiting the response. Linking a test to a test case, highest precedence first: 1. `caseId` / `caseIds` in the body - internal case ids, used as sent. 2. `annotations.caseId` / `annotations.caseIds` - the same internal ids, for runners whose annotation API is the only place a test can carry metadata. 3. A `[TC-N]` marker anywhere in titlePath - N is the per-project case NUMBER the UI shows, not the internal id, and is resolved against the run's project server-side. A number that matches nothing links nothing and is not an error. All three are merged, so a test can cover several cases; precedence only decides which one is primary. Links recorded in the app for this project are merged in as well, and become primary when the body carries none of the three. A `[tag: NAME]` marker anywhere in titlePath adds NAME to the test's tags, alongside anything sent in `tags`.

{
  "runId": "3f0f1e6a-7b1c-4b6e-9a52-1c2d3e4f5a6b",
  "testId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "titlePath": [
    "auth.spec.ts",
    "Login",
    "valid credentials"
  ],
  "filePath": "tests/auth.spec.ts",
  "retry": 0,
  "startedAt": "2026-07-17T21:00:01.000Z",
  "tags": [
    "smoke"
  ],
  "caseIds": [
    42
  ]
}

Responses: 200 (Success), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 409 (Run is no longer active (stopped or interrupted)), 500 (Unexpected server error)

POST /api/ingest/v2/test/complete

Complete a test attempt - Final status, error, timings, any steps not already streamed, and any attachments sent inline. Linking a test to a test case, highest precedence first: 1. `caseId` / `caseIds` in the body - internal case ids, used as sent. 2. `annotations.caseId` / `annotations.caseIds` - the same internal ids, for runners whose annotation API is the only place a test can carry metadata. 3. A `[TC-N]` marker anywhere in titlePath - N is the per-project case NUMBER the UI shows, not the internal id, and is resolved against the run's project server-side. A number that matches nothing links nothing and is not an error. All three are merged, so a test can cover several cases; precedence only decides which one is primary. Links recorded in the app for this project are merged in as well, and become primary when the body carries none of the three. A `[tag: NAME]` marker anywhere in titlePath adds NAME to the test's tags, alongside anything sent in `tags`.

{
  "runId": "3f0f1e6a-7b1c-4b6e-9a52-1c2d3e4f5a6b",
  "testId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "titlePath": [
    "auth.spec.ts",
    "Login",
    "valid credentials"
  ],
  "status": "passed",
  "retry": 0,
  "duration": 4210,
  "startedAt": "2026-07-17T21:00:01.000Z",
  "endedAt": "2026-07-17T21:00:05.210Z",
  "steps": [],
  "attachments": []
}

Responses: 200 (Success), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 409 (Run is no longer active (stopped or interrupted)), 500 (Unexpected server error)

POST /api/ingest/v2/steps/stream

Stream live step events (batched) - Batch of step events, possibly spanning multiple tests and runs. Every unique runId in the batch is ownership-checked.

{
  "items": [
    {
      "runId": "3f0f1e6a-7b1c-4b6e-9a52-1c2d3e4f5a6b",
      "testId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "title": "page.click(#login)",
      "action": "end",
      "status": "passed",
      "duration": 120,
      "nestingLevel": 0,
      "stepIndex": 3
    }
  ]
}

Responses: 200 (Success), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 409 (Run is no longer active (stopped or interrupted)), 500 (Unexpected server error)

POST /api/ingest/v2/run/end

End a run

{
  "runId": "3f0f1e6a-7b1c-4b6e-9a52-1c2d3e4f5a6b",
  "status": "finished",
  "endedAt": "2026-07-17T21:05:00.000Z"
}

Responses: 200 (Success), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 500 (Unexpected server error)

POST /api/ingest/v2/attachment/upload

Upload attachments (buffered multipart) - For small files. Multipart form with runId, testId fields and up to 10 file parts.

Responses: 200 (Success), 400 (runId and testId are required, or no files provided), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 409 (Run is no longer active (stopped or interrupted)), 413 (Per-run attachment byte quota exceeded), 500 (Unexpected server error)

POST /api/ingest/v2/attachment/stream

Upload large attachments (streaming multipart) - For large files (videos, traces). Streams to storage without buffering. Send runId and testId fields BEFORE file parts.

Responses: 200 (Success), 400 (runId and testId are required, or no files uploaded), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 409 (Run is no longer active (stopped or interrupted)), 413 (Per-run attachment byte quota exceeded), 500 (Unexpected server error)

POST /api/ingest/v2/attachment/presign

Get a presigned direct-upload URL - Returns a PUT URL that uploads straight to storage, so the bytes never pass through this service. Use it for files at or above the directUploadMinBytes reported by run/start; below that, attachment/upload is one request instead of three. The URL binds the exact Content-Length, Content-Type and filename you declare here. Send precisely those values on the PUT: any other length, or a chunked request with no Content-Length, is refused by storage and nothing is stored. Then call attachment/confirm. Nothing is recorded until you do, and the quota is charged there, against the size storage actually reports.

{
  "runId": "3f0f1e6a-7b1c-4b6e-9a52-1c2d3e4f5a6b",
  "testId": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "filename": "trace.zip",
  "contentType": "application/zip",
  "size": 1048576
}

Responses: 200 (Success), 400 (Missing a required field, a size that is not a positive integer, or a file above the 200MB per-file limit (code ATTACHMENT_TOO_LARGE)), 401 (Missing or invalid API key), 403 (Run belongs to another organization (code RUN_ACCESS_DENIED), or the subscription is paused or canceled and every write is blocked (code SUBSCRIPTION_INACTIVE, sent for any authenticated endpoint)), 409 (Run is no longer active (stopped or interrupted)), 500 (Unexpected server error), 501 (This deployment cannot issue presigned URLs; storage is not reachable from outside the server network. Use attachment/stream.), 503 (Could not record the upload authorization; retry or use attachment/stream)

POST /api/ingest/v2/attachment/confirm

Confirm a direct upload - Records the attachment after a successful presigned PUT, and charges the run quota against the size storage reports rather than the size declared at presign. Safe to retry: repeating a confirm that already succeeded returns 200 and changes nothing. If the response is lost, retry this call. Do NOT fall back to attachment/stream once the PUT succeeded, or the file is stored and charged twice. Does not require the run to still be active, because it finalises something presign authorised while the run was running.

{
  "runId": "3f0f1e6a-7b1c-4b6e-9a52-1c2d3e4f5a6b",
  "attachmentId": "7c8d9e0f-1a2b-4c3d-8e5f-6a7b8c9d0e1f",
  "filename": "trace.zip",
  "contentType": "application/zip"
}

Responses: 200 (Success), 400 (Missing one of runId, attachmentId, filename, or the run no longer exists (code RUN_NOT_FOUND). Neither is retryable.), 401 (Missing or invalid API key), 409 (The attachmentId was never issued for this run or has expired (code PRESIGN_BINDING_UNKNOWN), or no object was uploaded against it (code UPLOAD_NOT_FOUND). Neither is retryable; upload again via attachment/stream.), 413 (Per-run attachment byte quota exceeded. The object has already been deleted; do not retry and do not fall back.), 500 (Unexpected server error), 503 (Storage could not be reached to verify the upload. The object is intact; retry this call.)

ErrorEnvelope

RunQuota

Per-run attachment byte quota, by pricing tier.

AttachmentResult

One stored attachment, as returned by attachment/upload and attachment/stream.

StepItem

One step event. Items without runId, testId and title are silently skipped by the server.

EmbeddedStep

One step embedded in test/complete's steps array (distinct from steps/stream's StepItem: no runId/testId per item, since the parent call already carries both for the whole array). No field is required - the server accepts partial items and falls back to array position for ordering when index/stepIndex is omitted.

EmbeddedAttachment

One inline base64-encoded attachment embedded in test/complete's attachments array (distinct from AttachmentResult, the shape the upload endpoints return). This is the fallback route for a file: base64 costs 33% in size and the whole file travels in the test/complete body, so prefer attachment/upload, attachment/stream or presign+confirm and leave this array empty. Items without data or name are silently skipped by the server.