Skip to content
Speccy

Write a type into skipped files, so they become spec docs (REQ-001). One request takes every picked doc, so the order of the picks does not matter (#73).

POST
/skipped
curl --request POST \
  --url https://example.com/api/v1/skipped \
  --header 'Content-Type: application/json' \
  --data '{ "items": [ { "path": "example", "profile": "example", "link": { "kind": "example", "target": "example" } } ] }'

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
items
required
Array<object>
>= 1 items
object
path
required
string
profile
required
string
link

A link a person confirmed. target is the root-relative path of the doc it links to.

object
kind
required
string
target
required
string
Examplegenerated
{
  "items": [
    {
      "path": "example",
      "profile": "example",
      "link": {
        "kind": "example",
        "target": "example"
      }
    }
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “201”

The new spec docs, in the order of the request.

Media typeapplication/json
object
items
required
Array<object>

One spec doc of a bundle, with its own profile, versions, review runs and verdict.

object
id
required
string format: uuid
bundle_id
required

The bundle that holds the spec doc.

string format: uuid
slug
required
string
title
required
string
profile_key
required

The profile of the spec doc.

string
source_kind
required
string
Allowed values: local db github
github

Where a GitHub bundle comes from, and its draft (REQ-123).

object
repo
required
string
branch
required
string
path
required
string
draft
required

The current version has changes that are not on GitHub.

boolean
ahead
required

GitHub changed after the draft started.

boolean
pr_url
string
path
required

The path of the spec doc in its bundle.

string
current_version
required
object
id
required
string format: uuid
number
required
integer format: int64
created_by
required
string
message
required
string
created_at
required
string format: date-time
updated_at
required
string format: date-time
verdict

The verdict of the bundle’s latest completed run. It is stale when that run is not on the current version.

object
run_id
required
string format: uuid
version_number
required
integer format: int64
kind
required

Lint means only the lint stage ran.

string
Allowed values: lint full
result
required
string
Allowed values: build_ready not_build_ready stale
score
required
integer
radar
required
object
key
additional properties
integer
waiver_count
required
integer
relaxed_count
required

Checks in adoption mode (REQ-133).

integer
must
required

Open MUST findings.

integer
should
required
integer
info
required
integer
blocking_threads

Open blocking threads. Any makes the verdict Not Build Ready (§8.6 rule 2).

integer
ai_run_id

The full review whose AI findings this verdict counts. For a full run, the run itself.

string format: uuid
ai_version_number

The version the AI review read, when it is older than this verdict’s version.

integer format: int64
sections_changed

How many sections changed since the AI review read the doc.

integer
stale_reason

Set when the verdict is stale because a linked bundle has a newer version than the run read (REQ-056).

string
Allowed values: upstream_changed
stale_upstream

With stale_reason upstream_changed, the linked spec docs that have a newer version than the run read.

Array<object>
object
id
required
string format: uuid
bundle_id
required

The bundle that holds the spec doc.

string format: uuid
slug
required
string
title
required
string
profile_key
required
string
run_error

Why the latest run on the current version failed, when it failed.

string
adopt

The frontmatter keys the main doc does not name, and the values a review used for them (REQ-135). Absent when the doc names both.

object
type
string
size
string
status
string
Allowed values: draft in_review approved superseded
next_action

The one thing the caller must do next on this bundle. Absent when nothing is open. The list carries the kind and the sentence; one bundle also carries the target.

object
kind
required
string
Allowed values: waiver decide fix review adopt request_review handoff
sentence
required

What to do, in words, for a button label or a status line.

string
waiver_id
string format: uuid
finding_id
string format: uuid
tour_key

The key of the tour point to open.

string
Example
{
  "items": [
    {
      "source_kind": "local",
      "verdict": {
        "kind": "lint",
        "result": "build_ready",
        "stale_reason": "upstream_changed"
      },
      "status": "draft",
      "next_action": {
        "kind": "waiver"
      }
    }
  ]
}

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"
}