Sync API
Artbucket never talks to a Git host. An integration does: a GitHub or GitLab app, a bot, a CI job. It holds the host’s credentials, reads and writes the repository, and calls these endpoints with an API key. The CLI uses the same ones.
All of them are under /api/v1/brands/{slug}, with
Authorization: Bearer ab_..., and answer { "data": ... }.
| Endpoint | Key | |
|---|---|---|
GET .../source |
read | Where the brand’s files live, and whether the app holds changes they lack |
PUT .../source |
write | Say where they live; with synced, record what both sides now agree on |
DELETE .../source |
write | The brand lives in Artbucket alone again; the repository is left as it is |
POST .../files/export |
read | The brand as files, keeping the repository’s own where they say the same |
GET .../files |
read | The same, with no files to keep: ?assets=files gives every asset a path |
POST .../files/import |
write | Take the brand from files, merged with the app’s changes |
POST .../previews |
write | A pull request’s files as a site at a link, and what they change |
DELETE .../previews?ref=pull/12 |
write | Close a preview’s link |
GET /api/v1/previews/{token} |
none | A page of a preview, for whoever has its link |
Writing takes write on the project, and so does an import that releases
the brand. The full schemas are in the
API reference.
The model
Section titled “The model”For each brand kept in a repository, Artbucket stores its source: the repository, branch and folder, the commit both sides last agreed on, and the brand as of that commit (the base). Every import merges three states: the base, the brand in the app now, and the files.
- Import at a commit (the repository changed): the base becomes the files at that commit.
- Import without a commit (files from anywhere else, like the CLI): the base stays, so the next import still merges from what the repository last said.
PUT .../sourcewithsynced(the integration just committed what Artbucket exported): the base becomes those files, so nothing is merged or exported again.- Moving the source to another repository, branch or folder forgets the base: the next import takes the files whole.
A brand with no source, or no base yet, has nothing to merge from: an import
takes the files whole, unless it sends a base of its own (the files as the
caller last had them, as the CLI does).
The source
Section titled “The source”{ "data": { "source": { "remote": "https://github.com/acme/brand", "branch": "main", "path": "brand", "commit": "9f2c1e7", "syncedAt": "2026-09-30T10:12:00.000Z", "pending": false, "files": 7 }, "connect": null }}| Field | |
|---|---|
remote |
The repository, as its host shows it |
branch |
main unless set |
path |
The brand’s folder in the repository, "" for its root |
commit |
The commit last agreed on, or null |
syncedAt |
When, or null |
pending |
The brand changed in the app since: an export is due |
files |
How many of its assets are files in the repository |
connect |
Where this server’s integration connects a brand (GIT_CONNECT_URL), for a project admin signed in; else null |
source is null for a brand that lives in Artbucket alone.
Connect a brand
Section titled “Connect a brand”A repository that already holds the brand
Section titled “A repository that already holds the brand”curl -X PUT https://assets.example.com/api/v1/brands/acme/source \ -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \ -d '{"remote": "https://github.com/acme/brand", "branch": "main", "path": "brand"}'Then import the folder at its head commit, as below. With no base yet, the
import takes the files whole and records them as the base. Make the brand
first (POST /api/v1/brands with name and slug) when Artbucket doesn’t
have it: the import names it from brand.yaml.
An empty repository, from a brand Artbucket has
Section titled “An empty repository, from a brand Artbucket has”- Export with every asset given a path:
POST .../files/exportwith{ "assets": "files" }. - Commit
files, and each asset inassets, fetched from itsurlwith the key, at its path. - Record it:
PUT .../sourcewith the repository andsynced, the commit and what you committed.
{ "remote": "https://github.com/acme/brand", "branch": "main", "path": "brand", "synced": { "commit": "4b1d0aa", "files": { "brand.yaml": "...", "rules/color.yaml": "...", "pages/overview.yaml": "..." }, "assets": { "assets/logo.svg": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" } }}synced is checked like an import: files that don’t check are refused with
their problems.
The repository changed
Section titled “The repository changed”On a push to the source’s branch that touches its folder, send the folder at that commit:
{ "files": { "brand.yaml": "slug: acme\nname: Acme\n...", "rules/color.yaml": "color.primary:\n type: color\n value: \"#1a5fd0\"\n", "pages/overview.yaml": "title: Acme\nsections: ..." }, "assets": { "assets/logo.svg": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "assets/workshop.jpg": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9" }, "commit": "9f2c1e7a0b3d", "message": "Bluer primary\n\nThe old one failed contrast on the new site."}| Field | |
|---|---|
files |
The folder’s brand.yaml and its rules/ and pages/ YAML, by path in the folder. Any other path is left alone. 500 files at most |
assets |
Each file under assets/, by path: the SHA-256 of its bytes, or the id of the asset it is |
commit |
The commit the files are at. With a source, recorded as the new base |
message |
The commit’s message: its first line names the version the import makes |
dryRun |
true: check and merge, answer what would change, write nothing |
merge |
false: take the files whole, ignoring the base |
base |
For a brand with no source: the files as you last had them from it (your last pull, or your last push), merged from as a source’s base is. The CLI sends it |
publish |
true, or a note: release the brand after, with that note |
{ "data": { "brand": "acme", "applied": true, "version": 14, "published": null, "diff": { "name": null, "rules": [ { "change": "changed", "key": "color.primary", "context": null, "type": "color", "before": "#2563eb", "after": "#1a5fd0", "fields": ["value"] } ], "pages": [{ "change": "changed", "slug": "color", "title": "Color" }], "theme": [], "reordered": false }, "conflicts": [ { "what": "rule color.primary", "ours": { "key": "color.primary", "context": null, "type": "color", "value": "#2563eb", "usage": null, "assets": [] }, "theirs": { "key": "color.primary", "context": null, "type": "color", "value": "#1a5fd0", "usage": null, "assets": [] } } ], "warnings": [], "pending": false }}Here color.primary was changed on both sides since the base: the files’
value won, and the app’s is in the version before.
| Field | |
|---|---|
applied |
Something changed: a new version in the brand’s history |
version |
The brand’s latest version after the import |
published |
The version released, when publish was asked and something was new |
diff |
What changed in the brand, piece by piece: rules (added, removed, changed, with the fields that changed), pages (added, removed, changed, moved; a changed page with its own fields that changed and its sections by id), theme (settings by name), name, reordered |
conflicts |
Pieces both sides changed differently. The files’ side was taken; the app’s is in the history |
warnings |
What readers would trip on, at file and line |
pending |
The brand still holds changes the files lack: export them back |
A conflict’s what names its piece: name, theme.radius,
rule color.primary, rule color.primary (dark-background), page logo
(one side added or removed it), page logo: lede, page logo: section clearspace.
When two sound sides make an unsound whole (a page in the app binding a rule
the files removed), the import takes the files whole and says so as a
conflict on brand.
The brand changed in the app
Section titled “The brand changed in the app”When source.pending is true, export, giving the repository’s files at its
head:
{ "previous": { "brand.yaml": "...", "rules/color.yaml": "...", "pages/overview.yaml": "..." } }{ "data": { "brand": "acme", "files": { "brand.yaml": "...", "rules/color.yaml": "...", "pages/overview.yaml": "..." }, "assets": { "assets/logo.svg": { "id": "7b1d0e3c-5a2f-4c1e-9d3b-0f6a2e8c4b11", "filename": "logo.svg", "mime": "image/svg+xml", "size": 4211, "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "url": "https://assets.example.com/a/7b1d0e3c-5a2f-4c1e-9d3b-0f6a2e8c4b11" } }, "source": { "remote": "https://github.com/acme/brand", "branch": "main", "path": "brand", "commit": "9f2c1e7", "syncedAt": "2026-09-30T10:12:00.000Z", "pending": true, "files": 7 } }}files is the whole brand. A file that says the same as its previous comes
back exactly as it was, comments and all, so:
- to write: each file whose text differs from
previous, or thatpreviouslacks; - to delete: each file of
previousunderrules/orpages/thatfilesno longer has; - assets: each path in
assetswhosesha256the repository’s file doesn’t match, fetched fromurlwith the key.assets: "files"in the request gives every asset the brand points at a path, including ones the repository never held.
Commit them, directly or as a pull request, then record the commit as agreed:
PUT .../source with synced: { commit, files, assets }, the folder as
committed. Until then the source stays pending.
If the commit goes through a pull request that people change before merging,
skip synced: the merge comes back as an import, and the base moves then.
Pull request previews
Section titled “Pull request previews”{ "ref": "pull/12", "title": "Bluer primary", "commit": "c0ffee1", "files": { "brand.yaml": "...", "rules/color.yaml": "..." }, "assets": { "assets/logo.svg": "2c26b46b..." }}{ "data": { "brand": "acme", "ref": "pull/12", "url": "https://assets.example.com/preview/q3Jx0f9mT2c8LwP1aZr4vYbn", "pages": [ { "slug": "overview", "title": "Acme", "url": "https://assets.example.com/preview/q3Jx0f9mT2c8LwP1aZr4vYbn/overview" }, { "slug": "color", "title": "Color", "url": "https://assets.example.com/preview/q3Jx0f9mT2c8LwP1aZr4vYbn/color" } ], "expiresAt": "2026-10-31T09:00:00.000Z", "diff": { "name": null, "rules": [], "pages": [], "theme": [], "reordered": false }, "warnings": [] }}- The files are checked as an import is, and refused the same way.
- One preview per
ref: saving it again (a new push to the pull request) keeps its link and replaces what it shows. diffis what merging would change of the brand as it stands, for the pull request’s comment.- The link needs no account, like a share link, and shows every page that isn’t hidden, members’ pages too, with files signed for whoever opens it. Treat it as you would the pull request.
- It closes 30 days after its last update. Close it sooner when the pull
request is merged or closed:
DELETE .../previews?ref=pull/12.
GET /api/v1/previews/{token}?page=color answers a page of the preview as
data, for an integration that draws its own.
Assets
Section titled “Assets”A path under assets/ is matched to the library by the SHA-256 of its bytes
(or an asset id given in its place). When a file the folder points at isn’t
in the library, the request is refused with missing:
{ "error": { "code": "invalid", "message": "Upload assets/hero.jpg first, then send its SHA-256 in assets", "detail": { "errors": [], "warnings": [], "missing": ["assets/hero.jpg"] } }}Upload each, then send the same request again:
# 1. A ticket to upload to storage directlycurl -X POST https://assets.example.com/api/v1/uploads -H "Authorization: Bearer $KEY" \ -H 'content-type: application/json' -d '{"filename": "hero.jpg", "mime": "image/jpeg", "size": 482113}'# 2. PUT the bytes to the uploadUrl it returned, with the same Content-Type# 3. File itcurl -X POST https://assets.example.com/api/v1/assets -H "Authorization: Bearer $KEY" \ -H 'content-type: application/json' -d '{"token": "<token>", "filename": "hero.jpg", "mime": "image/jpeg"}'A font’s type is read from its bytes when it is filed, whatever media type
the upload gave. Files under assets/ no file points at can be sent or left
out.
Problems
Section titled “Problems”Files that don’t check are refused with 422, every problem at its file and
line, and the files to upload:
{ "error": { "code": "invalid", "message": "pages/color.yaml:6: sections[0].keys[0]: no rule \"color.nope\"; this brand has color.primary, color.ink (and 1 more)", "detail": { "errors": [ { "file": "pages/color.yaml", "line": 6, "message": "sections[0].keys[0]: no rule \"color.nope\"; this brand has color.primary, color.ink" }, { "file": "rules/color.yaml", "line": 3, "message": "color.ink.value: Use #rrggbb or #rrggbbaa" } ], "warnings": [], "missing": [] } }}A check on the host (a GitHub check run, a GitLab code quality report) can put each at its line, under the folder’s path. The messages are listed in the brand folder.
Connecting from the app
Section titled “Connecting from the app”Set GIT_CONNECT_URL on the server to where your integration starts, with
{brand} for the brand’s slug: https://git.example.com/connect?brand={brand}.
New brand, the brand’s menu (Connect Git) and Edit’s Git way link there for
project admins, with {brand} empty when the brand is to come from a
repository.
When it is done, send the person back to the brand’s Overview,
{APP_URL}/brands/{slug}?git=connected, which says when the first sync has
landed.
A minimal integration
Section titled “A minimal integration”Import on every push to the main branch, from a CI job or a webhook handler.
It assumes the brand’s source is set (PUT .../source, once).
// node sync.mjs brand acme: import the folder at HEAD, uploading new files first.import { createHash } from "node:crypto";import { execSync } from "node:child_process";import { readdir, readFile } from "node:fs/promises";import { basename, join, relative, sep } from "node:path";
const [dir = "brand", slug] = process.argv.slice(2);const { ARTBUCKET_URL: url, ARTBUCKET_KEY: key } = process.env;const MIME = { svg: "image/svg+xml", png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", pdf: "application/pdf", woff2: "font/woff2", ttf: "font/ttf", otf: "font/otf" };
const call = async (method, path, body) => { const r = await fetch(`${url}/api/v1${path}`, { method, headers: { authorization: `Bearer ${key}`, "content-type": "application/json" }, body: body && JSON.stringify(body), }); return { status: r.status, json: await r.json() };};
const paths = (await readdir(dir, { recursive: true, withFileTypes: true })) .filter((e) => e.isFile()) .map((e) => relative(dir, join(e.parentPath, e.name)).split(sep).join("/"));
const files = {};const assets = {};for (const p of paths) { const bytes = await readFile(join(dir, p)); if (p.startsWith("assets/")) assets[p] = createHash("sha256").update(bytes).digest("hex"); else if (/^(brand\.ya?ml|(rules|pages)\/[^/]+\.ya?ml)$/.test(p)) files[p] = bytes.toString("utf8");}const body = { files, assets, commit: execSync("git rev-parse HEAD").toString().trim(), message: execSync("git log -1 --format=%B").toString() };
let r = await call("POST", `/brands/${slug}/files/import`, body);if (r.status === 422 && !r.json.error.detail.errors.length) { for (const p of r.json.error.detail.missing) { const bytes = await readFile(join(dir, p)); const mime = MIME[p.split(".").pop().toLowerCase()] ?? "application/octet-stream"; const ticket = (await call("POST", "/uploads", { filename: basename(p), mime, size: bytes.length })).json; await fetch(ticket.uploadUrl, { method: "PUT", headers: { "content-type": mime }, body: bytes }); await call("POST", "/assets", { token: ticket.token, filename: basename(p), mime }); } r = await call("POST", `/brands/${slug}/files/import`, body);}if (r.status !== 200) { for (const e of r.json.error.detail?.errors ?? [r.json.error]) console.error(`${e.file ?? ""}${e.line ? `:${e.line}` : ""} ${e.message}`); process.exit(1);}console.log(r.json.data.applied ? `version ${r.json.data.version}` : "nothing changed");if (r.json.data.pending) console.log("The brand holds changes the repository lacks: export them back.");The rest of a full integration is the other direction (export when the
source is pending, commit, PUT .../source with synced) and previews on
pull requests, each one call as above.