moxzid HTTP APIalpha
Every moxzid endpoint, with its request, response and authentication.
ACTOR is an actor's manifest name or its hex id. "Token" means the endpoint requires Authorization: Bearer TOKEN when the server has a token. Paths are matched exactly, including the query string, except on website routes.
Calling actors#
| Method and path | Body | Response | Auth |
|---|
POST /call-json/ACTOR/METHOD | JSON array of arguments | JSON array of results | Token |
POST /query-json/ACTOR/METHOD | JSON array of arguments. Update methods are refused | JSON array of results | Token |
POST /call/ACTOR/METHOD | Candid-encoded arguments | Candid-encoded reply | Token |
POST /query/ACTOR/METHOD | Candid-encoded arguments. Composite queries are supported | Candid-encoded reply | Token |
GET /openapi/ACTOR | | OpenAPI 3.1 document for the JSON endpoints | Token |
Request headers:
| Header | Effect |
|---|
x-caller: PRINCIPAL | Sets msg.caller for the message. Default: the anonymous principal. Not authenticated |
JSON errors are returned as {"code": N, "message": "…"}. Add ?lossless=1 to a JSON call for the lossless encoding, which keeps every distinction Candid makes (for example, a nat64 is {"$moxzi": "nat64", "value": "…"}).
Managing actors#
| Method and path | Body | Response | Auth |
|---|
GET /actors | | [{"name": …, "id": …}] | Token |
POST /install/NAME | wasm module | The new actor's hex id. Refused if NAME exists | Token |
POST /upgrade/ACTOR | wasm module, or empty to reload the manifest's file | upgraded | Token |
POST /upgrade/ACTOR?report=1 | as above | JSON report of stable-variable and interface changes | Token |
POST /upgrade/ACTOR?force=true | as above | Skips the stable-compatibility check. The runtime still refuses an upgrade it can't apply | Token |
GET /cycles/ACTOR | | Remaining cycles, as decimal text | Token |
POST /cycles/ACTOR | Cycles to add, as decimal text | New balance | Token |
Observing#
| Method and path | Response | Auth |
|---|
GET /logs/ACTOR | The actor's Debug.print output since the last read. Reading clears it | Token |
GET /events/ACTOR | The same output as a server-sent event stream. Shares the buffer with /logs | Token |
GET /history/ACTOR | JSON array of recent messages (method, caller, argument preview, outcome) | Token |
GET /inspect | JSON snapshot of every actor: id, name, cycles, heap size, message and trap counts, methods, Candid interface | Token |
GET /metrics | Prometheus metrics | Token |
GET / (without --web), GET /inspector | The inspector page | Open |
Health#
| Method and path | Response | Auth |
|---|
GET /health | ok | Open |
GET /health/ready | ready, or 503 and a progress note while starting | Open |
GET /version | Version and build | Open |
Every response has a moxzid-version header.
Websites#
| Method and path | Effect | Auth |
|---|
Any method, /site/ACTOR/PATH | Sent to the actor's http_request (query), then to http_request_update if it returns upgrade = ?true | Open |
Any method, any other path, with --web ACTOR | Same, for ACTOR, at the root | Open |
The request reaches the actor as { method; url; headers; body; certificate_version } with certificate_version = null. The Authorization header isn't forwarded. The actor's status, headers and body are returned as is, except Content-Length, Connection and Transfer-Encoding.
| Website error | Status |
|---|
| No such actor | 404 |
The actor has no http_request method | 502 |
| The reply isn't a valid HTTP response record | 502 |
Other#
| Method and path | Response | Auth |
|---|
GET /mops/closure/ENTRY | Every source file ENTRY depends on, as JSON with base64 contents. Requires --project; paths outside it are refused with 403 | Token |
OPTIONS on any non-website path | 204, for CORS preflight | Open |
Every response includes Access-Control-Allow-Origin: *.
Status codes#
| Status | Meaning |
|---|
200 | Success |
204 | CORS preflight |
400 | Bad request, bad arguments, or the method trapped or rejected |
401 | Missing or wrong token |
402 | The actor is out of cycles |
403 | /mops/closure path outside --project |
404 | No such actor or path |
413 | Body too large: 192 MiB for authenticated control/service routes, 8 MiB for public actor and website routes |
500 | The actor produced no reply |
502 | Website request the actor couldn't answer |
503 | Still starting, or the actor's thread has stopped |