Admin

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.

Endpoints

EndpointMethodDescriptionParams
/_mosaic_/configGETReturns the JSON from the Mosaic config filen/a
/_mosaic_/content/dumpGETReturns the entire mosaic filesystem as JSONn/a
/_mosaic_/sources/listGETReturns a collection of active sourcesn/a
/_mosaic_/source/addPOSTAdds the sourcedefinition & isPreview
/_mosaic_/source/stopPUTStops the source with the provided namename
/_mosaic_/source/restartPUTRestarts the source with the provided namename
/_mosaic_/tags/listGETReturns the tag names known to the filesystemn/a
/_mosaic_/webhooks/bitbucketPOSTRefreshes git repo sources when Bitbucket reports a pushBitbucket push event

Authentication

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-secret header):

    curl -H "Authorization: Bearer $MOSAIC_ADMIN_SECRET" http://localhost:8080/_mosaic_/sources/list
    curl -u admin:$MOSAIC_ADMIN_SECRET http://localhost:8080/_mosaic_/sources/list

    Requests without a valid secret get 401.

  • Secret not set: the endpoints are open when NODE_ENV=development (the reference site's yarn serve and yarn debug scripts set it) and return 403 otherwise, including when NODE_ENV is unset.

Basic auth sends the secret base64-encoded, not encrypted, so only use it over HTTPS outside local development.

Bitbucket webhooks

/_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.

Workflows

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/jobs starts 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 optional commitMessage override. 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 responds 202 { "jobId": "…" }, or with { "error": "…" } and 400 (invalid request), 401 (wrong secret), 404 (page not found), 409 (new page already exists), 413 (too large) or 503 (secret not configured, or too many workflows running).

  • POST /workflows/defaults inspects 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) contains name, user, route, and optionally targetRoute and isNewPage; 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 workflow prepare hooks must also remain side-effect-free. Invalid requests or defaults return 400, missing pages 404, conflicting new pages 409, wrong secrets 401, oversized requests 413, and an unconfigured secret 503. See Editor commit messages for source settings.

  • GET /workflows/jobs/:jobId/events?user=<sid> streams the job's progress as text/event-stream. user must be the user the job was started for, otherwise the response is 404. Each update is an event: progress with data: { "status", "message" }, and the stream ends with one event: done whose status is SUCCESS (with the workflow's result as message) or ERROR. Events have ids, so a client that reconnects with Last-Event-ID (or ?lastEventId=) only gets the events it missed. The CLI sends a : ping comment 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).

Browser access (CORS)

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.

Environment variables

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.

VariableValuesDefaultPurpose
MOSAIC_ADMIN_SECRETSecret, not blankUnset: admin API open only in developmentProtects the admin endpoints (see Authentication).
MOSAIC_WORKFLOWS_SECRETSecret, not blankUnset: no workflow runsAuthenticates workflow HTTP requests using a bearer token or x-mosaic-workflows-secret header (see Workflows).
MOSAIC_WORKFLOWS_TIMEOUT_MSInteger milliseconds from 1 to 2147483647300000 (5 minutes)Maximum duration of a workflow before its job fails. Validated once when the CLI starts.
MOSAIC_CORS_ORIGINSComma-separated origins, each scheme://host[:port] with no pathUnset: no CORS headersOrigins 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_URLhttp(s) URL. Needs MOSAIC_REVALIDATE_SECRETUnset: the site is not notifiedThe site's revalidate endpoint, e.g. https://docs.example.com/api/revalidate. The CLI calls it whenever a source updates.
MOSAIC_REVALIDATE_SECRETSecret, not blank–Sent to MOSAIC_REVALIDATE_URL; the same value as the site's MOSAIC_REVALIDATE_SECRET.
MOSAIC_SOURCE_BOOT_TIMEOUT_MSWhole number of milliseconds up to 2147483647; 0 waits forever60000How long a source may take to start before mosaic serve gives up on it.
BITBUCKET_API_URLhttp(s) URL–Bitbucket REST API used by the Bitbucket save workflow, e.g. https://bitbucket.example.com/rest/api/1.0.
NODE_ENVdevelopment or anything elseUnsetdevelopment 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.

Binding the content server

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.

Mosaic BETA

Coming soon