Swagger UI

The widget below mounts Swagger UI against the OpenAPI spec we ship with every release. Click Authorize, paste a bearer token, then Try it out on any endpoint. Nothing leaves your machine — Swagger calls the spec URL directly from your browser.

How the spec is generated

Mnemosyne uses @hono/zod-openapi to derive an OpenAPI 3.1 document from the same Zod schemas the server uses to validate requests. There is one source of truth — the route definitions in packages/server/src/routes/.

// packages/server/src/openapi.ts
app.doc("/v1/openapi.json", {
  openapi: "3.1.0",
  info: { title: "Mnemosyne API", version },
  servers: [{ url: "/v1", description: "current deployment" }],
});
 
app.openAPIRegistry.registerComponent("securitySchemes", "BearerAuth", {
  type: "http",
  scheme: "bearer",
  bearerFormat: "API Key",
});

Authorization

Every endpoint requires a bearer token. After you boot the server and create an API key, click the Authorize button at the top of the Swagger UI above, paste your mns_live_... token, and every “Try it out” call will include it automatically.

# create a workspace + api key in one go
curl -X POST http://localhost:3000/v1/admin/api-keys \
  -H "Authorization: Bearer $MNEMO_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "swagger-tester", "workspace_id": "00000000-0000-0000-0000-000000000000" }'

Raw spec

If you’d rather pull the spec and feed it to your own tooling:

# bundled snapshot from the docs site
curl https://<your-docs-host>/openapi-snapshot.json | jq '.info.version'
 
# or your own running server
curl http://localhost:3000/v1/openapi.json \
  -H "Authorization: Bearer $MNEMO_KEY" \
  | jq '.info.version'

The bundled snapshot is taken from the latest tagged release and updated on every docs deploy, so it may lag the live spec served by your instance. If your server reports a newer version than the snapshot, the Try it out button still works — just paste your URL into the spec bar above.

Compatibility notes

• The spec uses OpenAPI 3.1.0, with oneOf/nullable discriminators on the polymorphic primitives (Fact / Decision / Episode / Entity).
• Swagger UI ≥ 5.x is required. Older versions choke on 3.1’s nullable rewrite.
• Codegen via openapi-typescript, openapi-generator-cli or oapi-codegen all work out of the box.