BETA
Krafter Docs

Appearance

Tasks ​

Create and manage remediation tasks linked to audit findings. A task is the unit of work that closes a finding — it carries an owner, a priority, an SLA, and optional pointers to an external ticket or pull request.

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

List Tasks ​

Retrieve all remediation tasks in a project, optionally filtered by status. Results are cursor-paginated.

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

Required scope: audit:read

Query Parameters ​

ParameterTypeRequiredDescription
statusstringNoFilter by status. One of backlog, in_progress, blocked, ready_verify, done.
cursorstringNoPagination cursor from a previous response.
limitintegerNoPage size. Defaults to the server limit.

Tasks 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/tasks?status=backlog&limit=20" \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response ​

json
{
  "data": [
    {
      "id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
      "finding_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "title": "Add Content-Security-Policy header",
      "status": "backlog",
      "priority": "high",
      "owner_id": "22222222-2222-2222-2222-222222222222",
      "sla_due_at": "2025-06-20T00:00:00Z",
      "external_ticket_key": null,
      "pr_url": null,
      "created_at": "2025-06-10T15:00:00Z",
      "updated_at": "2025-06-10T15:00:00Z"
    }
  ],
  "meta": {
    "request_id": "K-scg2wTP6zbkVFFFIYo",
    "total": 12,
    "next_cursor": "eyJpbnNlcnRlZF9hdCI6IjIwMjUtMDYtMTBUMTU6MDA6MDBaIn0="
  },
  "error": null
}

Notes:

  • priority is one of low, medium, high, critical. Defaults to medium for new tasks.
  • owner_id is the user UUID assigned to the task, or null if unassigned.
  • sla_due_at is the SLA deadline (UTC, ISO 8601), or null if none was set.
  • external_ticket_key is the canonical key in an external tracker (e.g. SEC-142), or null.
  • pr_url is the URL of the pull request that addresses the task, or null.

There is no description field on tasks. The remediation guidance lives on the linked finding's recommended_fix object.

Create Task ​

Create a new remediation task linked to an existing finding in the same project.

POST /orgs/:org_id/projects/:project_id/audit/tasks

Required scope: audit:write

Request Body ​

FieldTypeRequiredDescription
finding_idstringYesUUID of the finding this task addresses. Must belong to the same project.
titlestringYesShort description of the remediation work.
statusstringNoInitial status. One of backlog, in_progress, blocked, ready_verify, done. Defaults to backlog.
prioritystringNoOne of low, medium, high, critical. Defaults to medium.
owner_idstringNoUUID of the user assigned to the task.
sla_due_atstringNoSLA deadline as ISO 8601 timestamp (UTC).
external_ticket_keystringNoKey in an external tracker (e.g. SEC-142).
pr_urlstringNoURL of the pull request addressing the task.

Example Request ​

bash
curl -X POST https://app.krafter.dev/api/v1/orgs/:org_id/projects/:project_id/audit/tasks \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "finding_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "title": "Add Content-Security-Policy header",
    "priority": "high",
    "owner_id": "22222222-2222-2222-2222-222222222222",
    "sla_due_at": "2025-06-20T00:00:00Z"
  }'

Example Response ​

json
// 201 Created
{
  "data": {
    "id": "f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c",
    "finding_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "title": "Add Content-Security-Policy header",
    "status": "backlog",
    "priority": "high",
    "owner_id": "22222222-2222-2222-2222-222222222222",
    "sla_due_at": "2025-06-20T00:00:00Z",
    "external_ticket_key": null,
    "pr_url": null,
    "created_at": "2025-06-10T15:00:00Z",
    "updated_at": "2025-06-10T15:00:00Z"
  },
  "meta": {
    "request_id": "L-tdh3xUQ7aclWGGGJZp"
  },
  "error": null
}

Error Responses ​

json
// 422 Unprocessable Entity — missing finding_id/title, invalid status/priority, etc.
{
  "data": null,
  "meta": {
    "request_id": "L-tdh3xUQ7aclWGGGJZp"
  },
  "error": {
    "code": "invalid_params"
  }
}
json
// 404 Not Found — finding_id does not exist in this project
{
  "data": null,
  "meta": {
    "request_id": "L-tdh3xUQ7aclWGGGJZp"
  },
  "error": {
    "code": "not_found"
  }
}

Update Task ​

Update an existing task. Only provided fields are changed; the request must include at least one field or it returns 422 invalid_params.

PATCH /orgs/:org_id/projects/:project_id/audit/tasks/:task_id

Required scope: audit:write

Request Body ​

FieldTypeRequiredDescription
titlestringNoShort description of the remediation work.
statusstringNoNew status. Same enum as Create Task.
prioritystringNoNew priority. Same enum as Create Task.
owner_idstringNoUUID of the user assigned to the task.
sla_due_atstringNoSLA deadline as ISO 8601 timestamp (UTC).
external_ticket_keystringNoKey in an external tracker.
pr_urlstringNoURL of the pull request addressing the task.

The finding_id cannot be changed once the task is created. Create a new task instead if you need to re-link work to a different finding.

Example Request ​

bash
curl -X PATCH https://app.krafter.dev/api/v1/orgs/:org_id/projects/:project_id/audit/tasks/f6a7b8c9-0d1e-2f3a-4b5c-6d7e8f9a0b1c \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "owner_id": "33333333-3333-3333-3333-333333333333",
    "pr_url": "https://github.com/acme/web-app/pull/142"
  }'

Example Response ​

The response is the full task shape (same as List Tasks), reflecting the applied changes.

Error Responses ​

json
// 404 Not Found
{
  "data": null,
  "meta": {
    "request_id": "M-uei4yVR8bdmXHHHKaq"
  },
  "error": {
    "code": "not_found"
  }
}
json
// 422 Unprocessable Entity — empty patch, invalid status/priority, etc.
{
  "data": null,
  "meta": {
    "request_id": "M-uei4yVR8bdmXHHHKaq"
  },
  "error": {
    "code": "invalid_params"
  }
}

Verifications close tasks

You don't transition a task directly to done. Run a verification instead — when the verification passes, the task is moved to done and the linked finding is moved to resolved automatically.

Built by Krafter Studio

Copyright © 2024-present Krafter