{ "info": { "_postman_id": "lathe-studio-api-v1", "name": "Lathe Studio API", "description": "# Lathe Studio API\n\nGenerated from `openapi.json` (API version 1.2.0). Do not edit by hand.\n\nREST API for integrating CI/CD pipelines, automation frameworks, and external tools with Lathe Studio.\n\nAll endpoints are versioned under `/api/v1`. Authentication uses API keys in Bearer token format.\n\n**Availability:** the API is included in Lathe Studio's single plan, and in the 90-day preview.\n\n**Errors** always use `{ \"error\": { \"code\", \"message\", \"details\"? } }`. Branch on `error.code`, then on `error.details.reason` where present; the code for a given failure never changes.\n\n## Setup\nSet the `apiKey` collection variable to a key from **Settings → API Keys**. Requests send it as `Authorization: Bearer {{apiKey}}`.\nSet `baseUrl` to your environment; the id variables (`projectId`, `runId`, …) to ids from your organization.\n\n## Errors every request can return\n- **401** `AUTH_REQUIRED`: missing or invalid API key.\n- **403** `FORBIDDEN`: the key lacks the scope or is scoped to another project, or the organization is locked.\n- **429** `RATE_LIMITED`: per-minute limit or monthly quota; `details.reset_at` and `X-RateLimit-Reset` are Unix seconds.\n- **500** `INTERNAL_ERROR`: retry with backoff.\n\n## Scopes\n- `builds:create`\n- `builds:read`\n- `builds:update`\n- `projects:read`\n- `releases:create`\n- `releases:read`\n- `results:read`\n- `results:submit`\n- `testcases:create`\n- `testcases:delete`\n- `testcases:update`\n- `testruns:assign`\n- `testruns:create`\n- `testruns:read`\n- `testsets:create`\n- `testsets:delete`\n- `testsets:read`\n- `testsets:update`\n- `webhooks:manage`", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "version": "1.2.0" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{apiKey}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://lathe.studio/api/v1", "type": "string" }, { "key": "apiKey", "value": "", "type": "string" }, { "key": "projectId", "value": "", "type": "string" }, { "key": "buildId", "value": "", "type": "string" }, { "key": "runId", "value": "", "type": "string" }, { "key": "releaseId", "value": "", "type": "string" }, { "key": "testCaseId", "value": "", "type": "string" }, { "key": "testSetId", "value": "", "type": "string" }, { "key": "webhookId", "value": "", "type": "string" } ], "item": [ { "name": "Builds", "description": "Create and query builds. Use the builds API to register new deployments from your CI/CD pipeline and associate them with releases.", "item": [ { "name": "List builds", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ], "query": [ { "key": "project_id", "value": "", "disabled": true, "description": "Filter builds by project ID." }, { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (alternative to `project_id`, and the only project selector for org-scoped keys without `project_id`). Resolved inside the key's organization. If both `project_id` and `project_key` are sent and disagree → 400." }, { "key": "release", "value": "", "disabled": true, "description": "Filter by release bucket: `none` returns only release-less builds; a release UUID returns that release's builds (the release must belong to the resolved project — else 404)." }, { "key": "limit", "value": "20", "disabled": true, "description": "Number of results per page (max 100)." }, { "key": "offset", "value": "0", "disabled": true, "description": "Number of results to skip." } ] }, "description": "Returns a paginated list of builds. Filter by project (`project_id` or `project_key` — both sent and disagreeing is a 400) or by release bucket: `release=none` for release-less builds, `release=` for one release (must belong to the resolved project, else 404)." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ], "query": [ { "key": "project_id", "value": "", "disabled": true, "description": "Filter builds by project ID." }, { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (alternative to `project_id`, and the only project selector for org-scoped keys without `project_id`). Resolved inside the key's organization. If both `project_id` and `project_key` are sent and disagree → 400." }, { "key": "release", "value": "", "disabled": true, "description": "Filter by release bucket: `none` returns only release-less builds; a release UUID returns that release's builds (the release must belong to the resolved project — else 404)." }, { "key": "limit", "value": "20", "disabled": true, "description": "Number of results per page (max 100)." }, { "key": "offset", "value": "0", "disabled": true, "description": "Number of results to skip." } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"0b9d8c7e-6f5a-4b3c-8d2e-1f0a9b8c7d6e\",\n \"name\": \"v2.4.1\",\n \"status\": \"queued\",\n \"release_id\": null,\n \"created_at\": \"2026-09-20T14:03:11Z\"\n }\n ],\n \"pagination\": {\n \"total\": 1,\n \"limit\": 20,\n \"offset\": 0,\n \"has_more\": false\n }\n}" }, { "name": "400 Bad Request", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ], "query": [ { "key": "project_id", "value": "", "disabled": true, "description": "Filter builds by project ID." }, { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (alternative to `project_id`, and the only project selector for org-scoped keys without `project_id`). Resolved inside the key's organization. If both `project_id` and `project_key` are sent and disagree → 400." }, { "key": "release", "value": "", "disabled": true, "description": "Filter by release bucket: `none` returns only release-less builds; a release UUID returns that release's builds (the release must belong to the resolved project — else 404)." }, { "key": "limit", "value": "20", "disabled": true, "description": "Number of results per page (max 100)." }, { "key": "offset", "value": "0", "disabled": true, "description": "Number of results to skip." } ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ], "query": [ { "key": "project_id", "value": "", "disabled": true, "description": "Filter builds by project ID." }, { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (alternative to `project_id`, and the only project selector for org-scoped keys without `project_id`). Resolved inside the key's organization. If both `project_id` and `project_key` are sent and disagree → 400." }, { "key": "release", "value": "", "disabled": true, "description": "Filter by release bucket: `none` returns only release-less builds; a release UUID returns that release's builds (the release must belong to the resolved project — else 404)." }, { "key": "limit", "value": "20", "disabled": true, "description": "Number of results per page (max 100)." }, { "key": "offset", "value": "0", "disabled": true, "description": "Number of results to skip." } ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Create a build", "request": { "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "", "disabled": true, "description": "Optional. 1-255 characters. Retry-safe create: identical retries replay the original response (200) instead of creating a duplicate build; a different body with the same key returns 409." }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ] }, "description": "Creates a new build and returns `201 Created`. `release_id` is optional — without it the build lands in the project's \"No release\" bucket; a release is never chosen for you. Duplicate names are never refused: if a build with the same name (case-insensitive) already exists in the same release bucket, the new build is created as \"name (2)\", \"name (3)\", … and the final name is returned. An optional `suffix` makes the stored name \" ()\".\n\n**Project resolution:** a project-scoped key uses its project. An org-scoped key MUST send `project_key` (project UUID or project_code) — there is no default project and `repo_url` no longer selects one (breaking change for org-scoped keys, 2026-09-24). `project_key` naming a different project than a project-scoped key → `403`.\n\nIdempotency: send an `Idempotency-Key` header to safely retry. An identical retry returns `200` with the original build (no second insert); the same key with a different body returns `409` (`details.reason: idempotency_key_reused`). Keys expire after 24 hours; a claim whose request died mid-flight is reclaimed after 5 minutes.\n\nTypically called from your CI/CD pipeline immediately after a successful deployment.", "body": { "mode": "raw", "raw": "{\n \"name\": \"v2.4.1\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"19cb07a9-3ab5-56c0-a54e-648725bdc6e4\",\n \"name\": \"v2.4.1\",\n \"status\": \"queued\",\n \"release_id\": \"6067f547-04a7-5e00-af03-ef78a57f4181\",\n \"source\": \"api\",\n \"message\": \"Build already created for this Idempotency-Key\"\n}" }, { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ] } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"19cb07a9-3ab5-56c0-a54e-648725bdc6e4\",\n \"name\": \"v2.4.1\",\n \"status\": \"active\",\n \"source\": \"api\",\n \"message\": \"Build created successfully.\",\n \"release_id\": \"6067f547-04a7-5e00-af03-ef78a57f4181\"\n}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "403 Forbidden", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ] } }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"FORBIDDEN\",\n \"message\": \"project_key does not match this API key's project\"\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" }, { "name": "409 Conflict", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/builds", "host": [ "{{baseUrl}}" ], "path": [ "builds" ] } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"CONFLICT\",\n \"message\": \"Idempotency-Key was already used with a different request body\",\n \"details\": {\n \"reason\": \"idempotency_key_reused\"\n }\n }\n}" } ] }, { "name": "Get a build", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] }, "description": "Returns a single build by ID. A project-scoped key only sees its own project's builds; anything else is a 404. This is where the `Location` header from `POST /builds` points." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"project_id\": \"00000000-0000-0000-0000-000000000000\",\n \"name\": \"v2.4.1\",\n \"status\": \"queued\",\n \"release_id\": \"00000000-0000-0000-0000-000000000000\"\n}" }, { "name": "400 Bad Request", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Place a build in a release", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] }, "description": "Moves a build into a release, or back to the project's \"No release\" bucket with `release_id: null`. The body is exactly `{ \"release_id\": \"\" }` — any other field is a 400, and no other build field is editable through the API.\n\nThe move runs through the same core as the UI's *Place in release*: the build's runs follow it in the database, a name collision in the target bucket suffixes the name (\"X (2)\") instead of refusing, and a **completed** release refuses the move in either direction (**409** `details.reason: release_completed`). A release from another project is a 404.\n\nReturns the build (`id`, `name`, `release_id`, `status`).", "body": { "mode": "raw", "raw": "{\n \"release_id\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "PATCH", "header": [], "url": { "raw": "{{baseUrl}}/builds/{{buildId}}", "host": [ "{{baseUrl}}" ], "path": [ "builds", "{{buildId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] } ] }, { "name": "Test Runs", "description": "Query test runs, submit automation results, and split runs into child runs.", "item": [ { "name": "List test runs", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns", "host": [ "{{baseUrl}}" ], "path": [ "testruns" ], "query": [ { "key": "project_id", "value": "", "disabled": true, "description": "Filter by project ID." }, { "key": "build_id", "value": "", "disabled": true, "description": "Filter by build ID." }, { "key": "status", "value": "planned", "disabled": true, "description": "Filter by run status." }, { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true }, { "key": "release_id", "value": "", "disabled": true, "description": "Only runs in this release." } ] }, "description": "Returns a paginated list of test runs for a project or build." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns", "host": [ "{{baseUrl}}" ], "path": [ "testruns" ], "query": [ { "key": "project_id", "value": "", "disabled": true, "description": "Filter by project ID." }, { "key": "build_id", "value": "", "disabled": true, "description": "Filter by build ID." }, { "key": "status", "value": "planned", "disabled": true, "description": "Filter by run status." }, { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true }, { "key": "release_id", "value": "", "disabled": true, "description": "Only runs in this release." } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns", "host": [ "{{baseUrl}}" ], "path": [ "testruns" ], "query": [ { "key": "project_id", "value": "", "disabled": true, "description": "Filter by project ID." }, { "key": "build_id", "value": "", "disabled": true, "description": "Filter by build ID." }, { "key": "status", "value": "planned", "disabled": true, "description": "Filter by run status." }, { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true }, { "key": "release_id", "value": "", "disabled": true, "description": "Only runs in this release." } ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" } ] }, { "name": "Create a test run", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/testruns", "host": [ "{{baseUrl}}" ], "path": [ "testruns" ] }, "description": "Create a new test run with selected test cases. The run is created in `planned` status and can be executed manually or via automation.\n\nWhen `build_id` is given, the run's release is its build's release: a run created on a build in a release belongs to that release, and a run on a release-less build has no release. Passing both `release_id` and `build_id` where the build's release differs returns **400** `VALIDATION_ERROR` with `details.reason: 'release_build_mismatch'` — an explicit release is never silently overridden.\n\n`assignee_id` and `queue: true` both require the **`testruns:assign`** scope in addition to `testruns:create` (touchless T3, 2026-09-24): assigning or queueing a run is a lead's decision in the UI, and the API mirrors that. An assignee together with `queue: true` is refused (400 `assignee_and_queue`). Keys created before 2026-09-24 do not have the scope — an admin enables it on the key. An assigned run now sends the assignment notifications (email, `testrun.assigned.v1`, `run.assigned` chat trigger) attributed to the API key; previously API-created assigned runs sent nothing.\n\n`assignee_email` (touchless T4, 2026-09-24) is accepted anywhere `assignee_id` is: the email is resolved case-insensitively to a user inside your organization and the run is assigned exactly as with `assignee_id` (same validation, notifications, and `testruns:assign` scope requirement). An email that does not match exactly one assignable org member returns **400** `BAD_REQUEST` (the same code this endpoint has always used for `assignee_id` errors, which now also carry `details.reason`) with `details.reason` one of `assignee_not_found`, `assignee_not_assignable` (member lacks effective `test_run:update` in the project), or `assignee_ambiguous` (the email matches more than one user — disambiguate with `assignee_id`). The response is identical whether the email belongs to a different organization or to no one — the API never confirms which. Sending both fields returns `details.reason: 'assignee_conflict'`. There is no endpoint that lists member emails.", "body": { "mode": "raw", "raw": "{\n \"name\": \"Sprint 14 Regression\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns", "host": [ "{{baseUrl}}" ], "path": [ "testruns" ] } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns", "host": [ "{{baseUrl}}" ], "path": [ "testruns" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns", "host": [ "{{baseUrl}}" ], "path": [ "testruns" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Get a test run", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}" ] }, "description": "Returns a single test run by ID." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"project_id\": \"00000000-0000-0000-0000-000000000000\",\n \"in_unassigned_queue\": false,\n \"name\": \"Regression - v2.4.1 Staging\",\n \"status\": \"planned\",\n \"created_at\": \"2026-10-01T12:00:00Z\"\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Assign, queue, or unassign a test run", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/assign", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "assign" ] }, "description": "Moves a run between the three assignment states. Exactly one target is required:\n- `{ \"assignee_id\": \"\" }` — assign or reassign to a person (must be assignable in the project).\n- `{ \"assignee_email\": \"\" }` — the same, by email: resolved case-insensitively inside your organization (touchless T4). An email that does not match exactly one assignable org member returns **400** `VALIDATION_ERROR` (`details.reason`: `assignee_not_found`, `assignee_not_assignable`, or `assignee_ambiguous`) — the identical response whether the email belongs to another org or to no one. Sending both assignee fields returns `details.reason: 'assignee_conflict'`.\n- `{ \"queue\": true }` — release the run into the unassigned queue for testers to grab.\n- `{ \"unassigned\": true }` — pull the run back to plain unassigned.\n\nSends the same notifications as assigning in the UI: the `testrun.assigned.v1` webhook, an email to the assignee, and the `run.assigned` Slack/Teams trigger — attributed to the API key by name (the audit row records the key, not a user). Repeating the run's current target returns **200** with `changed: false` and no side effects. An API key cannot grab a run for itself; self-claim remains a browser-only action.\n\n**Completed releases freeze assignment:** if the run's release is `completed`, every target is refused with **409** `details.reason: 'release_completed'` — a completed release freezes the run's assignment.\n\n**Behaviour change (2026-09-24):** creating a run with `assignee_id` (POST /testruns) and splitting a run with an assignee now send the same notifications.\n\nOther `details.reason` values on **400** `VALIDATION_ERROR`: `invalid_target` (no target, or more than one), `assignee_and_queue` (an assignee together with `queue`), `invalid_assignee_email` (malformed email).", "body": { "mode": "raw", "raw": "{\n \"assignee_id\": \"00000000-0000-0000-0000-000000000000\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/assign", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "assign" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/assign", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "assign" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/assign", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "assign" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" }, { "name": "409 Conflict", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/assign", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "assign" ] } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"CONFLICT\",\n \"message\": \"This run belongs to a completed release, so its assignment can't be changed\",\n \"details\": {\n \"reason\": \"release_completed\"\n }\n }\n}" } ] }, { "name": "Split a test run", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/split", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "split" ] }, "description": "Moves unexecuted cases from a run into one or more child runs. Executed cases stay locked in the original run, whose status becomes `superseded` when emptied.\n\n- `by_section`: one child run per section.\n- `by_set`: one child run per source regression set.\n- `manual`: moves the executions listed in `execution_ids` into a single child run (`execution_ids` is required for this strategy).\n\n`assignee_id` (or `assignee_email`, resolved case-insensitively inside your organization — touchless T4) is optional; when provided, the moved executions are assigned to that user (who must be assignable in the project). Supplying `assignee_id` also requires the `testruns:assign` scope (403 without it), and sends the same assignment notifications as `POST /testruns/{id}/assign`.\n\nA project-scoped key used on another project's run gets **403** `FORBIDDEN` here (assign returns 404 for the same case). Assignee failures return **400** `VALIDATION_ERROR` with the same `details.reason` values as assign.", "body": { "mode": "raw", "raw": "{\n \"strategy\": \"by_section\",\n \"name\": \"string\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/split", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "split" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/split", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "split" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/split", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "split" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Get test run results", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results" ], "query": [ { "key": "limit", "value": "100", "disabled": true }, { "key": "offset", "value": "0", "disabled": true }, { "key": "result", "value": "pass", "disabled": true, "description": "Only executions with this result. An unknown value returns an empty list." } ] }, "description": "Returns all execution results for a test run, including pass/fail status, notes, and defect references." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results" ], "query": [ { "key": "limit", "value": "100", "disabled": true }, { "key": "offset", "value": "0", "disabled": true }, { "key": "result", "value": "pass", "disabled": true, "description": "Only executions with this result. An unknown value returns an empty list." } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"result\": \"pass\",\n \"requires_retest\": false\n }\n ],\n \"pagination\": {}\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results" ], "query": [ { "key": "limit", "value": "100", "disabled": true }, { "key": "offset", "value": "0", "disabled": true }, { "key": "result", "value": "pass", "disabled": true, "description": "Only executions with this result. An unknown value returns an empty list." } ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Submit automation results", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results" ] }, "description": "Submit execution results from an automation framework (Playwright, Cypress, pytest …). One execution row is added per item. A `test_case_id` that isn't a live case in the run's project is skipped and counted in `skipped`, not rejected. This endpoint does not honour `Idempotency-Key`.", "body": { "mode": "raw", "raw": "{\n \"results\": [\n {\n \"test_case_id\": \"c3864dd3-7451-5692-8d98-97b586148f84\",\n \"result\": \"pass\",\n \"duration_seconds\": 1\n },\n {\n \"test_case_id\": \"bda1d531-3d0d-557a-8d3c-77088e4e9122\",\n \"result\": \"fail\",\n \"duration_seconds\": 3,\n \"comments\": \"AssertionError: expected 200 but got 500\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"accepted\": 42,\n \"skipped\": 1,\n \"message\": \"Results submitted successfully. 42 accepted, 1 skipped.\"\n}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Get exploratory session notes", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results/{{executionId}}/notes", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results", "{{executionId}}", "notes" ], "query": [ { "key": "limit", "value": "100", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] }, "description": "Returns the note log of one execution of an exploratory test case (the 'session'), oldest first. Read-only; notes are added from the run page." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results/{{executionId}}/notes", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results", "{{executionId}}", "notes" ], "query": [ { "key": "limit", "value": "100", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {}\n ],\n \"pagination\": {}\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/testruns/{{runId}}/results/{{executionId}}/notes", "host": [ "{{baseUrl}}" ], "path": [ "testruns", "{{runId}}", "results", "{{executionId}}", "notes" ], "query": [ { "key": "limit", "value": "100", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Ingest automated test results", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/results/ingest", "host": [ "{{baseUrl}}" ], "path": [ "results", "ingest" ] }, "description": "Accepts JSON test results from any CI/CD pipeline. Refers to a Build by name (results attach to the NEWEST non-deleted build of that name in the project, case-insensitive) and creates one in \"No release\" only when none exists — a release is never guessed. Creates a completed Test Run, links results to existing Test Cases (by display code or external_id), or auto-creates new Test Cases for unknown identifiers. Pass `build.release_id` to target a bucket, `build.suffix` for \"name (suffix)\".\n\n**409** `CONFLICT` (`details.reason: release_completed`) when the build's release is completed. Validation failures are **400** `BAD_REQUEST` with `details.field`.", "body": { "mode": "raw", "raw": "{\n \"build\": {\n \"identifier\": \"string\"\n },\n \"results\": [\n {\n \"test_identifier\": \"string\",\n \"status\": \"passed\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/results/ingest", "host": [ "{{baseUrl}}" ], "path": [ "results", "ingest" ] } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"build_id\": \"00000000-0000-0000-0000-000000000000\",\n \"build_display_id\": \"string\",\n \"test_run_id\": \"00000000-0000-0000-0000-000000000000\",\n \"test_run_display_id\": \"RUN-MOB-0042\",\n \"test_run_url\": \"string\",\n \"test_cases_created\": 0,\n \"test_cases_linked\": 0,\n \"results_imported\": 0,\n \"results_unmatched\": [\n \"string\"\n ]\n}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/results/ingest", "host": [ "{{baseUrl}}" ], "path": [ "results", "ingest" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/results/ingest", "host": [ "{{baseUrl}}" ], "path": [ "results", "ingest" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" }, { "name": "409 Conflict", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/results/ingest", "host": [ "{{baseUrl}}" ], "path": [ "results", "ingest" ] } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"CONFLICT\",\n \"message\": \"This run belongs to a completed release, so its assignment can't be changed\",\n \"details\": {\n \"reason\": \"release_completed\"\n }\n }\n}" } ] } ] }, { "name": "Projects", "description": "List projects and their test cases.", "item": [ { "name": "List projects", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects", "host": [ "{{baseUrl}}" ], "path": [ "projects" ], "query": [ { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] }, "description": "Returns all projects the API key has access to." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects", "host": [ "{{baseUrl}}" ], "path": [ "projects" ], "query": [ { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" } ] }, { "name": "List test cases", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases" ], "query": [ { "key": "status", "value": "draft", "disabled": true, "description": "Filter by test case status." }, { "key": "section_id", "value": "", "disabled": true, "description": "Filter by section ID." }, { "key": "limit", "value": "50", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] }, "description": "Returns test cases for a project. Useful for syncing test case IDs with your automation framework." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases" ], "query": [ { "key": "status", "value": "draft", "disabled": true, "description": "Filter by test case status." }, { "key": "section_id", "value": "", "disabled": true, "description": "Filter by section ID." }, { "key": "limit", "value": "50", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases" ], "query": [ { "key": "status", "value": "draft", "disabled": true, "description": "Filter by test case status." }, { "key": "section_id", "value": "", "disabled": true, "description": "Filter by section ID." }, { "key": "limit", "value": "50", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] } ] }, { "name": "Test Cases", "description": "Create, update, and delete test cases in the test library.", "item": [ { "name": "Create a test case", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases" ] }, "description": "Creates a new test case in the project and section given in the URL path. Steps may mix plain manual steps with tool steps (`step_type` + `tool_config`).\n\nThe case-level `preconditions` field is **deprecated**: when non-empty it is converted into a leading `step_type: 'precondition'` step and never stored in a column. Send a precondition step directly instead. Accepts an optional `case_type` — the vendor-style case Type (functional, regression, smoke, acceptance, …); omitted or null means not set. Unknown values are rejected with a 400 VALIDATION_ERROR.", "body": { "mode": "raw", "raw": "{\n \"section_id\": \"00000000-0000-0000-0000-000000000000\",\n \"title\": \"string\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases" ] } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Get a test case", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] }, "description": "Returns one test case with its `custom_fields` serialized to the P6 wire format (see GET /projects/{id}/custom-fields for the schema). Values whose definition has been archived are omitted." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"title\": \"User can log in with valid credentials\",\n \"status\": \"draft\",\n \"priority\": \"p0\",\n \"is_adhoc\": false,\n \"custom_fields\": {\n \"severity\": \"High\",\n \"automatable\": true,\n \"reviewed\": \"2026-09-20\"\n },\n \"test_case_type\": \"standard\"\n}" }, { "name": "400 Bad Request", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Update a test case", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] }, "description": "Partial update of a test case. All fields are optional; unknown fields are rejected. At least one field must be provided.\n\nWhen `preconditions` is provided without `steps`, the deprecated conversion applies against the case's stored steps. Pass `case_type` to set the vendor-style case Type, or `null` to clear it back to not set.", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "PUT", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "PUT", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "PUT", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Delete a test case", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] }, "description": "Soft-deletes a test case. Idempotent — returns 204 even if the case was already deleted." }, "response": [ { "name": "204 No Content", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "No Content", "code": 204, "header": [], "body": "" }, { "name": "400 Bad Request", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/testcases/{{testCaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "testcases", "{{testCaseId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "List project custom fields", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/custom-fields", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "custom-fields" ] }, "description": "Returns the project's ACTIVE custom field definitions in display (`position`) order: `key`, `label`, `field_type`, `options` (option labels, in order — null for non-select types), `position`. Archived definitions are omitted. There is no API to create, edit or archive definitions in v1 — managing fields is a human task in Project Settings." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/custom-fields", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "custom-fields" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/custom-fields", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "custom-fields" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] } ] }, { "name": "Regression Sets", "description": "Manage Regression Sets — reusable collections of test cases and section subscriptions (paths, scopes, and field names use `test_sets` / `test-sets` / `testsets:*`).", "item": [ { "name": "List Regression Sets", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets" ], "query": [ { "key": "limit", "value": "50", "disabled": true, "description": "Number of results per page (max 200)." }, { "key": "offset", "value": "0", "disabled": true, "description": "Number of results to skip." } ] }, "description": "Returns the project's Regression Sets (reusable collections of test cases and section subscriptions) with their current item counts." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets" ], "query": [ { "key": "limit", "value": "50", "disabled": true, "description": "Number of results per page (max 200)." }, { "key": "offset", "value": "0", "disabled": true, "description": "Number of results to skip." } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets" ], "query": [ { "key": "limit", "value": "50", "disabled": true, "description": "Number of results per page (max 200)." }, { "key": "offset", "value": "0", "disabled": true, "description": "Number of results to skip." } ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Create a Regression Set", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets" ] }, "description": "Creates a Regression Set from case items and/or section items. `case` items are static snapshots; `section` items become dynamic subscriptions — test cases added to a subscribed section join in-flight runs automatically.\n\nRequires the `testsets:create` scope.", "body": { "mode": "raw", "raw": "{\n \"name\": \"string\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets" ] } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Get a Regression Set", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] }, "description": "Returns a single Regression Set with its items (cases and section subscriptions), ordered by position." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Update a Regression Set", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] }, "description": "Updates a Regression Set's name and/or description. When `items` is provided it fully replaces the set's items.\n\nRequires the `testsets:update` scope.", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "PUT", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "404 Not Found", "originalRequest": { "method": "PUT", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Delete a Regression Set", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] }, "description": "Soft-deletes a Regression Set. A set that doesn't exist, or was already deleted, returns **404**.\n\nRequires the `testsets:delete` scope." }, "response": [ { "name": "204 No Content", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] } }, "status": "No Content", "code": 204, "header": [], "body": "" }, { "name": "404 Not Found", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Preview a resolved Regression Set", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}/preview", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}", "preview" ] }, "description": "Returns the set resolved against the current test case library: the total current case count plus up to 5 sample cases. Section items are expanded at request time, so the result reflects the library as it is now — not when the set was created." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}/preview", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}", "preview" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/projects/{{projectId}}/test-sets/{{testSetId}}/preview", "host": [ "{{baseUrl}}" ], "path": [ "projects", "{{projectId}}", "test-sets", "{{testSetId}}", "preview" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] } ] }, { "name": "Releases", "description": "Create, list and read releases, and query release readiness.", "item": [ { "name": "Get release readiness", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases/{{releaseId}}/progress", "host": [ "{{baseUrl}}" ], "path": [ "releases", "{{releaseId}}", "progress" ] }, "description": "Readiness for a release: counts of verified, pending, blocked and new test cases across its builds. Requires the `testruns:read` scope." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases/{{releaseId}}/progress", "host": [ "{{baseUrl}}" ], "path": [ "releases", "{{releaseId}}", "progress" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"release\": {\n \"id\": \"2f6c1a7e-4b1d-4c55-9a3e-0f6b7c8d9e10\",\n \"name\": \"v2.4\",\n \"status\": \"active\",\n \"target_date\": \"2026-10-15\",\n \"project_id\": \"8a1f3c2e-5d4b-4e6a-9b7c-1d2e3f4a5b6c\"\n },\n \"builds\": [\n {\n \"id\": \"0b9d8c7e-6f5a-4b3c-8d2e-1f0a9b8c7d6e\",\n \"name\": \"v2.4.0-rc1\",\n \"status\": \"active\"\n }\n ],\n \"progress\": {\n \"total\": 250,\n \"verified\": 209,\n \"blocked\": 12,\n \"pending\": 20,\n \"new\": 9,\n \"pass_rate_percent\": 84\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases/{{releaseId}}/progress", "host": [ "{{baseUrl}}" ], "path": [ "releases", "{{releaseId}}", "progress" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "List releases", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ], "query": [ { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (required for org-scoped keys)." }, { "key": "status", "value": "planned", "disabled": true, "description": "Filter by release status." }, { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] }, "description": "Returns a paginated list of a project's releases, newest first.\n\n**Project resolution (D7):** a project-scoped key lists its own project. An org-scoped key MUST send `project_key` (project UUID or project_code) — there is no default project (400 without one).\n\nOptional `status` filter: `planned`/`active`/`completed`." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ], "query": [ { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (required for org-scoped keys)." }, { "key": "status", "value": "planned", "disabled": true, "description": "Filter by release status." }, { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ], "query": [ { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (required for org-scoped keys)." }, { "key": "status", "value": "planned", "disabled": true, "description": "Filter by release status." }, { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ], "query": [ { "key": "project_key", "value": "", "disabled": true, "description": "Project UUID or project_code (required for org-scoped keys)." }, { "key": "status", "value": "planned", "disabled": true, "description": "Filter by release status." }, { "key": "limit", "value": "20", "disabled": true }, { "key": "offset", "value": "0", "disabled": true } ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Create a release", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ] }, "description": "Creates a new release and returns `201 Created` with a `Location` header.\n\n**Project resolution (D7):** a project-scoped key creates in its own project; an org-scoped key MUST send `project_key`.\n\n**Status:** `planned` (default) or `active`. `completed` is refused — creating an already-completed release is completing one, and completing is human-only (400 `details.reason: release_status_not_allowed`).\n\n**Names:** duplicate names (case-insensitive) are refused with **409** `details.reason: release_name_taken`. Unlike builds, releases are never auto-suffixed.\n\n**Idempotency:** an `Idempotency-Key` header retries safely — an identical retry returns `200` with the original release (no second insert); the same key with a different body returns `409`.\n\n**Dates:** `target_date` must be today or later.", "body": { "mode": "raw", "raw": "{\n \"name\": \"string\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ] } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" }, { "name": "409 Conflict", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/releases", "host": [ "{{baseUrl}}" ], "path": [ "releases" ] } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"CONFLICT\",\n \"message\": \"This run belongs to a completed release, so its assignment can't be changed\",\n \"details\": {\n \"reason\": \"release_completed\"\n }\n }\n}" } ] }, { "name": "Get a release", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases/{{releaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "releases", "{{releaseId}}" ] }, "description": "Returns a release with its `build_count` (non-deleted builds currently in the release). A project-scoped key only sees its own project's releases; anything else is a 404. There is no endpoint that updates a release's status or deletes it — completing and deleting are human-only." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases/{{releaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "releases", "{{releaseId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases/{{releaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "releases", "{{releaseId}}" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/releases/{{releaseId}}", "host": [ "{{baseUrl}}" ], "path": [ "releases", "{{releaseId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] } ] }, { "name": "Discovery", "description": "Discover supported webhook events and API metadata.", "item": [ { "name": "List webhook event types", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/events", "host": [ "{{baseUrl}}" ], "path": [ "events" ] }, "description": "Lists the webhook event types and a human-readable description of each payload. No authentication; this endpoint cannot fail.", "auth": { "type": "noauth" } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/events", "host": [ "{{baseUrl}}" ], "path": [ "events" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"events\": [\n {\n \"name\": \"testrun.submitted.v1\",\n \"description\": \"Fired when a tester submits a test run.\",\n \"payload\": {\n \"run_id\": \"string (UUID)\",\n \"submitted_by\": \"string (Clerk user ID)\"\n }\n }\n ],\n \"docs_url\": \"/docs/api/webhooks\",\n \"openapi_url\": \"/openapi.json\"\n}" } ] }, { "name": "Get current API key metadata", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/whoami", "host": [ "{{baseUrl}}" ], "path": [ "whoami" ] }, "description": "Returns metadata for the API key used to authenticate the request. Any valid API key can call this endpoint." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/whoami", "host": [ "{{baseUrl}}" ], "path": [ "whoami" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" } ] }, { "name": "Get your organization", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/organizations", "host": [ "{{baseUrl}}" ], "path": [ "organizations" ] }, "description": "Returns the organization that owns the API key: plan, preview days left, lock state, billing and usage. A project-scoped key returns its parent organization." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/organizations", "host": [ "{{baseUrl}}" ], "path": [ "organizations" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"5e8f2a1b-3c4d-4e5f-8a9b-0c1d2e3f4a5b\",\n \"name\": \"Acme\",\n \"plan\": \"trial\",\n \"trialDaysLeft\": 41,\n \"isPaid\": false,\n \"isExempt\": false,\n \"lockState\": \"active\",\n \"isExpired\": false,\n \"billing\": {\n \"model\": \"per_user\",\n \"pricePerSeat\": 25,\n \"monthlyTotal\": 0,\n \"note\": \"Trial — no charge\"\n },\n \"usage\": {\n \"currentUsers\": 3,\n \"currentProjects\": 2,\n \"currentActiveReleases\": 1\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/organizations", "host": [ "{{baseUrl}}" ], "path": [ "organizations" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] }, { "name": "Get OpenAPI specification", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/openapi", "host": [ "{{baseUrl}}" ], "path": [ "openapi" ] }, "description": "Redirects to the static OpenAPI JSON spec at `/openapi.json`.", "auth": { "type": "noauth" } }, "response": [] } ] }, { "name": "Webhooks", "description": "Manage outgoing webhook subscriptions.", "item": [ { "name": "List webhook subscriptions", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "webhooks" ] }, "description": "Returns all active webhook subscriptions for the organization." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "webhooks" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"url\": \"string\",\n \"events\": [\n \"build.created.v1\"\n ],\n \"status\": \"active\",\n \"created_at\": \"2026-10-01T12:00:00Z\"\n }\n ]\n}" } ] }, { "name": "Create webhook subscription", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "webhooks" ] }, "description": "Register a new webhook endpoint. The signing secret is returned once — save it immediately.", "body": { "mode": "raw", "raw": "{\n \"url\": \"string\",\n \"events\": [\n \"string\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "webhooks" ] } }, "status": "Created", "code": 201, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": {\n \"id\": \"00000000-0000-0000-0000-000000000000\",\n \"url\": \"string\",\n \"events\": [\n \"build.created.v1\"\n ],\n \"status\": \"active\",\n \"created_at\": \"2026-10-01T12:00:00Z\"\n },\n \"secret\": \"whsec_0000000000000000000000000000000000000000000000000000000000000000\"\n}" }, { "name": "400 Bad Request", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/webhooks", "host": [ "{{baseUrl}}" ], "path": [ "webhooks" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" } ] }, { "name": "Delete webhook subscription", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/webhooks/{{webhookId}}", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", "{{webhookId}}" ] }, "description": "Soft-deletes a webhook subscription. No further events will be delivered." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/webhooks/{{webhookId}}", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", "{{webhookId}}" ] } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{}" }, { "name": "400 Bad Request", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/webhooks/{{webhookId}}", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", "{{webhookId}}" ] } }, "status": "Bad Request", "code": 400, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"BAD_REQUEST\",\n \"message\": \"The 'name' field is required.\",\n \"details\": {\n \"field\": \"name\"\n }\n }\n}" }, { "name": "404 Not Found", "originalRequest": { "method": "DELETE", "header": [], "url": { "raw": "{{baseUrl}}/webhooks/{{webhookId}}", "host": [ "{{baseUrl}}" ], "path": [ "webhooks", "{{webhookId}}" ] } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Build not found.\"\n }\n}" } ] } ] } ] }