---
title: 'Schema endpoint'
description: 'Read the deployed project schema as the Studio renders it.'
---

# 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.

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

Replace `PROJECT_ID` with the ID from Dashboard Settings → General. Behind the [framework handler](/docs/reference/framework-adapters) 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](/docs/api/tokens), receives **403**. Tokens and agents read the schema through [GraphQL introspection](/docs/api/graphql/reference) or the MCP `search_schema` tool instead.

Browser requests from another origin follow the project's [CORS origins](/docs/api/cors); the endpoint answers `OPTIONS` preflights with the same policy.

## Response

```json
{
  "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](/docs/schema/attribute-reference) and [entity reference](/docs/schema/entity-reference), with `validation` as JSON Schema (see [Validation](/docs/schema/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.

```bash
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](/docs/api/graphql/reference) of the generated API.                                   |
| Let an agent or AI client discover entities, labels, options and rules | MCP [`search_schema`](/docs/integrations/mcp), 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](/docs/cli/deploy).


---

[View full sitemap](/docs/sitemap.md)