API overview

The engine exposes a JSON HTTP API. Everything below is served by ASP.NET Core controllers under Genie.Engine/Api/**. There is no HTML — the React UI owns all rendering.

Base URL & versioning

All engine routes are versioned under api/v1. The main object surface is:

/api/v1/genie/object/...

Other areas (auth, navbar, search, reports, notifications, wizard, workflow, …) live under their own api/v1/... prefixes — see Other endpoints.

Authentication

Every controller is [Authorize] unless noted. Authenticate with a short-lived JWT bearer token obtained from the auth endpoints, sent as:

Authorization: Bearer <access-token>

Tokens are RS256-signed and refreshable. See Identity for the login/refresh flow and MFA. A X-TimeZone header (IANA zone) is honoured for session-local date handling; see Timezone handling.

The response envelope

Successful responses are wrapped in a SuccessDataResult<T>:

{
  "success": true,
  "data": { /* the T payload */ }
}

Errors are shaped by a global exception handler into a consistent envelope:

{
  "success": false,
  "error": "Human-readable message (for expected 4xx).",
  "traceId": "00-…"
}

The HTTP status is mapped from the thrown exception type: UnauthorizedException → 401, NotFoundException → 404, ArgumentException / RuntimeException / GenieException / InvalidOperationException → 400, otherwise 500. Whether 5xx responses expose the real message is config-driven (Genie:Errors — on in dev, off in prod). See Errors & exception handling.

The structure-vs-data model

The single most important thing to understand about the object API: the client fetches the schema once, then loads data as needed.

Concern	Endpoint	Gated by
Structure (schema, columns, fields, layout)	GET /object/{name}/metadata	authentication only
Grid data (rows + paging)	POST /object/{name}/table	View
Record values (form/view)	POST /object/{name}/form · /view	View / Update
Mutations	POST /object/{submit,delete-row,…}	Create / Update / Delete

The metadata endpoint is SQL-free, static and cacheable, and never returns record values. Data endpoints run the view’s SQL and are gated by the RBAC data-disclosure gate. Any permissions / canSubmit fields in a response are UI hints only — the server re-validates on every operation. See The disclosure gate.

Full object endpoint reference: Object endpoints.