Health

Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.

GET /healthz

Liveness

Answers without touching the database. Carries the brand, the version and the uptime.

Access — No authentication.

Responses

200 — Alive.

Field	Type	Required
status	"ok"	yes
brand	string	yes
version	string	yes
uptimeSeconds	number	yes

JSON Schema

{
  "type": "object",
  "properties": {
    "status": { "type": "string", "const": "ok" },
    "brand": { "type": "string", "minLength": 1 },
    "version": { "type": "string" },
    "uptimeSeconds": { "type": "number", "minimum": 0 }
  },
  "required": [ "status", "brand", "version", "uptimeSeconds" ],
  "additionalProperties": false
}

GET /readyz

Readiness

Checks the database and that every migration is applied. 503 with the failing checks otherwise.

Access — No authentication.

Responses

200 — Ready.

Field	Type	Required
status	"ready" | "not_ready"	yes
checks	object[]	yes

JSON Schema

{
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": [ "ready", "not_ready" ] },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "enum": [ "database", "migrations" ] },
          "ok": { "type": "boolean" },
          "detail": { "type": "string" }
        },
        "required": [ "name", "ok" ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "status", "checks" ],
  "additionalProperties": false
}

503 — Not ready.

GET /api/v1/branding

The effective brand of the instance

Public: name, logos, favicon, colours, sign-in text — what a visitor already sees on screen. Read by the sign-in page before any session.

Access — No authentication.

Responses

200 — The brand.

Field	Type	Required
name	string	yes
source	"control_plane" | "environment"	yes
logo	object	yes
favicon	string (uri) | null	yes
colors	object	yes
supportUrl	string (uri) | null	yes
poweredBy	string | null	yes
login	object	yes
instance	object	yes

JSON Schema

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "source": { "type": "string", "enum": [ "control_plane", "environment" ] },
    "logo": {
      "type": "object",
      "properties": {
        "light": {
          "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ]
        },
        "dark": {
          "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ]
        }
      },
      "required": [ "light", "dark" ],
      "additionalProperties": false
    },
    "favicon": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] },
    "colors": {
      "type": "object",
      "properties": {
        "primary": {
          "anyOf": [
            { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
            { "type": "null" }
          ]
        },
        "onPrimary": {
          "anyOf": [
            { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
            { "type": "null" }
          ]
        },
        "accent": {
          "anyOf": [
            { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
            { "type": "null" }
          ]
        },
        "onAccent": {
          "anyOf": [
            { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
            { "type": "null" }
          ]
        }
      },
      "required": [ "primary", "onPrimary", "accent", "onAccent" ],
      "additionalProperties": false
    },
    "supportUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] },
    "poweredBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] },
    "login": {
      "type": "object",
      "properties": {
        "welcome": {
          "anyOf": [
            {
              "type": "object",
              "properties": { "en": { "type": "string" }, "fr": { "type": "string" } },
              "additionalProperties": false
            },
            { "type": "null" }
          ]
        },
        "image": {
          "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ]
        }
      },
      "required": [ "welcome", "image" ],
      "additionalProperties": false
    },
    "instance": {
      "type": "object",
      "properties": { "suspended": { "type": "boolean" } },
      "required": [ "suspended" ],
      "additionalProperties": false
    }
  },
  "required": [
    "name",
    "source",
    "logo",
    "favicon",
    "colors",
    "supportUrl",
    "poweredBy",
    "login",
    "instance"
  ],
  "additionalProperties": false
}

GET /api/v1/openapi.json

This OpenAPI document

The OpenAPI 3.1 description of the instance, generated from the real route schemas. ?lang=fr for French texts.

Access — No authentication.

Parameters

Name	In	Type	Required
lang	query	"en" | "fr"	no

Responses

200 — The document.

Type : object

{
  "type": "object",
  "propertyNames": { "type": "string" },
  "additionalProperties": {}
}

400 — The request does not match its schema.