PraxQL — Schema Introspection

The /schema endpoint tells you which tables and columns your API key can see. It is where a refs dictionary comes from, and the only reliable way to learn the column names to use in select and where.

The endpoint

GET https://gateway.praxsuite.com/{workspaceId}/schema
Authorization: Bearer sk_live_xxxxx

No request body. What comes back is decided entirely by the credential's scopes.

Response

{
  "tables": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Customers",
      "columns": [
        { "name": "ID",     "type": "Guid",      "isKey": true  },
        { "name": "Name",   "type": "ShortText", "isKey": false },
        { "name": "Email",  "type": "Email",     "isKey": false },
        { "name": "Status", "type": "Status",    "isKey": false },
        { "name": "Orders", "type": "Table",     "isKey": false, "pointsTo": "b2c3d4e5-..." }
      ]
    }
  ]
}

Column types

Two of these behave differently from how they read. A `Status` column returns an object on read — { Id, Name, Color, Position } — not the bare name, so comparing it to a string in client code fails even though filtering on it by name works. A `DocInstance` column stores document ids and returns the resolved document with its content.

Using it

1. Call GET /schema and keep the response.

2. Build refs from the table id values.

3. Use columns[].name verbatim in select, where and orderBy.

4. For a Table column, its pointsTo GUID is the table to add to refs and name in a relation object.

Column names are the ones you see in the workspace, spaces and all. A column shown as Player Name is "Player Name" in a query — not Player_Name.

What makes a table visible

A table appears only when both are true:

1. the credential has a table scope for it, and

2. that scope has AllowSchemaIntrospection = true.

That flag is off by default on a new scope. A key that can query a table perfectly well will get an empty /schema until somebody switches it on — that is the expected behaviour, not a fault.

Columns appear only where CanRead = true. A table with no column scopes defined shows all its columns.

The two settings are separate on purpose: you can let a key query and write a table without letting it enumerate the table's structure. That is the setting to use for a pk_live_ key embedded in public frontend JavaScript.

The Playground ignores AllowSchemaIntrospection and shows every scoped table to workspace admins. That is deliberate — an admin testing a query needs to see what they are testing against.

Caching

Schema data is cached per workspace and invalidated whenever the workspace's structure changes — a table or column added, renamed or deleted. The lookup is not what makes a query slow.

You do not need to call /schema before every request. Fetch it when your integration starts, or when a query starts failing with an unknown-column error, which is the signal that somebody renamed something.