Schema endpoint

The schema endpoint returns the deployed schema of a project: its entities with their UI metadata, scopes, spaces, Studio title and sidebar menu groups. It is what the Studio fetches after login to render a project, and it is available to your own applications under the same session rules.

GET https://PROJECT_ID.api.flexkit.io/schema

Replace PROJECT_ID with the ID from Dashboard Settings → General. Behind the framework handler the same resource is served at your app’s /api/flexkit/PROJECT_ID/schema, which is the path the Studio uses so that the session cookie stays same-origin.

Authentication

The request needs a signed-in session of a project member; the framework handler forwards it. A request without a recognised session receives 401, and a subject that is not a signed-in member of that project, including every API token, receives 403. Tokens and agents read the schema through GraphQL introspection or the MCP search_schema tool instead.

Browser requests from another origin follow the project’s CORS origins; the endpoint answers OPTIONS preflights with the same policy.

Response

{
  "projectId": "your-project-id",
  "title": "Atlas Commerce",
  "schema": [
    {
      "name": "product",
      "plural": "products",
      "display": "name",
      "menu": { "label": "Products", "group": "catalog", "icon": "Tag" },
      "groups": [{ "name": "general", "label": "General", "icon": "Info" }],
      "attributes": [
        {
          "name": "name",
          "label": "Name",
          "scope": "local",
          "dataType": "string",
          "inputType": "text",
          "searchable": true,
          "isRequired": true,
          "validation": { "type": "string", "minLength": 1 }
        },
        {
          "name": "stock",
          "label": "Stock",
          "scope": "global",
          "dataType": "int",
          "inputType": "number",
          "validation": { "type": "integer", "minimum": 0 }
        }
      ]
    }
  ],
  "scopes": [{ "name": "default", "label": "Default", "isDefault": true }],
  "spaces": [{ "code": "mkt", "label": "Marketing" }],
  "menuGroups": [{ "name": "catalog", "title": "Catalog" }],
  "schemaHash": "9f2c…"
}

Field	Contents
`projectId`	The project the schema belongs to.
`title`	The Studio title from `flexkit.config.ts`, falling back to the project name.
`schema`	The deployed entity list. Each attribute carries its `validation` as JSON Schema (compiled from the Zod function at deploy); `menu` and `groups` carry lucide icon names, not components.
`scopes`	The configured scopes, with the default marked.
`spaces`	The project’s spaces, sorted by label.
`menuGroups`	The sidebar groups in display order.
`schemaHash`	The hash of the deployed schema; it changes with every successful `flexkit deploy`.

The reserved _asset and _tag entities are not included; the Studio adds them itself. A project that has never been deployed returns an empty schema with a null schemaHash, which is what the Studio turns into its No deployed schema screen.

The shape mirrors the attribute reference and entity reference, with validation as JSON Schema (see Validation), minus everything that is not data: callbacks and icon components do not survive deployment.

Caching

The response carries ETag set to the schema hash and Cache-Control: private, no-store. Send the previous ETag in If-None-Match to receive 304 Not Modified without a body when nothing was deployed in between. Do not cache the body in a shared cache; it is specific to the member who requested it.

curl -i "https://${FLEXKIT_PROJECT_ID}.api.flexkit.io/schema" \
  -H "Cookie: ${FLEXKIT_SESSION_COOKIE}" \
  -H 'If-None-Match: "9f2c…"'

When to use it

Need	Use
Render forms, menus or validation for a member in a custom interface	This endpoint, with the member’s session; or the `useConfig` hook beneath `FlexkitStudio` which reads it.
Build typed queries and mutations from a server with a token	GraphQL introspection of the generated API.
Let an agent or AI client discover entities, labels, options and rules	MCP `search_schema`, which lists the same labels, flags, options and validation.
Detect that a deployment changed the schema	Compare `schemaHash` or the `ETag`.

GraphQL introspection describes the generated types but not Studio metadata such as labels, menu groups, field groups, hidden, readOnly or option lists; this endpoint does, and it is the only surface that returns the compiled validation JSON Schema in full. It is read-only: deploy a new schema with the CLI.