One version, and what changed

GET

/api/v1/brands/{slug}/versions/{number}

const url = 'http://localhost:3000/api/v1/brands/example/versions/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:3000/api/v1/brands/example/versions/example \
  --header 'Authorization: Bearer <token>'

The rules as they were. diff goes from the version before (or against) to this one; with against=current, from this one to now.

Scope: read.

Authorizations

bearer
session
None

Parameters

Path Parameters

slug

required

string

Brand slug

number

required

string

Version number

Query Parameters

against

string

A version number, or “current”

Responses

200

The version

application/json

object

data

required

object

number

required

integer

>= -9007199254740991 <= 9007199254740991

kind

required

string

Allowed values: baseline edit restore

name

required

string | null

actor

required

Who: a person’s name, an API key’s name, or “web” for the app without an account

string

changed

required

Keys touched; a page as page:{slug}, and theme

Array<string>

restoredFrom

required

Any of:

integer
null

integer

>= -9007199254740991 <= 9007199254740991

summary

required

string

rules

required

Array<object>

object

key

required

string

label

string

context

required

string | null

type

required

string

Allowed values: color text number list font

value

required

spec

object

key

additional properties

usage

required

string | null

position

required

integer

>= -9007199254740991 <= 9007199254740991

assets

required

Array<object>

object

required

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

rendition

required

string | null

pages

required

Any of:

Array<object>
null

Array<object>

object

slug

required

string

title

required

string

position

required

integer

>= -9007199254740991 <= 9007199254740991

hidden

required

boolean

sections

required

Array<object>

object

required

string

template

required

GET /api/v1/brand/templates lists them

string

title

required

string

body

required

Markdown

string

width

required

string

Allowed values: text wide full

columns

required

integer

>= -9007199254740991 <= 9007199254740991

tone

required

Its ground: plain, tint, brand, panel, dark, color, image or pattern

string

hidden

required

boolean

keys

required

The rules it shows, by key, in order

Array<string>

props

required

Its template’s own settings

object

key

additional properties

eyebrow

string

lede

string

aside

Markdown

string

tab

Sections sharing a tab name show under one tab

string

background

object

color

string

angle

number

image

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

scrim

number

items

Array<object>

A thing a template lists: a do or a don’t with its picture, a picture in a gallery

object

key

A rule it shows

string

asset

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

title

string

text

Markdown

string

verdict

string

Allowed values: do dont

caption

string

link

string

label

string

icon

string

download

False: for reference, never offered as a download

boolean

audience

string

Allowed values: everyone partners members

contexts

A tab per context, its rules resolved for each

Array<string>

only

Shown only in this context

string

translations

Its words by language tag; readers get them already in their language

object

key

additional properties

object

title

string

<= 300 characters

eyebrow

string

<= 120 characters

lede

string

<= 1000 characters

body

string

<= 20000 characters

aside

string

<= 4000 characters

items

Array

<= 60 items

Any of:

object
null

object

title

string

<= 200 characters

text

string

<= 4000 characters

caption

string

<= 500 characters

parent

string

eyebrow

string

lede

string

cover

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

icon

string

audience

string

Allowed values: everyone partners members

tabs

boolean

aliases

Array<string>

layout

Left out: book

string

Allowed value: landing

translations

object

key

additional properties

object

title

string

eyebrow

string

lede

string

updatedAt

string

publishedAt

required

Any of:

string
null

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/

publishedBy

required

string | null

note

required

What changed, for readers, given when it was published

string | null

noteImage

required

Any of:

string
null

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

createdAt

required

string format: date-time

updatedAt

required

Edits close together extend a version; this is its last

string format: date-time

theme

required

Any of:

object
null

object

accent

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

accentUse

Hairline: the accent draws rules and marks, never fills

string

Allowed values: fill hairline

surface

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

panel

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

dark

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

ink

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

muted

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

head

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

body

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

label

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

logo

Any of:

string
null

string

<= 120 characters /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/

device

Any of:

string
null

string format: uuid

/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/

radius

Corner radius in px

integer

<= 40

width

string

Allowed values: narrow normal wide

density

string

Allowed values: compact normal airy

scale

Heading size ratio; 1.25 when left out

number

>= 1.067 <= 1.618

nav

string

Allowed values: sidebar top overlay

band

Every page opens on a band of the brand color; header band says the same

boolean

header

A page’s opening: on the page, on a band of the brand color, or beside its cover

string

Allowed values: plain band split

separation

Between two sections on the page’s own ground: space alone, or a hairline too

string

Allowed values: space hairline

numbering

Number chapters and pages: 01, 01.2

boolean

motion

Subtle: sections reveal as they scroll in; never with reduced motion

string

Allowed values: none subtle

toc

On this page: a side column, a list under the page header, or hidden

string

Allowed values: side inline none

titles

Section titles: headings (medium), or headlines (large, huge); a section’s own size wins

string

Allowed values: medium large huge

grounds

Alternate: every other section on the page’s own ground sits on the panel, so a long page has rhythm; canvas: under its header the page sits on the panel, dotted like a whiteboard, its section titles centered

string

Allowed values: plain alternate canvas

languages

The languages readers pick from; the first is the one the pages are written in

Array<object>

<= 12 items

object

code

required

string

<= 20 characters /^[a-z]{2,3}(-[a-z0-9]{2,8})?$/

label

required

string

>= 1 characters <= 40 characters

dir

From the language when left out

string

Allowed values: ltr rtl

links

Links beside search and print on the brand’s pages: its repository, its Figma library, its site

Array<object>

<= 8 items

object

label

required

string

>= 1 characters <= 40 characters

url

required

Http or https; a link to GitHub, Figma, npm and the like shows its icon

string format: uri

<= 2000 characters

against

required

Any of:

unknown
null

Any of:

integer
string

integer

>= -9007199254740991 <= 9007199254740991

diff

required

Added, removed, changed (field by field) or moved, per rule

Array<object>

object

key

additional properties

pageDiff

required

Pages that differ, as page:{slug}

Array<string>

themeChanged

required

The theme differs; against current, whether a restore would change it

boolean

Example

{
  "data": {
    "kind": "baseline",
    "rules": [
      {
        "type": "color"
      }
    ],
    "pages": [
      {
        "sections": [
          {
            "width": "text",
            "items": [
              {
                "verdict": "do"
              }
            ],
            "audience": "everyone"
          }
        ],
        "audience": "everyone",
        "layout": "landing"
      }
    ],
    "theme": {
      "accentUse": "fill",
      "width": "narrow",
      "density": "compact",
      "nav": "sidebar",
      "header": "plain",
      "separation": "space",
      "motion": "none",
      "toc": "side",
      "titles": "medium",
      "grounds": "plain",
      "languages": [
        {
          "dir": "ltr"
        }
      ]
    },
    "against": "current"
  }
}

default

An error

application/json

object

error

required

object

code

required

string

message

required

string

detail

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "detail": "example"
  }
}

One version, and what changed

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Example

default

Examplegenerated

Example^generated