Skip to content

API reference

The Mica OS management API is specified by one machine-readable contract: mica-core:apid/openapi.json. It is generated from the same code that serves the routes, and CI holds it equal to what the shipped binary reports — so it cannot drift from the device the way a hand-written endpoint list would. This page deliberately does not duplicate the endpoint inventory; it tells you where the contract is and states the facts the schema itself cannot.

status: shipped — evidence: mica-core:apid/openapi.json

1. The surface in one paragraph

Section titled “1. The surface in one paragraph”

apid serves HTTPS on port 443 (port 80 redirects) and /api is the complete management protocol: versioned settings and state reads, typed writes, queued task records, setup and session lifecycle, UI selection, live network observation, update state and system actions. Errors are JSON envelopes. /healthz is the one operational exception outside /api, and it proves only that the apid process is listening — not that micad or anything else is healthy. The built-in browser UI at /_ui/ is an ordinary client of the same API, with no privileged side channel.

status: shipped — evidence: mica-core:apid/openapi.json, docs/design/remote-management.md

2. Authentication

Section titled “2. Authentication”

Two credential shapes, both defined in the contract:

  • Browser session — password login at the session route creates a signed HttpOnly; Secure cookie plus a per-session CSRF token; session-based mutations must send the token in X-CSRF-Token.
  • Bearer token — for automation; stored tokens authenticate API calls without CSRF. Setup returns the one-time token for API-only clients.

Setup discovery and session state (GET /api/v1/session) are the narrow unauthenticated operations; everything that reads or changes appliance state requires one of the credentials above. Login attempts are rate-limited with persistent backoff and audited (security.md).

status: shipped — evidence: mica-core:apid/openapi.json, docs/design/access.md

3. Versioning

Section titled “3. Versioning”

The API currently uses /api/v1/.... During system development, backward compatibility across builds is not guaranteed unless explicitly requested. Consume the OpenAPI contract from the image you target; CI verifies that the committed document matches the binary. Breaking changes do not require a second version router or an adapter under this development policy (doc-contract.md).

status: shipped — evidence: mica-core:apid/openapi.json, docs/design/api.md

4. What is not a public API

Section titled “4. What is not a public API”
  • The D-Bus interface com.mica.micad1 is the local IPC boundary between apid and micad (and the boot health gate). It is root-only by policy on the device and is not a supported integration surface; integrate over HTTPS.
  • MQTT is the application-data plane, not a management channel: only package-enrolled application services are bridged, and management state and actions are structurally excluded. The grammar and enrollment contract are ../design/bus.md.
  • /_ui and custom UI assets are static content, not contract; a custom bundle cannot shadow /api routes.

status: shipped — evidence: docs/design/bus.md, mica-core:dist/

5. Trying it

Section titled “5. Trying it”

The API acceptance suite boots the x64 image in QEMU and drives every phase of the contract over a real socket — it is also the reference for how the surface behaves end to end, including TLS, redirects and auth gating:

终端窗口
bash micad:tests/apid-api/run.sh

status: shipped — evidence: mica-core:tests/apid-api/run.sh