BETA
Krafter Docs

Appearance

Verifications ​

Verifications confirm that a remediation task actually fixed the underlying finding. Each verification is created against a single task, runs an asynchronous worker that re-checks the issue, and on approval transitions both the task and the underlying finding to terminal states.

Base URL: https://app.krafter.dev/api/v1

List Verifications ​

Retrieve all verifications for a project. Results are cursor-paginated.

GET /orgs/:org_id/projects/:project_id/audit/verifications?cursor=...&limit=...

Required scope: audit:read

Query Parameters ​

ParameterTypeRequiredDescription
cursorstringNoPagination cursor from a previous response.
limitintegerNoPage size. Defaults to the server limit.

Verifications are ordered by inserted_at descending, then id descending.

Example Request ​

bash
curl "https://app.krafter.dev/api/v1/orgs/:org_id/projects/:project_id/audit/verifications?limit=20" \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response ​

json
{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-9788-7c6d-5e4f3a2b1c0d",
      "task_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
      "result": "passed",
      "checks": [
        {
          "key": "security_header_csp",
          "before": "failed",
          "after": "passed",
          "status": "passed"
        },
        {
          "key": "lcp",
          "before": 2.9,
          "after": 1.7,
          "status": "passed"
        }
      ],
      "verified_by_id": "22222222-2222-2222-2222-222222222222",
      "verified_at": "2025-06-12T11:00:00Z",
      "created_at": "2025-06-12T10:55:00Z",
      "updated_at": "2025-06-12T11:00:00Z"
    },
    {
      "id": "e2d3c4b5-a697-8889-6c5d-4e3f2a1b0c9d",
      "task_id": "a7b8c9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "result": "pending",
      "checks": [
        {
          "key": "security_header_csp",
          "before": "failed",
          "after": "pending",
          "status": "running"
        }
      ],
      "verified_by_id": null,
      "verified_at": null,
      "created_at": "2025-06-12T10:50:00Z",
      "updated_at": "2025-06-12T10:50:00Z"
    }
  ],
  "meta": {
    "request_id": "N-vfj5zWS9cenYIIILbr",
    "total": 5,
    "next_cursor": null
  },
  "error": null
}

Notes on the response shape:

  • task_id (not finding_id) is the link to the remediation task. Each verification belongs to exactly one task. Use the linked task to find the finding.
  • result is one of pending, passed, failed. There is no separate status field.
  • checks is an array of per-check records {key, before, after, status}. Initial values are seeded by the worker; on approval/reopen each item's status is normalised to passed / failed.
  • verified_by_id is the user UUID who approved or reopened the verification, or null while it is still pending.
  • verified_at is the timestamp of the approval/reopen action, or null while pending.

There are no reviewer or notes fields — verifications carry no free-form text. The audit trail is the per-check before/after/status set.

Run Verification ​

Create a verification for a single task. The verification is queued and the Verification Worker re-runs the relevant checks asynchronously. Each call consumes one unit of the team's AI quota.

POST /orgs/:org_id/projects/:project_id/audit/verifications/run

Required scope: audit:write

Request Body ​

FieldTypeRequiredDescription
task_idstringYesUUID of the task being verified. Must belong to the same project.

One task per call

Verifications are created one task at a time. To verify multiple tasks, call this endpoint once per task.

Example Request ​

bash
curl -X POST https://app.krafter.dev/api/v1/orgs/:org_id/projects/:project_id/audit/verifications/run \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c"
  }'

Example Response ​

json
// 202 Accepted
{
  "data": {
    "id": "d3c4b5a6-9788-7889-5d4e-3f2a1b0c9d8e",
    "task_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
    "result": "pending",
    "checks": [
      {
        "key": "security_header_csp",
        "before": "failed",
        "after": "pending",
        "status": "running"
      },
      {
        "key": "lcp",
        "before": 2.9,
        "after": null,
        "status": "running"
      }
    ],
    "verified_by_id": null,
    "verified_at": null,
    "created_at": "2025-06-12T10:50:00Z",
    "updated_at": "2025-06-12T10:50:00Z"
  },
  "meta": {
    "request_id": "O-wgk6aXT0dfoZJJJMcs"
  },
  "error": null
}

Error Responses ​

json
// 422 Unprocessable Entity — missing or invalid task_id
{
  "data": null,
  "meta": {
    "request_id": "O-wgk6aXT0dfoZJJJMcs"
  },
  "error": {
    "code": "invalid_params"
  }
}
json
// 404 Not Found — task does not exist in this project
{
  "data": null,
  "meta": {
    "request_id": "O-wgk6aXT0dfoZJJJMcs"
  },
  "error": {
    "code": "not_found"
  }
}
json
// 429 Too Many Requests — AI quota exhausted for this team
{
  "data": null,
  "meta": {
    "request_id": "O-wgk6aXT0dfoZJJJMcs"
  },
  "error": {
    "code": "quota_exceeded"
  }
}

Approve Verification ​

Mark a verification as passed. This is a transactional action: on success the verification's result becomes passed, the linked task moves to done, the linked finding moves to resolved, and any open regressions for that finding are closed.

POST /orgs/:org_id/projects/:project_id/audit/verifications/:verification_id/approve

Required scope: audit:write

Example Request ​

bash
curl -X POST https://app.krafter.dev/api/v1/orgs/:org_id/projects/:project_id/audit/verifications/d3c4b5a6-9788-7889-5d4e-3f2a1b0c9d8e/approve \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response ​

json
{
  "data": {
    "id": "d3c4b5a6-9788-7889-5d4e-3f2a1b0c9d8e",
    "task_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
    "result": "passed",
    "checks": [
      {
        "key": "security_header_csp",
        "before": "failed",
        "after": "passed",
        "status": "passed"
      }
    ],
    "verified_by_id": "22222222-2222-2222-2222-222222222222",
    "verified_at": "2025-06-12T11:00:00Z",
    "created_at": "2025-06-12T10:50:00Z",
    "updated_at": "2025-06-12T11:00:00Z"
  },
  "meta": {
    "request_id": "P-xhl7bYU1egpaKKKNdt"
  },
  "error": null
}

Error Responses ​

json
// 404 Not Found
{
  "data": null,
  "meta": {
    "request_id": "P-xhl7bYU1egpaKKKNdt"
  },
  "error": {
    "code": "not_found"
  }
}
json
// 422 Unprocessable Entity — task or finding update failed inside the transaction
{
  "data": null,
  "meta": {
    "request_id": "P-xhl7bYU1egpaKKKNdt"
  },
  "error": {
    "code": "request_failed"
  }
}

Reopen Verification ​

Mark a verification as failed. This is the inverse transactional action: the verification's result becomes failed, the linked task moves back to in_progress, the linked finding moves back to in_progress, and a new regression is recorded against the finding with trigger verification_reopened.

POST /orgs/:org_id/projects/:project_id/audit/verifications/:verification_id/reopen

Required scope: audit:write

Example Request ​

bash
curl -X POST https://app.krafter.dev/api/v1/orgs/:org_id/projects/:project_id/audit/verifications/d3c4b5a6-9788-7889-5d4e-3f2a1b0c9d8e/reopen \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response ​

json
{
  "data": {
    "id": "d3c4b5a6-9788-7889-5d4e-3f2a1b0c9d8e",
    "task_id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
    "result": "failed",
    "checks": [
      {
        "key": "security_header_csp",
        "before": "failed",
        "after": "pending",
        "status": "failed"
      }
    ],
    "verified_by_id": "22222222-2222-2222-2222-222222222222",
    "verified_at": "2025-06-12T11:00:00Z",
    "created_at": "2025-06-12T10:50:00Z",
    "updated_at": "2025-06-12T11:05:00Z"
  },
  "meta": {
    "request_id": "Q-yim8cZV2fhqbLLLOeu"
  },
  "error": null
}

Error Responses ​

json
// 404 Not Found
{
  "data": null,
  "meta": {
    "request_id": "Q-yim8cZV2fhqbLLLOeu"
  },
  "error": {
    "code": "not_found"
  }
}
json
// 422 Unprocessable Entity — task/finding/regression update failed inside the transaction
{
  "data": null,
  "meta": {
    "request_id": "Q-yim8cZV2fhqbLLLOeu"
  },
  "error": {
    "code": "request_failed"
  }
}

Built by Krafter Studio

Copyright © 2024-present Krafter