Skip to content

API reference

The Mica OS management API is specified by one machine-readable contract: mica-core:crates/mica-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:crates/mica-apid/openapi.json

1. The surface in one paragraph

Section titled “1. The surface in one paragraph”

apid serves plain HTTP on port 8080 by default, and HTTPS on 8443 once it is turned on (PUT /api/v1/web; HTTP then only 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:crates/mica-apid/openapi.json, docs/reference/remote.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/overview.md).

status: shipped — evidence: mica-core:crates/mica-apid/openapi.json, docs/reference/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 (../contributing.md).

status: shipped — evidence: mica-core:crates/mica-apid/openapi.json, docs/reference/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 ../integrate/bus.md.
  • /_ui and custom UI assets are static content, not contract; a custom bundle cannot shadow /api routes.

status: shipped — evidence: docs/integrate/bus.md, mica-core:crates/micad/dist/

5. Trying it

Section titled “5. Trying it”

The API acceptance suite boots the uefi-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/suites/apid-api/run.sh

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