anticode.json: the open file every Anticode project lives in
Every Anticode project can be read and written as one JSON document, anticode.json, described by a public JSON Schema at /schema/project.v1.json. A coding agent or a script can fetch it, change a headline or the section order, and send it back. Nothing in the file is executed, every write is checked against the schema, and a stale write is refused rather than allowed to overwrite newer work.
Why a builder needs an open file
Most site builders keep your project in a format only their editor understands. That's fine until you want a coding agent to fix a typo across ten sections, a script to update prices every Monday, or a person on your team to review a change as a diff. A published website project JSON schema solves that: anything that can read and write JSON can work on the project, and the schema says exactly which keys exist and what values they take, so a tool doesn't have to guess.
What the file holds
The schema follows JSON Schema 2020-12 and its format id is anticode.project/v1. Six keys are required: format, version, name, prompt, kind and direction. Any key the schema doesn't list is refused. The main ones:
- kind
- What the page is, which decides the sections it can have:
landing,store,booking,dashboardorportfolio. - direction
- The design system:
editorial,technical,luxury,playful,brutalist,organicorswiss. - theme
- The mode (auto, light or dark), the action colour, the headline scale, and individual colour tokens as hex or numeric
rgb()values only. - sections
- The text of every element by key (
hero.h1,faq.2.a), the order of sections between header and footer, and layout constraints such as basis, minimum width or sticky. Never pixel positions, so the page still fits every screen. - pages
- Separate pages besides home, such as
["work", "about", "contact"], each published at its own address. An empty list puts everything back on one page. - features, content, data
- Optional sections (pricing, FAQ, booking), the copy the model planned, and bindings that show CMS collections as sections.
- connectors
- The tools the page is wired to. Secrets never appear in the file.
- id, updatedAt
- Read-only. The id must match the address you write to.
Text is always plain text. It's escaped when the page is rendered, so HTML typed into a field shows up literally rather than becoming markup. You never write styles or scripts in the file; Anticode's renderer applies the design system and the checks run on the page that would ship.
Reading and writing it
- Authenticate with a personal access token. The Anticode CLI creates one with a device-code sign-in. Tokens can read and write projects, collections, entries, sites and builds, but not the account, the password or billing.
- Read with
GET /api/projects/{id}/format. The response is the file; itsversionfield and anETagheader both carry the current version. - Edit only what you need, keeping every allowed key.
- Write with
PUTto the same address, sending the whole file with the version you read (or anIf-Matchheader).
| Response | Meaning | What to do |
|---|---|---|
| 200, version n+1 | Saved | Nothing. An open builder picks it up |
| 409 version_conflict | Someone changed the project after you read it | Re-apply your edit to the current copy included in the response, then try again |
| 400 invalid_input | The file doesn't match the schema | Fix the fields listed under issues |
The 409 is the important one. It means an agent can never silently overwrite a change you made in the builder a minute earlier, or the other way round. How the open builder reacts to an accepted write is covered in code-to-canvas sync.
What /AGENTS.md tells coding agents
The project publishes /AGENTS.md, a short brief written for coding agents. It maps common requests to the keys to edit (a headline, the section order, splitting the site into pages, the accent colour) and sets the ground rules:
- Read before you write, and handle the 409 rather than retrying blindly.
- Keep each edit small and say what changed, since the person can undo it from the builder.
- Don't invent keys, and don't put HTML, scripts, secrets or personal data in text fields.
- Publishing is a separate, deliberate step. Don't publish unless you were asked to.
- To undo your own change, restore the version before it from version history instead of writing the old file back by hand. Saves made with a token are labelled as CLI saves there.
Assistants that speak MCP, such as Claude, ChatGPT and Cursor, don't need the raw file: the MCP server offers tools that read and update it for them.
Limits
- Design-engine projects. The schema describes pages laid out by the design engine. An app build is a whole program the model wrote, not a set of keys you can edit one by one.
- Constraints, not freehand layout. You can reorder, resize and pin elements within the rules of the design system, but not place them at exact coordinates or add markup of your own.
- One major version. Breaking changes get a new major version and a new schema address, so a tool written for v1 should check
formatbefore it edits.
Questions people ask
Is anticode.json the same file the CLI writes to my folder?
Not quite. anticode pull writes a small anticode.json that records which project the folder belongs to, plus a spec.json with the build spec. The full project file described here is what the format endpoint returns.
Can an agent change my site's colours?
Yes, through theme.tokens, using hex or numeric rgb values. Anything else, such as a colour name or a CSS expression, is refused by the schema.
Can an edit through the file publish my site?
No. Saving the file updates the project. Publishing is its own request and still runs the security and design gates.
What happens if two tools write at the same moment?
The first write wins and gets a new version. The second carries the old version number, so it's refused with a conflict and the current copy to work from.