OpenAPI & REST API Overview

moul provides a comprehensive OpenAPI 3.0 specification embedded directly into the binary and served at runtime.

---

Interactive API Documentation

When your server is running (moul start), you can explore and test all endpoints interactively in your browser:

• Scalar API Reference (Default): http://localhost:8090/docs
• Swagger UI: http://localhost:8090/docs?ui=swagger

Raw OpenAPI Specification Files

Export the spec to Postman, Insomnia, or code generator tools:

• YAML Format: http://localhost:8090/openapi.yml (or /docs/openapi.yml)
• JSON Format: http://localhost:8090/openapi.json (or /docs/openapi.json)

---

Authentication Schemes

The API uses three authentication methods depending on the operation scope:

1. Root Administrator Bearer Token (_rootUsers)

Obtained by logging into the root administrative account (POST /api/moul/_rootUsers/auth-with-password). Grants full access to schema management, settings, worker queues, and file uploads.

• Header: Authorization: Bearer <ROOT_USER_JWT_TOKEN>

2. Administrative Master Key

Master API key configured via MOUL_ADMIN_KEY. Used for direct server-to-server calls, CLI operations, and MCP inspection without requiring an active user session.

• Header: X-Admin-Key: <MOUL_ADMIN_KEY> (or Authorization: Bearer <MOUL_ADMIN_KEY>)
• Keys in the query string (?adminKey=, ?admin_key=, ?api_key=) are rejected with 400 Bad Request.

3. User Bearer Token

Returned upon successful end-user authentication (Password, Email OTP, WebAuthn Passkey, or OAuth2) against custom auth collections. Governed by the collection's row-level access rules.

• Header: Authorization: Bearer <USER_JWT_TOKEN>
• Single-use ticket (SSE EventSource): exchange the token for a 30-second ticket with POST /api/realtime/ticket, then connect with ?ticket=<TICKET>. ?token= is rejected with 400 Bad Request.

---

REST Endpoints Catalog

Schema & Collection Management

• GET /api/moul — List all dynamic collections.
• POST /api/moul — Create a new collection and SQLite table.
• GET /api/moul/:name — Get collection schema, field options, and access rules.
• PATCH /api/moul/:name — Update schema fields and rules.
• DELETE /api/moul/:name — Delete collection and drop table.
• POST /api/moul/:name/truncate — Truncate records while retaining schema.

Dynamic Records CRUD

• GET /api/moul/:name/records — List records (supports page, perPage, filter, sort, expand).
• GET /api/moul/:name/records/:id — View single record by ID.
• POST /api/moul/:name/records — Create a record.
• PATCH /api/moul/:name/records/:id — Update a record.
• DELETE /api/moul/:name/records/:id — Delete a record.

Authentication & User Accounts

• POST /api/moul/:name/auth-with-password — Password login.
• POST /api/moul/:name/otp/request — Request 6-digit email OTP.
• POST /api/moul/:name/auth-with-otp — Verify OTP and sign in.
• POST /api/moul/:name/passkey/login/options — Passkey login challenge.
• POST /api/moul/:name/passkey/login/verify — Passkey assertion verification.
• POST /api/moul/:name/refresh — Refresh active JWT session.
• POST /api/moul/:name/logout — Invalidate JWT session.

Real-Time & Webhooks

• GET /api/moul/:name/subscribe — SSE live record events.
• GET /api/moul/subscribe — Global multi-collection SSE stream.
• GET /api/moul/:name/webhooks — List outbound webhooks.
• POST /api/moul/:name/webhooks — Create outbound webhook.
• POST /api/moul/:name/webhooks/:id/test — Trigger ping test to webhook receiver.

Model Context Protocol (MCP) & System

• POST /api/mcp — Streamable HTTP JSON-RPC MCP server endpoint.
• GET /api/mcp — MCP SSE streaming session.
• GET /api/system/metrics — Live host CPU, RAM, disk, and runtime stats.
• GET /api/analytics/summary — Visitor and request telemetry summary.