HTTP API
The routes and server-sent events the backend serves for mockups, the version history it records, and the browser events the viewer exchanges with the assistant.
The backend serves each mockup through routes under /api/mockup. The viewer uses them, and so can your own tools. The MCP mockup tools read the files directly instead.
Access
The routes exist only in development, as under ajs project dev or ajs project run. Neither docsPreview nor DMS_DOCS_PREVIEW=1 turns them on.
Only the platform owner can call them. A request without a session answers 401, and any other signed-in user gets 403. A role cannot grant access.
A name, page id, fixture key or annotation id that does not match its pattern answers 404. A mockup name uses lowercase letters, digits and dashes, up to 64 characters. schema and example are reserved.
Mockups
| Route | Answer |
|---|---|
GET /api/mockup | { results, total }, one row per mockup, most recently changed first. A row is { name, title?, pages, openComments, source?, updatedAt, status }, plus builtAt and builtPages when status is built. |
GET /api/mockup/:name | The compiled MockupState. See Compiled state. |
PATCH /api/mockup/:name | Body { name?, title? }, at least one. Renames the folder and sets the spec's title. Answers { name }. |
POST /api/mockup/:name/duplicate | Body { name? }. Copies the mockup as a draft with no comments. Without name, the copy is <name>-copy, then <name>-copy-2. Answers { name }. |
DELETE /api/mockup/:name | Deletes the folder and its comments. The pages it built stay. Answers { name }. |
GET /api/mockup/:name/spec | { spec, digest, writtenBy? }: spec.json as written, and a digest of its text. writtenBy is { name }, the name of the signed-in user, when the last write of the file was a PUT that named a viewer, even one whose stream had just closed. |
PUT /api/mockup/:name/spec | Body { spec, digest?, viewer? }. Checks the spec as mockup_write_spec does. Answers { ok: true, digest, warnings } or { ok: false, errors, warnings }. A block another viewer holds refuses the write: see Several viewers. |
POST /api/mockup/from-page | Body { path } or { pageRef }, with replace? and digest?. Converts a page into a mockup. See Live page mockups. |
GET /api/mockup/schema | The JSON Schema of the spec, over the block types registered now. |
GET /api/mockup/schema/blocks | { blocks }, every registered block type as ListBlockTypes describes it. |
GET /api/mockup/example | The spec of the shipped example mockup, to copy as a start. |
warnings lists the fixtures a block cannot read. A warning never refuses a write.
| Status | When |
|---|---|
400 | A name that is not valid or is reserved. A body that is not an object. A replace from a page without digest. |
404 | spec.json is missing, or the builder does not know the page. A lock renewal from a viewer that holds no lock. |
403 | A lock route that names a viewer with no event stream open on the mockup, or one another user opened. |
409 | Another mockup has the new name, or digest no longer matches the file. The answer holds the current digest. |
Fixtures
| Route | Answer |
|---|---|
GET /api/mockup/:name/pages/:page/fixtures/:key | The fixture value. |
GET /api/mockup/:name/pages/:page/fixtures/:key/rows | { results, total } over an array of row objects. 404 when the fixture is not one. |
GET /api/mockup/:name/pages/:page/fixtures/:key/rows/list | The same as /rows. A kanban board reads its columns here. |
GET /api/mockup/:name/pages/:page/fixtures/:key/record | ?id=<id>, with &key=<field> optional. The row whose <field>, else _id, else id, is <id>. |
GET /api/mockup/:name/pages/:page/fixtures/:key/rows/get | The same row as /record, where a data controller's get route stands. A table's details view reads it. |
PUT /api/mockup/:name/pages/:page/fixtures/:key/rows | Where a table's add and edit forms save. Answers the row it was sent, merged into the row that ?id= names, and keeps nothing. |
PUT /api/mockup/:name/pages/:page/fixtures/:key/rows/archive and /rows/restore | Where a table in archive mode archives and restores rows. Answers {} and keeps nothing. |
Rows route
The rows route reads these query parameters:
| Parameter | Meaning |
|---|---|
offset | The first row to answer. Defaults to 0. |
limit | How many rows to answer. Every row from offset when absent. |
search | Keeps the rows where a string, number or boolean value contains it, ignoring case. |
sortKey | The field to sort on. Numbers sort by value, then text in reading order, ignoring case and accents. Rows without the field come last. |
sortDirection | asc or desc. Defaults to asc. |
showArchived | true or false, for a table in archive mode. |
filter_<field> | <mode>:<value>. Keeps the rows whose <field> passes. The key repeats once per filter, and a row must pass them all. |
The filter modes are those of a data controller:
| Mode | Value |
|---|---|
is, is_not | A comma-separated list: any of them, or none of them. |
greater_than, less_than, greater_than_or_equal_to, less_than_or_equal_to | A number, or an ISO 8601 date. |
is_between | <low>,<high>. |
is_empty, is_not_empty | None. |
include, exclude | A value in a list field. |
contains, not_contains | Text, ignoring case. |
array_contains_string | A string. |
A mode not listed keeps every row.
Events
GET /api/mockup/:name/events opens a server-sent event stream for one mockup. 404 when spec.json is missing. ?viewer=<uuid> names the browser session that opens it: see Several viewers.
| Event | When | data |
|---|---|---|
state | On connect, then after each change of spec.json. | The MockupState. |
annotations | After each change of annotations.json or of spec.json. | { annotations } |
presence | On connect, then after each change of who is on the mockup, of the blocks held, or of where a held block is. | { viewers, locks }: each viewer is { name, mine }, each lock { name, mine, page, path }, where path is the spec pointer of the held block now. mine is true for the viewer and the lock of the stream's own ?viewer=: a viewer id is never sent to another viewer, as it is the key to that viewer's locks and writes. |
When spec.json is deleted, the next state keeps the last pages and has one issue that says the file is missing. Deleting the whole mockups/ folder stops the updates. Reload the viewer once the folder is back.
Several viewers
Every viewer of a mockup sees the changes the others write, as state events, and sees who is on it and which block each is editing. A viewer is a browser session: it makes a UUID and passes it as ?viewer= on the stream. It is on the mockup while one of its streams is open, under the name of its signed-in user, and a stream without ?viewer= only follows. Access is unchanged: every viewer is a platform owner.
A viewer holds at most one block:
| Route | Does |
|---|---|
PUT /api/mockup/:name/locks | Body { viewer, path, digest }, where path is the spec pointer of the block and digest the digest of the spec the client read it in: 400 without it. Takes the lock, or renews the one the viewer holds there, and frees the one it held. A block with no id gets one, as a comment pinned on it would give it. Answers { ok: true, id }, the id the block has in the spec, which a client finds it by after a write moves it. 409 with holder, the name of whoever holds that block, one it sits in or one inside it. 409 with the current digest when spec.json changed since the client read it, as the pointer may then name another block: nothing is granted, and the client takes the lock again once it has read the new file. 403 for a viewer with no stream open. |
PUT /api/mockup/:name/locks | Body { viewer }, with no path. Renews the lock the viewer holds wherever a write moved its block, and answers { ok: true, id } with the same id. 404 when the viewer holds no lock, which it ran out or was freed. |
DELETE /api/mockup/:name/locks?viewer=<uuid> | Frees the lock the viewer holds. |
A lock frees when its viewer frees it, which the viewer does on leaving the block once its edit is written, when the viewer's last stream closes, and 2 minutes after the lock was last taken or renewed. The viewer renews it as it edits, naming no block. A lock follows its block when another write moves it, and frees when the block is gone.
A PUT /spec that removes a block another viewer holds, or changes anything inside it, answers { ok: false, errors }, an error naming the block and the holder, and leaves the file as it was. A write that names no viewer, or one that has no stream open on the mockup, is refused for every block held. A POST /from-page with replace is refused the same way, with 409 and the same errors, when the page it converts over holds a block another viewer has. A history restore is refused the same way, with { ok: false, errors }. mockup_write_spec, mockup_patch_spec and mockup_from_page with replace are refused the same way while the dev engine runs: their answer holds the same error, and the file stays as it was.
Created mockups
GET /api/mockup/events/created opens a stream for the whole project. It sends a created event, with { name, title? }, for each mockup that did not exist before. Edits, renames and the mockups that existed when the stream opened send nothing. A mockup deleted and created again with the same name is sent again.
Version history
Every write of spec.json adds a version, so a mockup can go back. The versions live in .antelope/mockup-history/<name>/, outside mockups/. Add .antelope to .gitignore if your project does not ignore it yet. A mockup keeps its last 50 versions.
| Route | Answer |
|---|---|
GET /api/mockup/:name/history | { versions }, newest first. Each is { seq, at, by, summary, comments }, where comments counts the comments pinned on that version. |
GET /api/mockup/:name/history/:seq | { seq, at, by, summary, spec, state, annotations }: that version's spec, its compiled state, and the comments pinned on it. 404 for a number with no version. |
POST /api/mockup/:name/history/:seq/restore | Writes that version as the current spec, as PUT /spec does. A version that no longer passes the checks cannot be restored, and the answer lists the issues. |
GET /api/mockup/:name/history/:seq/pages/:page/fixtures/:key | The fixture of that version, with /rows and /rows/list variants. |
A version is { seq, at, by, summary, group?, spec }:
| Field | Meaning |
|---|---|
seq | Counts up from 1. A number is never reused. |
by | ai for mockup_write_spec and mockup_patch_spec. you for the viewer and for a restore. disk for a valid change made outside both, such as an edit in your editor or a git checkout. |
summary | Written by the DMS at page level, such as Added Orders, Customers · Changed Overview. The first version reads Created with 3 pages. A write tool's optional summary, up to 200 characters, replaces it. |
group | The write group of an AI write. |
Consecutive writes by one author fold into one version when each comes within 2 minutes of the last. A build written page by page, or a burst of edits in the viewer, is then one version. An AI write that carries a write group folds with the writes of the same group instead, however far apart. The DMS AI assistant gives each of its replies a group, so each reply is one version. The group is the writeGroup argument of the write tools, 1 to 128 letters, digits, _ and -. The host sets it, and the model leaves it out. A restore never folds.
A refused write leaves no version. Neither does a write that equals the newest version, nor stamping a block id for a comment.
Browser events
The viewer hands requests to the agent through window events. The names and types are exported by the mockupAssistant utilities of the dms-ui layer, which the dashboard auto-imports.
dms:assistant-prompt (MOCKUP_ASSISTANT_PROMPT_EVENT) is a cancelable event whose detail is a MockupAssistantPrompt. The DMS AI assistant claims it with preventDefault(). When nobody claims it, the viewer shows the request to copy.
source | Sent by | prompt | Other fields |
|---|---|---|---|
custom-zone | Ask the AI to change it on a sketch | A full sentence | block |
build | Build it | The mockup's name | title, and target: { pageRef } on a converted page |
resolve-comments | Resolve with AI | The mockup's name | title, and page unless sent from the Overview |
new-mockup | New mockup on the Mockups page | The start of a request, such as "Draft a mockup of " | None |
title is sent only when it differs from the name. The assistant reports its runs with two more events:
| Event | Sent by | detail |
|---|---|---|
dms:assistant-run (MOCKUP_ASSISTANT_RUN_EVENT) | The assistant, when a build or resolve run starts and when it ends. | MockupAssistantRun: { mockup, source, running } |
dms:assistant-run-query (MOCKUP_ASSISTANT_RUN_QUERY_EVENT) | The viewer, once, when it opens. | None. The assistant answers with a dms:assistant-run for each run in progress. |