Health endpoints

What /health and /ready of a self-hosted Mica answer, and how to use them in a container platform.

2 min read

A self-hosted Mica answers two public endpoints. Neither one needs a sign-in, and neither one names the repository, the branch or the uptime. The local editor answers both; its /ready has no reasons.

/health

curl -s https://cms.example.com/health

{ "status": "ok" }

/health checks only that the process answers. It does no input or output, so a problem at the Git host does not restart the container. Use it as the liveness check of your platform, for example the Docker HEALTHCHECK (the image has one).

/ready

curl -s https://cms.example.com/ready

{ "status": "ok", "repository": "ok", "reasons": [], "lastSyncAt": "2026-10-14T10:00:00.000Z" }

/ready tells whether editors can work. It answers with HTTP 200 when status is ok or degraded, and with 503 when it is error. Mica keeps a result for 30 seconds, so many requests do not cause many checks.

Key	Values	Meaning
`status`	`ok`, `degraded`, `error`	`ok`: editors can save and publish. `degraded`: editors can save, but something needs a person, such as a Publish that cannot work. `error`: editors cannot work.
`repository`	`ok`, `degraded`, `unavailable`	The state of the clone.
`reasons`	a list of codes	Why somebody should look.
`lastSyncAt`	a time, or `null`	When a sync last reached the Git host.

The reason codes. Each code makes the status degraded, except cloning (error) and conflict (no change):

Code	Meaning	What to do
`cloning`	The first clone runs. `/ready` answers 503 until it is done.	Wait.
`auth_failed`	The Git host refused the token.	Renew the token.
`write_forbidden`	The token cannot push.	Give the token write access, or check branch protection.
`repo_not_found`	The Git host does not know the repository, or the token cannot see it.	Correct `MICA_REPOSITORY_URL`, or the token's access.
`branch_not_found`	The branch does not exist at the Git host.	Create the branch, or correct `MICA_REPOSITORY_BRANCH`.
`network`	The Git host cannot be reached.	Check DNS and outgoing HTTPS from the container. Mica tries again at each sync.
`diverged`	The branch was rewritten during a publication.	Nothing: the next sync follows the branch. See "Troubleshooting" in Self-hosting.
`prefetch_incomplete`	A sync could not fetch all files of the new version, or could not download its Git LFS files. Mica keeps the old version.	Mica tries again at each sync. If it stays, read the log, and check the Git LFS quota and `MICA_REPOSITORY_LFS_URL`. See Large files with Git LFS.
`fast_forward_failed`	A sync could not bring the clone to the new version.	Read the log.
`sync_failing`	Another sync problem.	Read the log, and run `docker compose run --rm mica check`.
`pending_push`	A publication is committed in the clone, but the Git host did not take it yet.	Mica tries again at each sync. Look at the other codes for the cause.
`model_unreadable`	This Mica cannot read the content model of the new version, for example a model with a field kind from a newer `@micacms/astro`. Mica keeps the old version, refuses every save with a message that says why, and Publish waits.	Upgrade Mica, or push a model that it can read.
`read_only`	A sync failed while it changed the files, and Mica could not undo it. Editors cannot save or publish.	Read the log, then restart the container: the start finishes the sync.
`conflict`	An editor's draft and a change at the Git host touch the same entry.	Nothing: the editor chooses a version in the editor.

While a sync fails, editors can still edit and save: their work is in the clone. The exception is model_unreadable: a save would leave out the fields of the newer model, so Mica refuses it. Publish works again when the Git host accepts the push.

Use /ready for a readiness check or for monitoring, not for a restart. See Self-hosting and Command line.

What to alert on

Alert when status is not ok for longer than a few sync intervals. A short network problem is normal.
Alert at once on auth_failed, write_forbidden, read_only and model_unreadable: they do not go away without a person.
Alert when lastSyncAt is older than one hour.
Do not alert on conflict.