Skip to content
Speccy

Request a waiver for one finding, with a reason of at least 20 characters (REQ-072).

POST
/docs/{docId}/waivers
curl --request POST \
  --url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/waivers \
  --header 'Content-Type: application/json' \
  --data '{ "finding_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "reason": "example", "trace": { "status": "out_of_scope", "target": "example" }, "standalone": true }'

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
docId
required
string format: uuid

The ID of one spec doc.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
finding_id
required
string format: uuid
reason
required
string
trace

The answer to a coverage gap that says the ID is intentionally absent from this doc. It is an Acknowledgement, and it follows the profile’s waiver policy.

object
status
required
string
Allowed values: out_of_scope covered_by
target

For covered_by, the slug of the doc that covers the ID.

string
standalone

Mark the doc standalone: the answer to a links.has-upstream finding. It is an Acknowledgement, and its approval writes standalone to the doc’s sidecar.

boolean

Responses

Section titled “ Responses ”

200

Section titled “200”

The waiver.

Media typeapplication/json
object
id
required
string format: uuid
doc_id
required
string format: uuid
check_slug
required
string
level
required
string
section
required
Array<string>
reason
required
string
status
required

Withdrawn is an approved Acknowledgement that a person took out of the sidecar.

string
Allowed values: requested approved rejected invalidated withdrawn
requested_by
required
string
approvals
required
Array<string>
policy
required

The waiver policy (§9.1).

string
needed
required

The approvals the policy needs.

integer
can_approve
required

Whether the caller can approve or reject it now.

boolean
decision_reason

Why the waiver is rejected. Only a rejected waiver has one.

string
section_range

The byte range of the waiver’s section in the current main doc. Absent when the section is gone.

object
start
required
integer
end
required
integer
trace

An Acknowledgement of one upstream trace ID. On approval it goes in the sidecar under trace.

object
id
required
string
status
required
string
Allowed values: out_of_scope covered_by
target
string
verification

What a verification waiver excuses. It never goes in the sidecar.

object
trace_id
required
string
repo
required

The code repo, or the folder, as the verification run names it.

string
run_id

The verification run the request came from. Empty for a request that named no run.

string format: uuid
standalone

True for a standalone Acknowledgement. On approval it goes in the sidecar under standalone.

boolean
withdrawn_by

Who withdrew the Acknowledgement. Only a withdrawn one has it.

string
created_at
required
string format: date-time
Example
{
  "status": "requested",
  "trace": {
    "status": "out_of_scope"
  }
}

default

Section titled “default”

An error.

Media typeapplication/problem+json

RFC 9457 problem details with a stable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
instance
string
code
required

A stable machine-readable error code.

string
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "code": "example"
}