The bundle's links, its traceability matrices, and suggested trace IDs (REQ-050, REQ-052, REQ-058).

GET

/docs/{docId}/trace

curl --request GET \
  --url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/trace

Parameters

Path Parameters

docId

required

string format: uuid

The ID of one spec doc.

Responses

200

The trace view of the current version.

Media typeapplication/json

object

links

required

The links of the current version, from frontmatter and link rules.

Array<object>

object

kind

required

string

Allowed values: implements refines references supersedes implemented-by

origin

required

string

Allowed values: frontmatter rule adopted

target_kind

required

string

Allowed values: bundle external

target_ref

required

The target as written. For an incoming link, the source bundle’s slug.

string

bundle

The linked bundle. Absent when no bundle matches the target.

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

target_url

Where a person opens an external target (DEC-021).

string

state

The state of an external link, as the last review run read it.

string

Allowed values: aligned drifted conflicting unchecked

state_reason

Why the link is in that state. It says what stopped an unchecked read.

string

checked_at

When a run last read the external target.

string format: date-time

removable

True when DELETE /docs/{docId}/links can remove the link: an adopted link, or a frontmatter link of a doc Speccy writes. Absent on an incoming link.

boolean

incoming

required

Links from other bundles to this one.

Array<object>

object

kind

required

string

Allowed values: implements refines references supersedes implemented-by

origin

required

string

Allowed values: frontmatter rule adopted

target_kind

required

string

Allowed values: bundle external

target_ref

required

The target as written. For an incoming link, the source bundle’s slug.

string

bundle

The linked bundle. Absent when no bundle matches the target.

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

target_url

Where a person opens an external target (DEC-021).

string

state

The state of an external link, as the last review run read it.

string

Allowed values: aligned drifted conflicting unchecked

state_reason

Why the link is in that state. It says what stopped an unchecked read.

string

checked_at

When a run last read the external target.

string format: date-time

removable

True when DELETE /docs/{docId}/links can remove the link: an adopted link, or a frontmatter link of a doc Speccy writes. Absent on an incoming link.

boolean

standalone

object

reason

required

string

acknowledged_by

required

string

matrices

required

One matrix for this bundle’s own IDs, when other bundles implement it, and one for each bundle it implements.

Array<object>

object

upstream

required

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

rows

required

Array<object>

object

id

required

string

text

required

string

anchor

required

A range of text with context (SDD §8.8).

object

file

required

string

heading_path

required

Array<string>

quote

required

string

prefix

required

string

suffix

required

string

start

required

Byte offset of the quote in the file.

integer

end

required

integer

detached

The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).

boolean

columns

required

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

cells

required

Cells[row][column].

Array<Array<object>>

editable

required

Editable[column] says whether the caller can edit that column’s spec doc, and so answer its gaps and withdraw its acknowledgements.

Array<boolean>

suggestions

required

Array<object>

object

id

required

string

text

required

string

anchor

required

A range of text with context (SDD §8.8).

object

file

required

string

heading_path

required

Array<string>

quote

required

string

prefix

required

string

suffix

required

string

start

required

Byte offset of the quote in the file.

integer

end

required

integer

detached

The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).

boolean

sections

The heading path of each section of this doc, in order, for the answer “This doc covers it”.

Array<Array<string>>

Example

{
  "links": [
    {
      "kind": "implements",
      "origin": "frontmatter",
      "target_kind": "bundle",
      "state": "aligned"
    }
  ],
  "incoming": [
    {
      "kind": "implements",
      "origin": "frontmatter",
      "target_kind": "bundle",
      "state": "aligned"
    }
  ],
  "matrices": [
    {
      "cells": [
        [
          {
            "state": "referenced"
          }
        ]
      ]
    }
  ]
}

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

Example^generated

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