Skip to content
Artbucket

Deploy to a site

POST
/api/v1/sites/{id}/deployments
curl --request POST \
  --url 'http://localhost:3000/api/v1/sites/example/deployments?kind=guidelines' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/zip' \
  --data binary

The body is a zip of static files (Content-Type: application/zip): a built site with index.html at its root, or in the one folder it wraps. It is unpacked, checked and stored, then live at path, the deployment there before kept as replaced. A brand portal’s root is drawn by Artbucket: mount a build beside it, at a path such as /docs. When the zip holds artbucket.site.json, every asset it names is checked too. Every file is matched against the project’s library, by its bytes and by the /a/ and /c/ addresses in its HTML, CSS and JS: a copy or a pinned link of a replaced, unapproved or expired asset fails the deployment, naming the file and the replacement. Served on the site’s own address only.

Scope: write.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Site id

Query Parameters

Section titled “Query Parameters”
path
string

Where it is mounted: / (the default) or a path such as /docs

kind
string
Allowed values: guidelines landing docs storybook

What it is; the site’s own kind when left out

commit
string

The commit it was built from, when a build says

ref
string

The branch or tag of that commit

preview
string

A preview’s name, such as pr-12: the build is checked as any deployment is, then served at {name}–{site}.{PORTAL_DOMAIN} behind the site’s own door, never live. A later build of the same preview replaces it; previews go 30 days after they were made

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/zip
string format: binary

Responses

Section titled “Responses”

201

Section titled “201”

The deployment

Media typeapplication/json
object
data
required
object
id
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)$/
path
required

Where it is mounted

string
kind
required

External: an external site’s record of what it uses, no files

string
Allowed values: guidelines landing docs storybook external
state
required

Held: it looks like phishing or malware and waits for whoever runs the server; its files are kept, not served. preview: a pull request’s build at its own address, never live

string
Allowed values: checking live failed replaced held preview
preview
required

A preview’s name, such as pr-12; null for any other deployment

string | null
url

Where a preview answers: {name}–{site}.{PORTAL_DOMAIN}, at its mount. Given for previews only

string | null
files
required
integer
>= -9007199254740991 <= 9007199254740991
bytes
required
integer
>= -9007199254740991 <= 9007199254740991
commit
required
string | null
ref
required
string | null
error
required

Why it failed, or why it is held

string | null
manifest
required
Any of:
object
key
additional properties
uses
required

What it uses of the project’s library, found in its files: its lineage

Array<object>
object
asset
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)$/
how
required

Copy: a file is the asset’s bytes; link: /a/{id}; current: /c/{id}, the version it served; declared: named by artbucket.site.json

string
Allowed values: copy link current declared
file
required

The build’s file it was found in

string | null
componentUses
required

The component versions it is built with, as its artbucket.site.json names them (artbucket site scan adds them for an external site)

Array<string>
problems
required

What of it may no longer be shown, as the daily re-check of live builds last found: a license ended or a logo replaced since it deployed. Empty when all is well

Array<string>
flags
required

Signs it looks like phishing or malware (a page asking for a password, a card or a recovery phrase; a program to download), one line each

Array<string>
checkedAt
required

When it was last checked

string | null
createdBy
required
string
createdAt
required
string
Example
{
  "data": {
    "kind": "guidelines",
    "state": "checking",
    "uses": [
      {
        "how": "copy"
      }
    ]
  }
}

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