There are several admin urls exposed by Mosaic that provide an insight into how the filesystem has been configured and a way to remotely manage sources.
| Endpoint | Method | Description | Params |
|---|---|---|---|
/_mosaic_/config | GET | Returns the JSON from the Mosaic config file | n/a |
/_mosaic_/content/dump | GET | Returns the entire mosaic filesystem as JSON | n/a |
/_mosaic_/sources/list | GET | Returns a collection of active sources | n/a |
/_mosaic_/source/add | POST | Adds the source | definition & isPreview |
/_mosaic_/source/stop | PUT | Stops the source with the provided name | name |
/_mosaic_/source/restart | PUT | Restarts the source with the provided name | name |
/_mosaic_/tags/list | GET | Returns the tag names known to the filesystem | n/a |
/_mosaic_/webhooks/bitbucket | POST | Refreshes git repo sources when Bitbucket reports a push | Bitbucket push event |
Every endpoint except /_mosaic_/tags/list and /_mosaic_/webhooks/bitbucket can reveal or change
server state, so they are protected by MOSAIC_ADMIN_SECRET on the CLI process:
-
Secret set: requests must send it. Opening an endpoint in a browser shows a login prompt; enter any username and the secret as the password. From scripts, send it as a bearer token (or in an
x-mosaic-admin-secretheader):curl -H "Authorization: Bearer $MOSAIC_ADMIN_SECRET" http://localhost:8080/_mosaic_/sources/list curl -u admin:$MOSAIC_ADMIN_SECRET http://localhost:8080/_mosaic_/sources/listRequests without a valid secret get
401. -
Secret not set: the endpoints are open when
NODE_ENV=development(the reference site'syarn serveandyarn debugscripts set it) and return403otherwise, including whenNODE_ENVis unset.
Basic auth sends the secret base64-encoded, not encrypted, so only use it over HTTPS outside local development.
/_mosaic_/webhooks/bitbucket receives Bitbucket Data Center push events, so git repo sources pick up
new commits within seconds instead of at their next scheduled check. Bitbucket can't send the admin
secret, so the endpoint checks the webhook's signature instead: it only exists when
MOSAIC_BITBUCKET_WEBHOOK_SECRET is set, and rejects requests that aren't signed with it (401).
See Refresh on push for the setup.
The editor's save workflow runs over plain HTTP, with progress streamed as Server-Sent Events (SSE).
No WebSocket is needed. The workflows use the server's repository credentials, so every request must
send the CLI's MOSAIC_WORKFLOWS_SECRET as a bearer token (or in an x-mosaic-workflows-secret
header). Without that variable no workflow runs. The site sends the same value from its own
MOSAIC_WORKFLOWS_SECRET (see packages/site/README.md). The placeholder value committed in the
site's .env.development is ignored unless NODE_ENV=development.
-
POST /workflows/jobsstarts a workflow. The JSON body (up to 5 MB) names the workflow and the user, and carries the page's route and content:{ "name": "save", "user": { "sid": "jdoe", "name": "Jane Doe", "email": "jane@example.com" }, "route": "/mosaic/index", "markdown": "# Hello" }It can also carry
frontmatter,targetRoute(rename),isNewPage: true(create) and an optionalcommitMessageoverride. Messages must be nonblank text, at most 8 KiB of UTF-8, without control characters other than LF or CRLF line endings. CRLF becomes LF. Omit the field to use the source's configured default. The CLI responds202 { "jobId": "…" }, or with{ "error": "…" }and400(invalid request),401(wrong secret),404(page not found),409(new page already exists),413(too large) or503(secret not configured, or too many workflows running). -
POST /workflows/defaultsinspects the selected workflow before saving. It uses the same workflow secret, route normalization and source ownership as/workflows/jobs. The site also checks the signed-in editor before calling it. Its JSON body (up to 16 KiB) containsname,user,route, and optionallytargetRouteandisNewPage; it needs no page content:{ "name": "save", "user": { "sid": "jdoe", "name": "Jane Doe", "email": "jane@example.com" }, "route": "/mosaic/index" }The response is either
{ "supportsCommitMessage": true, "commitMessage": "docs: update ..." }or{ "supportsCommitMessage": false }. Only these fields are returned, never source options or credentials. The response is not cached. This lookup does not allocate a job, run a workflow action, clone a repository or write content. Custom workflowpreparehooks must also remain side-effect-free. Invalid requests or defaults return400, missing pages404, conflicting new pages409, wrong secrets401, oversized requests413, and an unconfigured secret503. See Editor commit messages for source settings. -
GET /workflows/jobs/:jobId/events?user=<sid>streams the job's progress astext/event-stream.usermust be the user the job was started for, otherwise the response is404. Each update is anevent: progresswithdata: { "status", "message" }, and the stream ends with oneevent: donewhosestatusisSUCCESS(with the workflow's result asmessage) orERROR. Events have ids, so a client that reconnects withLast-Event-ID(or?lastEventId=) only gets the events it missed. The CLI sends a: pingcomment every 15 seconds to keep proxies from closing the stream.curl -N -H "Authorization: Bearer $MOSAIC_WORKFLOWS_SECRET" \ "http://localhost:8080/workflows/jobs/$JOB_ID/events?user=jdoe"
A job fails if it hasn't finished after MOSAIC_WORKFLOWS_TIMEOUT_MS (validated when the CLI starts,
default 5 minutes). A timeout ends progress reporting, while the workflow can still finish. The same editor
cannot retry the workflow for that page until it stops. Check for the result before retrying.
Jobs are kept in memory, up to 100 jobs with up to 500 events each, and a finished job is
kept for 10 minutes. Jobs are lost when the CLI restarts, so a save in progress at that moment is
reported as failed. If you run several CLI instances, a job's events request must reach the instance
that started it: point MOSAIC_WORKFLOWS_URL at one instance, or use sticky routing in your load
balancer. Proxies in front of the CLI must not buffer text/event-stream responses (the CLI sends
X-Accel-Buffering: no for nginx).
The CLI sends no CORS headers by default, so web pages on other origins can't read its responses. Set
MOSAIC_CORS_ORIGINS to a comma-separated list of origins to allow specific ones.
mosaic serve checks these when it starts, before any source loads. If a value is invalid it exits
with code 1 and lists every problem as NAME: reason. Empty values count as unset.
| Variable | Values | Default | Purpose |
|---|---|---|---|
MOSAIC_ADMIN_SECRET | Secret, not blank | Unset: admin API open only in development | Protects the admin endpoints (see Authentication). |
MOSAIC_WORKFLOWS_SECRET | Secret, not blank | Unset: no workflow runs | Authenticates workflow HTTP requests using a bearer token or x-mosaic-workflows-secret header (see Workflows). |
MOSAIC_WORKFLOWS_TIMEOUT_MS | Integer milliseconds from 1 to 2147483647 | 300000 (5 minutes) | Maximum duration of a workflow before its job fails. Validated once when the CLI starts. |
MOSAIC_CORS_ORIGINS | Comma-separated origins, each scheme://host[:port] with no path | Unset: no CORS headers | Origins allowed to read the CLI from a browser. Write them as the browser sends them, e.g. https://docs.example.com (no trailing slash). |
MOSAIC_REVALIDATE_URL | http(s) URL. Needs MOSAIC_REVALIDATE_SECRET | Unset: the site is not notified | The site's revalidate endpoint, e.g. https://docs.example.com/api/revalidate. The CLI calls it whenever a source updates. |
MOSAIC_REVALIDATE_SECRET | Secret, not blank | – | Sent to MOSAIC_REVALIDATE_URL; the same value as the site's MOSAIC_REVALIDATE_SECRET. |
MOSAIC_SOURCE_BOOT_TIMEOUT_MS | Whole number of milliseconds up to 2147483647; 0 waits forever | 60000 | How long a source may take to start before mosaic serve gives up on it. |
BITBUCKET_API_URL | http(s) URL | – | Bitbucket REST API used by the Bitbucket save workflow, e.g. https://bitbucket.example.com/rest/api/1.0. |
NODE_ENV | development or anything else | Unset | development opens the admin API without a secret and accepts the placeholder MOSAIC_WORKFLOWS_SECRET. Not validated. |
The placeholder MOSAIC_WORKFLOWS_SECRET committed in the site's .env.development is not an error;
outside development it simply counts as unset. For the site's variables, see the
site README.
mosaic serve binds to localhost by default. Use --host 0.0.0.0 when the
content server must accept connections from another container, for example:
mosaic serve --config mosaic.config.mjs --host 0.0.0.0 --port 8080
The host accepts a hostname or IP address, without a scheme or port. Keep the existing workflow/admin secrets and network access controls when exposing the listener beyond the local machine.
Revalidation delivery keeps the latest pending source update until the site acknowledges it. Failed requests retry after one second, doubling up to thirty seconds, and each request has a ten-second deadline. Updates during an in-flight request cause a subsequent notification; closing the CLI server cancels pending requests and retries.