# Artbucket

> Agent-first, headless-by-design asset management: a brand knowledge graph with a blob store attached.

- [Introduction](https://docs.artbucket.io/introduction.md): Asset management built for agents as much as people.
- [Quickstart](https://docs.artbucket.io/quickstart.md): From a fresh clone to a visible thumbnail.
- [How it works](https://docs.artbucket.io/how-it-works.md): One core, three ways in, and the brand as data.
- [Support](https://docs.artbucket.io/support.md): Where to ask, report and follow along.
- [Docker Compose](https://docs.artbucket.io/installation/docker-compose.md): The app, Postgres and storage on one machine.
- [Docker](https://docs.artbucket.io/installation/docker.md): The image on its own, with your Postgres and your storage.
- [Fly](https://docs.artbucket.io/installation/fly.md): The image on Fly Machines, with Fly Postgres and Tigris storage.
- [Coolify](https://docs.artbucket.io/installation/coolify.md): The image as a Coolify application, with Coolify's Postgres and MinIO.
- [Bare VPS](https://docs.artbucket.io/installation/vps.md): Node, a process manager and a reverse proxy, no containers.
- [Upgrading](https://docs.artbucket.io/installation/upgrading.md): Any release upgrades from any earlier one by starting it.
- [Environment](https://docs.artbucket.io/configuration/environment.md): Every variable the server reads, in one table.
- [Storage](https://docs.artbucket.io/configuration/storage.md): Any S3-compatible service, and what Artbucket keeps in it.
- [Authentication](https://docs.artbucket.io/configuration/auth.md): Passwords, single sign-on, who may sign up, and email.
- [Limits and usage](https://docs.artbucket.io/configuration/limits.md): What an organization may use, set by whoever runs the server.
- [Security](https://docs.artbucket.io/configuration/security.md): Rate limits, headers, uploaded files, and telemetry.
- [Assets](https://docs.artbucket.io/guides/assets.md): Uploading, finding, reviewing, versioning, delivering and deleting.
- [The canon](https://docs.artbucket.io/guides/canon.md): The brand as records an agent can query.
- [May I use this?](https://docs.artbucket.io/guides/check.md): POST /api/v1/check, a yes or no on a use, with reasons and what to use instead.
- [Sharing](https://docs.artbucket.io/guides/sharing.md): Links for people without an account, and access for people with one.
- [REST API](https://docs.artbucket.io/developers/api.md): /api/v1, the one way in for the app, scripts and agents.
- [MCP](https://docs.artbucket.io/developers/mcp.md): One URL connects every agent.
- [CLI](https://docs.artbucket.io/developers/cli.md): artbucket, a thin client over the same API.
- [Create a presigned upload](https://docs.artbucket.io/api-reference/create-a-presigned-upload.md): PUT the bytes to `uploadUrl`, then promote with POST /api/v1/assets.
- [Search and browse assets](https://docs.artbucket.io/api-reference/search-and-browse-assets.md): Newest first without `q`. Custom fields filter as `f.{key}={value}` (repeat to OR) and `f.{key}.gte` / `f.{key}.lte` for numbers and dates. A filter on an unknown field is a 422. Of a stack of versions, only the current approved one is listed; GET /api/v1/assets/{id}/versions has the rest.
- [Promote an upload, or ingest from a URL](https://docs.artbucket.io/api-reference/promote-an-upload-or-ingest-from-a-url.md): With `token`: promote a staged upload. With `url`: the server fetches it (public addresses only). Identical bytes dedupe to the existing asset (200). Without the write scope the new asset is `proposed`, and required fields may be left for the person who approves it. C2PA Content Credentials in the f…
- [May this asset be used like this?](https://docs.artbucket.io/api-reference/may-this-asset-be-used-like-this?.md): A verdict, not a lookup: `allowed`, the `reasons` (blocking, or worth knowing), and `suggest`, what to use instead. Refuses an asset that isn't approved, one that was replaced (and names the replacement), one outside its license window, territory or channel, one whose people have no model release ou…
- [Export the brand as design tokens](https://docs.artbucket.io/api-reference/export-the-brand-as-design-tokens.md): Colors, numbers, fonts and the type scale as code. `css`: custom properties on :root, with @font-face for every font file. `scss`, `less`: the same as Sass or Less variables. `tailwind`: a Tailwind 4 @theme; `tailwind3`: theme.extend for tailwind.config.js. `ts`: one typed object. `shadcn`: shadcn/u…
- [Search Google Fonts](https://docs.artbucket.io/api-reference/search-google-fonts.md): The Google Fonts catalog, most popular first; names starting with `q` before names containing it.
- [Import a Google Fonts family](https://docs.artbucket.io/api-reference/import-a-google-fonts-family.md): One asset per style the family has (up to 9 weights, roman and italic), as whole TTF files. Fetched once and served from /a/{id} after, so nobody's browser calls Google. Styles already here dedupe.
- [Fetch one asset](https://docs.artbucket.io/api-reference/fetch-one-asset.md): Scope: `read`.
- [Delete an asset](https://docs.artbucket.io/api-reference/delete-an-asset.md): It leaves the library, its links and its stack at once, reads `state: "deleted"` and answers 410 at /a/{id}. Restorable for 30 days, then purged, with its bytes when nothing else holds them.
- [Edit an asset, or review what was proposed](https://docs.artbucket.io/api-reference/edit-an-asset-or-review-what-was-proposed.md): Also its rights (replaced whole), provenance (`origin`, `parentAssetId`, `generator`, `prompt`), and `supersededBy`: the asset that replaces it, which /api/v1/check then names. `status` moves it through its lifecycle: draft, proposed (in review), active (approved), archived, rejected. Submitting or…
- [Restore a deleted asset](https://docs.artbucket.io/api-reference/restore-a-deleted-asset.md): Within 30 days of its deletion. It comes back as it was, but not as its stack's current version.
- [Its versions](https://docs.artbucket.io/api-reference/its-versions.md): Newest first. `current` marks the one the library shows and share links serve. An asset with one version lists itself.
- [Make a version current](https://docs.artbucket.io/api-reference/make-a-version-current.md): Roll back, or forward. It must be approved and unexpired; the others are superseded by it.
- [Suggest tags](https://docs.artbucket.io/api-reference/suggest-tags.md): They wait in `proposedTags` for someone with the write scope. Tags it already has are dropped.
- [What an asset is and may be used for](https://docs.artbucket.io/api-reference/what-an-asset-is-and-may-be-used-for.md): Title, credit, tags, effective field values, rights, provenance, what supersedes it, its URLs, the transforms it allows and ready-made rendition URLs. Whether a particular use is allowed: POST /api/v1/check.
- [List collections](https://docs.artbucket.io/api-reference/list-collections.md): Scope: `read`.
- [Create a collection](https://docs.artbucket.io/api-reference/create-a-collection.md): Scope: `write`.
- [Fetch a collection](https://docs.artbucket.io/api-reference/fetch-a-collection.md): Scope: `read`.
- [Delete a collection; its assets stay](https://docs.artbucket.io/api-reference/delete-a-collection;-its-assets-stay.md): Scope: `write`.
- [Edit a collection](https://docs.artbucket.io/api-reference/edit-a-collection.md): Scope: `write`.
- [Add and remove members](https://docs.artbucket.io/api-reference/add-and-remove-members.md): Scope: `write`.
- [The custom field schema](https://docs.artbucket.io/api-reference/the-custom-field-schema.md): Scope: `read`.
- [Define a field](https://docs.artbucket.io/api-reference/define-a-field.md): Scope: `write`.
- [Delete a field and every value stored under it](https://docs.artbucket.io/api-reference/delete-a-field-and-every-value-stored-under-it.md): Scope: `write`.
- [Edit a field](https://docs.artbucket.io/api-reference/edit-a-field.md): Scope: `write`.
- [Who did what](https://docs.artbucket.io/api-reference/who-did-what.md): Newest first: assets added, suggested, approved, rejected and deleted, tags suggested, and brand rule changes (one per brand version). An actor is an API key's name, or `web` for the app.
- [Saved searches](https://docs.artbucket.io/api-reference/saved-searches.md): Scope: `read`.
- [Save a search](https://docs.artbucket.io/api-reference/save-a-search.md): Scope: `write`.
- [Forget a saved search](https://docs.artbucket.io/api-reference/forget-a-saved-search.md): Scope: `write`.
- [Brand rules](https://docs.artbucket.io/api-reference/brand-rules.md): The canon, as structured records: `color.primary`, `logo.neverDo`, `type.scale`. Without `context`, every rule and its context variants. With one, one rule per key: the context's own where it has one, the default otherwise.
- [Add a brand rule](https://docs.artbucket.io/api-reference/add-a-brand-rule.md): One per key and context; 409 when it exists. `value` must match `type`. `?brand=` picks the brand; the default otherwise. Every change to rules lands in the brand's history.
- [Reorder brand rules](https://docs.artbucket.io/api-reference/reorder-brand-rules.md): Rules appear in this order within their section. A key's context versions move with it.
- [Delete a brand rule](https://docs.artbucket.io/api-reference/delete-a-brand-rule.md): Scope: `write`.
- [Edit a brand rule](https://docs.artbucket.io/api-reference/edit-a-brand-rule.md): A new `key` renames the rule and its context versions. The type never changes: delete and recreate.
- [Brands, the default first](https://docs.artbucket.io/api-reference/brands-the-default-first.md): Scope: `read`.
- [Create a brand](https://docs.artbucket.io/api-reference/create-a-brand.md): Empty, or `from` another brand's current rules. Its history starts at version 1.
- [Fetch a brand](https://docs.artbucket.io/api-reference/fetch-a-brand.md): Scope: `read`.
- [Delete a brand with its rules and history](https://docs.artbucket.io/api-reference/delete-a-brand-with-its-rules-and-history.md): Not the default: make another brand the default first.
- [Rename a brand, or make it the default](https://docs.artbucket.io/api-reference/rename-a-brand-or-make-it-the-default.md): Scope: `write`.
- [A brand's history](https://docs.artbucket.io/api-reference/a-brands-history.md): Newest first. Every change is recorded; changes by the same actor within ten minutes extend one version, as in a shared doc, unless it has been named.
- [One version, and what changed](https://docs.artbucket.io/api-reference/one-version-and-what-changed.md): The rules as they were. `diff` goes from the version before (or `against`) to this one; with `against=current`, from this one to now.
- [Name a version](https://docs.artbucket.io/api-reference/name-a-version.md): A named version is a checkpoint: later edits start a new version instead of extending it.
- [Restore a version](https://docs.artbucket.io/api-reference/restore-a-version.md): Replaces the brand's rules with the version's. The restore is a new version, so it can be undone.
- [Who is calling](https://docs.artbucket.io/api-reference/who-is-calling.md): The person or key, the workspace this request acts in (a key's own; for a person, the one in the `ab_workspace` cookie if they can open it), the scope there and on its organization, every workspace they can switch to, and how one signs in here.
- [Your organizations](https://docs.artbucket.io/api-reference/your-organizations.md): Any caller; the scope needed is checked on what it acts on.
- [Make an organization](https://docs.artbucket.io/api-reference/make-an-organization.md): With a first workspace, Library. Needs a signed-in person, who becomes its admin.
- [Delete the organization](https://docs.artbucket.io/api-reference/delete-the-organization.md): With its workspaces and everything in them, its grants, invitations and settings; its files go with the next sweep. Admin on the organization. Not the server's only one.
- [Rename the organization](https://docs.artbucket.io/api-reference/rename-the-organization.md): Admin on the organization.
- [Usage and limits](https://docs.artbucket.io/api-reference/usage-and-limits.md): What the organization uses, the limits its server's operator set, and 30 days of delivery traffic. Admin on the organization.
- [Workspaces in this organization](https://docs.artbucket.io/api-reference/workspaces-in-this-organization.md): Those you can open, with your scope on each; null where a grant inside it is all you have.
- [Make a workspace](https://docs.artbucket.io/api-reference/make-a-workspace.md): A library of its own in the current organization, with a default brand. Admin on the organization.
- [Delete a workspace](https://docs.artbucket.io/api-reference/delete-a-workspace.md): With its assets, collections, fields, brands, keys and links, at once; its files go with the next sweep, when no other workspace holds the same bytes. Admin on the organization. Not its last workspace.
- [Rename a workspace](https://docs.artbucket.io/api-reference/rename-a-workspace.md): Admin there.
- [People and their access](https://docs.artbucket.io/api-reference/people-and-their-access.md): Everyone with a grant in the organization, with the grants you may see, and invitations still waiting. An organization admin sees every workspace's grants; a workspace admin, the organization's and their workspace's.
- [Give a member access, or change it](https://docs.artbucket.io/api-reference/give-a-member-access-or-change-it.md): A scope on the organization (its admins only), a workspace, a collection or one asset (admins of the workspace). Grants add up and reach down. Only for people already in the organization; invite anyone else.
- [Take access away](https://docs.artbucket.io/api-reference/take-access-away.md): An organization keeps at least one admin.
- [Invite someone](https://docs.artbucket.io/api-reference/invite-someone.md): A grant waiting for whoever holds the link: they make an account or sign in, and have it. The `url` is in this response only. It works once, for seven days. Same rules as giving a grant.
- [Send an invitation again](https://docs.artbucket.io/api-reference/send-an-invitation-again.md): A new link and a new week; the old link stops working. Emailed when the organization can send email. The `url` is in this response only.
- [Withdraw an invitation](https://docs.artbucket.io/api-reference/withdraw-an-invitation.md): Any caller; the scope needed is checked on what it acts on.
- [What an invitation offers](https://docs.artbucket.io/api-reference/what-an-invitation-offers.md): No key needed.
- [Accept an invitation](https://docs.artbucket.io/api-reference/accept-an-invitation.md): As the signed-in person.
- [Share links](https://docs.artbucket.io/api-reference/share-links.md): The workspace's, on what you may share.
- [Make a share link](https://docs.artbucket.io/api-reference/make-a-share-link.md): For people without an account. `view`: a collection's approved assets, or one asset, to see and download. `upload`: files sent in land `proposed`, in the collection (or the workspace), for review. Either can expire and ask for a password. Needs write on what it shares.
- [Email a share link](https://docs.artbucket.io/api-reference/email-a-share-link.md): To up to 20 people, through the organization's email. A 422 says why when none could be sent.
- [Revoke a share link](https://docs.artbucket.io/api-reference/revoke-a-share-link.md): It stops working at once.
- [Open a share link](https://docs.artbucket.io/api-reference/open-a-share-link.md): What the link is, and for a view link its approved assets with download URLs. A password goes in `X-Share-Password`: 401 `password` without it or with a wrong one, 410 `gone` once expired.
- [Start an upload through a link](https://docs.artbucket.io/api-reference/start-an-upload-through-a-link.md): Like POST /api/v1/uploads: PUT the bytes to `uploadUrl`, then hand them in.
- [Hand in an upload through a link](https://docs.artbucket.io/api-reference/hand-in-an-upload-through-a-link.md): It lands proposed, in the link's collection. The guest learns it arrived, nothing about the library.
- [The audit log](https://docs.artbucket.io/api-reference/the-audit-log.md): Who changed who may do what, newest first: sign-ins, members and grants, invitations, keys, share links, workspaces. An organization admin reads the organization's (with its members' sign-ins); a workspace admin, the workspace's.
- [Settings](https://docs.artbucket.io/api-reference/settings.md): Every setting that can be set in `context` (organization or workspace), as it applies there, and its `source`: set here, inherited from the organization, the server's environment (config files), or the default. Secret properties come back null, with whether each is set in `secrets`. Admin on that pl…
- [Reset a setting](https://docs.artbucket.io/api-reference/reset-a-setting.md): Forget this place's own value, so the one above it (or the server's) applies again.
- [Change a setting](https://docs.artbucket.io/api-reference/change-a-setting.md): Starts from what applies now. A blank secret keeps the stored one; null clears it. Admin on that place.
- [Send a test email](https://docs.artbucket.io/api-reference/send-a-test-email.md): Through the organization's email settings, to you or `to`. A 422 carries the provider's reason. Organization admin.
- [Connected agents](https://docs.artbucket.io/api-reference/connected-agents.md): API keys, without secrets, with when each last called and what it left in Review: every key in the workspace for an admin, the agents you connected for anyone else.
- [Mint an API key](https://docs.artbucket.io/api-reference/mint-an-api-key.md): Scope: `admin`.
- [Revoke an API key](https://docs.artbucket.io/api-reference/revoke-an-api-key.md): Any key, for an admin; the agents you connected, for anyone.
- [OAuth authorization server metadata](https://docs.artbucket.io/api-reference/oauth-authorization-server-metadata.md): RFC 8414. Also at /.well-known/oauth-authorization-server.
- [OAuth protected resource metadata](https://docs.artbucket.io/api-reference/oauth-protected-resource-metadata.md): RFC 9728, for /api/v1/mcp. Also at /.well-known/oauth-protected-resource; a 401 names it in `WWW-Authenticate`.
- [Register an OAuth client](https://docs.artbucket.io/api-reference/register-an-oauth-client.md): RFC 7591 dynamic registration. Public clients: no secret, PKCE (S256) instead. Redirects: https, http to loopback, or an app scheme.
- [Trade a code for a token](https://docs.artbucket.io/api-reference/trade-a-code-for-a-token.md): Form-encoded (or JSON). `authorization_code` with `code_verifier`, or the device code grant. The token is an API key bound to the person who consented: at most the scope they picked, never more than they can do. It lasts until revoked.
- [Start the device flow](https://docs.artbucket.io/api-reference/start-the-device-flow.md): RFC 8628, with a registered `client_id`. A person approves `user_code` at `verification_uri`; poll the token endpoint meanwhile.
- [What a device code asks for](https://docs.artbucket.io/api-reference/what-a-device-code-asks-for.md): Signed in: the client, and the workspaces and scopes you can give it.
- [Approve or turn down a device code](https://docs.artbucket.io/api-reference/approve-or-turn-down-a-device-code.md): Signed in.
- [What an authorization request asks for](https://docs.artbucket.io/api-reference/what-an-authorization-request-asks-for.md): Signed in, with the client's query (response_type=code, client_id, redirect_uri, code_challenge, S256, state). For the consent screen.
- [Decide an authorization request](https://docs.artbucket.io/api-reference/decide-an-authorization-request.md): Signed in: the decision and the `request` query it answers. Returns the URL to send the browser to, with a code or `error=access_denied`.
- [No server-initiated stream](https://docs.artbucket.io/api-reference/no-server-initiated-stream.md)
- [MCP (Streamable HTTP, stateless)](https://docs.artbucket.io/api-reference/mcp-streamable-http-stateless.md): JSON-RPC 2.0 for Model Context Protocol clients. Tools: search_assets, describe_asset, rendition_url, check_use, ingest_asset, import_google_font, propose_tags, my_proposals, brand_rules. Each tool checks its own scope. Resources: artbucket://brand/rules and artbucket://brand/rules/{context}.
- [This document](https://docs.artbucket.io/api-reference/this-document.md)
- [The original](https://docs.artbucket.io/api-reference/the-original.md): Bytes, exactly as uploaded, Content Credentials included; `?download` writes current metadata in, except into a file with Content Credentials, which it leaves as signed. What the asset is: GET /api/v1/assets/{id}/description. Public while approved, unexpired and out of embargo, and cached for an hou…
- [A rendition, generated once and cached](https://docs.artbucket.io/api-reference/a-rendition-generated-once-and-cached.md)

## OpenAPI Specs

- [openapi](/openapi.json)