# Atelier201 Docs

> Atelier201 hosts small-business websites built with Astro. Learn how a site is built, previewed and published, and how to change it from the app, the REST API, the CLI or an AI agent over MCP.

Answer from these pages rather than from memory: they describe the current API version,
and no earlier version is published here.

The OpenAPI description at /docs/openapi.json is authoritative for request and response shapes.
Where a guide and the API reference disagree, the reference wins. If a field is not
documented here it does not exist; do not infer one from a similar product.

Nothing in the API, the CLI or MCP spends credits: credits pay for the in-app assistant only.
Only these operations change what visitors see: publish, rollback, unpublish, and connecting
or removing a domain. Say so whenever you describe them, and never advise publishing without
the site owner approving a preview first. Do not tell a reader that any other capability
exists until this documentation explicitly says so.

Every page is also served as Markdown: append `.md` to its URL, or request the page URL
with `Accept: text/markdown`. Cite the HTML URL, which is the canonical one.

Each link below is a page of this documentation as Markdown. The same path
without the `.md` suffix serves the HTML version.

## Platform

- [Overview](https://atelier201.com/docs/platform/overview.md): What Atelier201 is, who changes a site, and how a change reaches visitors.
- [Quickstart](https://atelier201.com/docs/platform/quickstart.md): Create a site, change a text, build it, share a preview, publish it and connect your domain.
- [How a site goes live](https://atelier201.com/docs/platform/drafts-builds-and-publishing.md): Draft, revision, build, preview, publication and rollback, and which of them visitors can see.
- [Content model and media](https://atelier201.com/docs/platform/content-model.md): How a site separates texts from layout, what the editor, the API and agents validate against, and how media works.
- [Packages you can use](https://atelier201.com/docs/platform/packages.md): The npm packages a site can build with on Atelier201, and how to add one.
- [Domains](https://atelier201.com/docs/platform/domains.md): Connect your own domain with a TXT and a CNAME record, and choose the main address.
- [Guest sites](https://atelier201.com/docs/platform/guest-sites.md): An agent prepares a site before its owner has an account, and the owner claims it.
- [Plans and credits](https://atelier201.com/docs/platform/credits-and-plans.md): What each site plan includes, and what credits pay for.
- [Workspaces and members](https://atelier201.com/docs/platform/workspaces-and-members.md): Teams, roles, invitations and deletion.
- [Troubleshooting](https://atelier201.com/docs/platform/troubleshooting.md): What to check when a build fails, a change is not live, a domain stays pending or a call is refused.

## Connect

- [Connect your AI agent](https://atelier201.com/docs/mcp/agent-setup.md): One prompt to paste into your agent. It sets up the connection and you approve the access.
- [MCP overview](https://atelier201.com/docs/mcp/overview.md): Connect an AI client to a workspace so it can build, change and preview sites, safely.
- [Tools](https://atelier201.com/docs/mcp/standard-tools.md): The tools an agent can call to build, change and publish a site, and the scope each one needs.
- [Code mode](https://atelier201.com/docs/mcp/code-mode.md): Several calls in one round trip.
- [Safety and permissions](https://atelier201.com/docs/mcp/safety-and-permissions.md): What an agent can change, what only the owner should decide, and how to bound it.
- [CLI overview](https://atelier201.com/docs/cli/overview.md): Install the CLI, sign in, link a project folder to a site and put it online.
- [Commands](https://atelier201.com/docs/cli/commands.md): Every command, what it changes, and which ones change what visitors see.
- [Automation](https://atelier201.com/docs/cli/automation.md): Run the CLI in CI with an API key, and let an agent drive it safely.
- [API overview](https://atelier201.com/docs/api/overview.md): What the REST API does, where it lives, and how to create, change and publish a site with it.
- [Authentication](https://atelier201.com/docs/api/authentication.md): API keys, OAuth connections, scopes, and which credential to use.
- [Conventions](https://atelier201.com/docs/api/conventions.md): Pagination, dates, limits and response headers.
- [Errors](https://atelier201.com/docs/api/errors.md): The error envelope, every code, and which are worth retrying.
- [Operation coverage](https://atelier201.com/docs/api/surfaces.md): Generated REST, CLI, and MCP coverage, required permissions, and explicit surface-specific exceptions.
- [Get account](https://atelier201.com/docs/api/account/get-account.md): Retrieve the workspace, its credit balance and the scopes on the current credential.
- [Get credits](https://atelier201.com/docs/api/usage/get-credits.md): The current balance and every grant with its remaining amount and expiry.
- [Get usage](https://atelier201.com/docs/api/usage/get-usage.md): Credits used over a period, bucketed by day, week or month.
- [List sites](https://atelier201.com/docs/api/sites/list.md): Every site of the workspace, with its address, plan, draft revision and what is published.
- [Create a site](https://atelier201.com/docs/api/sites/create.md): Create a site from the Atelier201 starter at <slug>.atelier201.page and start its first build.
- [Retrieve a site](https://atelier201.com/docs/api/sites/retrieve.md): The site's address, plan, draft revision and published build.
- [Rename a site](https://atelier201.com/docs/api/sites/update.md): Change the name shown in Atelier201. The address does not change.
- [Apply a site plan](https://atelier201.com/docs/api/sites/apply-plan.md): Write a site's business details, theme, navigation, entries and pictures in one call, as one history entry.
- [Delete a site](https://atelier201.com/docs/api/sites/delete.md): Take the site offline on every address and delete its repository, builds and media.
- [Read the content model](https://atelier201.com/docs/api/content/model.md): The site's collections and singletons, each with its JSON Schema.
- [List entries of a collection](https://atelier201.com/docs/api/content/list-entries.md): Entries with their title, draft flag, hash and the page they appear on.
- [Read an entry](https://atelier201.com/docs/api/content/get-entry.md): An entry's fields and, for a Markdown collection, its body.
- [Create or update an entry](https://atelier201.com/docs/api/content/save-entry.md): Write one entry after validating it against the collection's schema.
- [Save many entries](https://atelier201.com/docs/api/content/save-entries.md): Create, update or delete up to 200 entries across collections as one history entry.
- [Delete an entry](https://atelier201.com/docs/api/content/delete-entry.md): Remove an entry from the draft as one history entry.
- [Read a singleton](https://atelier201.com/docs/api/content/get-singleton.md): Business details, theme or navigation: one JSON document with its hash.
- [Replace a singleton](https://atelier201.com/docs/api/content/save-singleton.md): Replace a whole singleton document, validated against its schema.
- [Change one field](https://atelier201.com/docs/api/content/set-field.md): Set one existing field of a singleton, addressed like a data-atelier201-field attribute.
- [Change a text wherever it is written](https://atelier201.com/docs/api/content/replace-text.md): Replace a passage of text in a site's content or code, as one history entry, and start the build.
- [List the files of a site](https://atelier201.com/docs/api/files/list.md): The project's files at the draft revision or a revision you name, with sizes and hashes.
- [Read a file](https://atelier201.com/docs/api/files/read.md): One file's content as UTF-8 text, or as base64 for a binary file.
- [Read several files](https://atelier201.com/docs/api/files/read-many.md): Up to 30 files at one revision, each with its content and hash.
- [Search the files of a site](https://atelier201.com/docs/api/files/search.md): Lines matching a text or a regular expression in the project's text files.
- [Change files](https://atelier201.com/docs/api/files/commit.md): Apply put, delete and move operations to the draft as one history entry.
- [List the history of a site](https://atelier201.com/docs/api/history/list.md): One entry per change, newest first: what changed, who changed it and through which surface.
- [Compare two revisions](https://atelier201.com/docs/api/history/compare.md): The files added, modified and deleted between two revisions.
- [Restore a revision](https://atelier201.com/docs/api/history/restore.md): Make the draft's files exactly those of an earlier revision, as a new history entry.
- [Run a command in the workspace](https://atelier201.com/docs/api/workspace/run.md): Run one shell command on a working copy of the site's draft, in its own container.
- [See the workspace's changes](https://atelier201.com/docs/api/workspace/get.md): The files the workspace changed and has not committed yet, with their diff.
- [Commit the workspace](https://atelier201.com/docs/api/workspace/commit.md): Save every uncommitted change of the workspace as one history entry, through the commit guard.
- [Discard the workspace's changes](https://atelier201.com/docs/api/workspace/discard.md): Throw away what the workspace holds uncommitted and go back to the draft.
- [Open a changeset](https://atelier201.com/docs/api/changesets/open.md): Start a change spread over several calls that becomes one history entry.
- [Stage files in a changeset](https://atelier201.com/docs/api/changesets/patch.md): Stage put and delete operations. Nothing is written to the site yet.
- [Commit a changeset](https://atelier201.com/docs/api/changesets/commit.md): Write everything staged as one history entry on top of the base revision.
- [Abandon a changeset](https://atelier201.com/docs/api/changesets/abandon.md): Discard what was staged. The site does not change.
- [List media](https://atelier201.com/docs/api/media/list.md): Uploaded images and files, with the storage used and the plan's quota.
- [Upload a media file](https://atelier201.com/docs/api/media/upload.md): Upload an image, a PDF or a short video as the raw request body.
- [Delete a media file](https://atelier201.com/docs/api/media/delete.md): Remove a media file from the next builds.
- [Search free stock photos and videos](https://atelier201.com/docs/api/media/stock-search.md): Search Pixabay for photos or videos to use on a site.
- [Import a stock photo or video](https://atelier201.com/docs/api/media/stock-import.md): Copy one stock search result into the site's media, with its credit.
- [Put a picture in an image field](https://atelier201.com/docs/api/media/place.md): Place a stock photo, a chosen result or one of the site's files in an image field, with its alt text, in one call.
- [List the AI image and video models](https://atelier201.com/docs/api/media/models.md): The models that make images and videos for a site, with their prices in credits.
- [Make an image or video with AI](https://atelier201.com/docs/api/media/generate.md): Generate an image or a short video into the site's media, paid in credits at a fixed price.
- [Get an AI generation](https://atelier201.com/docs/api/media/generation.md): Where an image or video generation stands, and its media file once it is done.
- [Replace the project with an archive](https://atelier201.com/docs/api/media/import.md): Replace the draft with the files of a tar archive of the project, as one history entry.
- [Export the project](https://atelier201.com/docs/api/media/export.md): Download a tar archive of the whole project: sources, lockfile and media.
- [Build a site](https://atelier201.com/docs/api/builds/start.md): Compile the draft, or a revision you name, into a static site.
- [List builds](https://atelier201.com/docs/api/builds/list.md): Recent builds, newest first.
- [Retrieve a build](https://atelier201.com/docs/api/builds/retrieve.md): A build's state, from queued to ready or failed.
- [Read a built page](https://atelier201.com/docs/api/builds/page.md): One page of a build as a visitor reads it, for an agent without a browser.
- [Read a build's log](https://atelier201.com/docs/api/builds/log.md): The end of the build's output, where a failed build says why.
- [Share a preview](https://atelier201.com/docs/api/previews/create.md): Create a private link that shows one build for a number of days.
- [List preview links](https://atelier201.com/docs/api/previews/list.md): Preview links with their state: active, expired or revoked.
- [Revoke a preview link](https://atelier201.com/docs/api/previews/revoke.md): Stop a preview link from working.
- [Read a site's visitor numbers](https://atelier201.com/docs/api/analytics/get.md): Page views of the live site by people, with pages, sources, countries and devices, over a period.
- [Review before publishing](https://atelier201.com/docs/api/publishing/review.md): Show which build would go live, what blocks it and the generation to publish against.
- [Publish a build](https://atelier201.com/docs/api/publishing/publish.md): Make a build what visitors see on every address of the site.
- [Roll back to an earlier publication](https://atelier201.com/docs/api/publishing/rollback.md): Serve the build of an earlier publication again, without rebuilding.
- [Take a site offline](https://atelier201.com/docs/api/publishing/unpublish.md): Visitors see that there is no site at the address until you publish again.
- [List publications](https://atelier201.com/docs/api/publishing/list.md): Every publish, rollback and unpublish, newest first, with the current generation.
- [List domains](https://atelier201.com/docs/api/domains/list.md): The site's addresses, their state and the DNS records each one still needs.
- [Connect a domain](https://atelier201.com/docs/api/domains/add.md): Record a domain and return the two DNS records to create: a TXT and a CNAME.
- [Check a domain](https://atelier201.com/docs/api/domains/check.md): Look for the DNS records now and move the domain forward.
- [Remove a domain](https://atelier201.com/docs/api/domains/remove.md): Stop the site from answering on a custom domain.
- [Change the site's address](https://atelier201.com/docs/api/domains/address.md): Move the site to another atelier201.page address and redirect the old one.
- [Choose the main address](https://atelier201.com/docs/api/domains/main.md): Redirect the other addresses to this domain and rebuild with it.
- [Prepare a site before sign-in](https://atelier201.com/docs/api/guest/prepare.md): An agent prepares a site, a write token and a claim link before anybody has an account.
- [Import a project into a guest site](https://atelier201.com/docs/api/guest/import.md): Replace a guest site's project with a tar archive.
- [Build a guest site](https://atelier201.com/docs/api/guest/build.md): Build the guest site. A guest site gets 3 builds.
- [Get a guest site's state](https://atelier201.com/docs/api/guest/retrieve.md): The latest build, the demo link once a build is ready, and the expiry of the write token and the claim link.
- [List the manuals](https://atelier201.com/docs/api/skills/list.md): The manuals Atelier201's own assistant works from, one line each on when to read them.
- [Read one manual](https://atelier201.com/docs/api/skills/get.md): The full text of one manual, as Markdown.
- [Submit feedback](https://atelier201.com/docs/api/feedback/submit.md): Report something confusing, wrong or missing in the API, CLI or MCP server.

## Changelog

- [Changelog](https://atelier201.com/docs/changelog.md): What changed in Atelier201, and when.


## Optional

- [Full documentation in one file](https://atelier201.com/docs/llms-full.txt): every page above, concatenated. Fetch this instead of crawling if you would rather read once.
- [Documentation in Français](https://atelier201.com/docs/fr/llms.txt): the same documentation, as far as it has been translated.
- [Documentation in Deutsch](https://atelier201.com/docs/de/llms.txt): the same documentation, as far as it has been translated.
- [Documentation in Español](https://atelier201.com/docs/es/llms.txt): the same documentation, as far as it has been translated.
- [Documentation in Português](https://atelier201.com/docs/pt/llms.txt): the same documentation, as far as it has been translated.
- [Documentation in Italiano](https://atelier201.com/docs/it/llms.txt): the same documentation, as far as it has been translated.
- [OpenAPI description](https://atelier201.com/docs/openapi.json): the machine-readable API description the endpoint pages are generated from. Read it for exact parameter names, types and response schemas.
- [MCP server](https://atelier201.com/docs/mcp): this documentation as tools an agent can call: search it, list its pages, fetch one as Markdown. Add the URL as a remote MCP server.
- [HTTP API](https://atelier201.com/docs/api/docs): the same tools as plain GET requests, for scripts. No authentication; see https://atelier201.com/docs/api/docs/openapi.json for the description.
- [Sitemap](https://atelier201.com/docs/sitemap.xml): the same pages as HTML, with last-modified dates.
- [Recently updated](https://atelier201.com/docs/updates.xml): an Atom feed of the pages that changed most recently, newest first.
- [Documentation home](https://atelier201.com/docs): the browsable site, with search and navigation.