Skip to content
Artbucket

Take a brand from its files

POST
/api/v1/brands/{slug}/files/import
curl --request POST \
  --url http://localhost:3000/api/v1/brands/example/files/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "files": { "additionalProperty": "example" }, "assets": { "additionalProperty": "example" }, "commit": "example", "message": "example", "dryRun": true, "merge": true, "base": { "additionalProperty": "example" }, "publish": true }'

The brand’s rules, pages, theme and name as the files say them, in one version of its history. With a source that remembers what both sides last agreed, what changed here since is kept: the files win only where both changed the same rule, page or setting, and conflicts names each. Files under assets/ are named in assets by id or by the SHA-256 of their bytes; a 422 lists every problem at its file and line (detail.errors) and the files to upload first (detail.missing); a brand.yaml whose slug names another brand is one. dryRun answers what would change. pending: the brand still holds changes the files lack, to export back. Takes setup on the project.

Scope: write.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
slug
required
string

Brand slug

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
files
required

The brand’s files by path in its folder: brand.yaml, rules/.yaml, pages/.yaml. Others are left alone

object
key
additional properties
string
<= 2000000 characters
assets

The files under assets/ the brand’s files point at: path to asset id, or to the SHA-256 of its bytes (upload first)

object
key
additional properties
string
<= 64 characters
commit

The commit the files are at, when they are the repository’s: recorded as agreed, when the brand has a source

string
>= 1 characters <= 100 characters
message

The commit’s message: its first line names the version the import makes

string
<= 2000 characters
dryRun

Check and merge, answer what would change, write nothing

boolean
merge

Keep what changed here since the source last agreed (default); false takes the files whole

boolean
base

For a brand with no source: the files as you last had them from it (a pull, or your last push). What changed here since is kept

object
key
additional properties
string
<= 2000000 characters
publish
Any of:
boolean
Examplegenerated
{
  "files": {
    "additionalProperty": "example"
  },
  "assets": {
    "additionalProperty": "example"
  },
  "commit": "example",
  "message": "example",
  "dryRun": true,
  "merge": true,
  "base": {
    "additionalProperty": "example"
  },
  "publish": true
}

Responses

Section titled “Responses”

200

Section titled “200”

What changed

Media typeapplication/json
object
data
required
object
brand
required
string
applied
required

Something changed: a new version in the brand’s history

boolean
version
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
published
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
diff
required
object
name
required
Any of:
object
before
required
string
after
required
string
rules
required
Array<object>
object
change
required
string
Allowed values: added removed changed
key
required
string
context
required
string | null
type
required
string
Allowed values: color text number list font
before
after
fields

What changed: value, usage, label, spec, assets, type

Array<string>
pages
required
Array<object>
object
change
required
string
Allowed values: added removed changed moved
slug
required
string
title
required
string
fields

Changed: the page’s own fields that changed (title, lede…)

Array<string>
sections

Changed: its sections that changed, by id

Array<object>
object
change
required
string
Allowed values: added removed changed moved
id
required
string
template
required
string
title
required
string
fields

Changed: which of its fields

Array<string>
theme
required

Theme settings changed

Array<string>
reordered
required

The rules’ order changed

boolean
conflicts
required

Pieces both sides changed differently: the files’ side was taken, this side’s is in the history

Array<object>
object
what
required
string
ours
required
theirs
required
warnings
required
Array<object>
object
file
required
string
line
integer
>= -9007199254740991 <= 9007199254740991
message
required
string
pending
required

The brand holds changes the files lack: export them back

boolean
Example
{
  "data": {
    "diff": {
      "rules": [
        {
          "change": "added",
          "type": "color"
        }
      ],
      "pages": [
        {
          "change": "added",
          "sections": [
            {
              "change": "added"
            }
          ]
        }
      ]
    }
  }
}

422

Section titled “422”

Problems in the files

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
detail
required
object
errors
required
Array<object>
object
file
required
string
line
integer
>= -9007199254740991 <= 9007199254740991
message
required
string
warnings
required
Array<object>
object
file
required
string
line
integer
>= -9007199254740991 <= 9007199254740991
message
required
string
missing
required

Files under assets/ to upload, then name in assets by SHA-256

Array<string>
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "errors": [
        {
          "file": "example",
          "line": 1,
          "message": "example"
        }
      ],
      "warnings": [
        {
          "file": "example",
          "line": 1,
          "message": "example"
        }
      ],
      "missing": [
        "example"
      ]
    }
  }
}

default

Section titled “default”

An error

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
detail
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": "example"
  }
}