> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/graphql.md).

# GraphQL

{% @scale-docs-page-title/page-title title="GraphQL" %}

{% hint style="warning" %}
**Confirm before publishing:** the public GraphQL role and endpoint, schema allowlist, per-user and per-broker row authorization, query depth/complexity limits, pagination limits, introspection policy and versioning approach. Today the documented pg\_graphql templates are ScaleAI-internal. Do not issue the internal read-only role or Supabase project key to a partner.
{% endhint %}

GraphQL lets a client request only the stored fields and relationships it needs. This reference separates the **product database graph** from the **Neo4j knowledge graph**. The product graph reads PostgreSQL rows; calculations such as LVR, cashflow and goal progress come from backend calculation and cache services, not raw GraphQL fields.

## Available query groups

ScaleAI uses curated, read-only templates instead of accepting arbitrary database queries from a model.

| Group        | Starts from                      | Typical data                                      |
| ------------ | -------------------------------- | ------------------------------------------------- |
| `workspace`  | Signed-in broker                 | Profile, teams, settings and integrations         |
| `book`       | Clients the broker may see       | Client IDs, strategies, property IDs and targets  |
| `clients`    | Authorized client IDs            | Personal inputs, income, expenses and goals       |
| `properties` | Authorized client IDs            | Property and loan inputs, assumptions and actuals |
| `activity`   | Authorized broker/client context | Meetings, notes, sessions and tasks               |

The engine obtains authorized client IDs from the backend's broker-visibility rule and injects them into templates. A supplied `userId` can narrow a result to one client; it cannot widen the caller's book.

## Query shape

The underlying `pg_graphql` schema uses collection fields and Relay-style `edges { node { … } }`. Database columns are often `snake_case`. Aliases make response keys readable:

```graphql
query ClientNames($clientIds: [UUID!]!, $first: Int = 25) {
  userCollection(filter: { id: { in: $clientIds } }, first: $first) {
    edges {
      node {
        id
        personalDetails: personal_details {
          name
          email
        }
      }
    }
    pageInfo { endCursor hasNextPage }
  }
}
```

```json
{
  "clientIds": ["00000000-0000-4000-8000-000000000001"],
  "first": 25
}
```

```json
{
  "data": {
    "userCollection": {
      "edges": [
        {
          "node": {
            "id": "00000000-0000-4000-8000-000000000001",
            "personalDetails": { "name": "Example Client", "email": "example@example.invalid" }
          }
        }
      ],
      "pageInfo": { "endCursor": null, "hasNextPage": false }
    }
  }
}
```

The UUID and email are synthetic. Field spelling, connection shape and nullability must be regenerated from the current schema before using this as a public example.

## Errors and limits

GraphQL can return `data` and `errors` together. Treat an error as a failed field or query, not as a complete success merely because HTTP status is 200. Paginate collections with the schema's cursor arguments and request only the required fields. A public contract must reject mutations and introspection patterns outside its approved role and complexity budget.

Open [GraphiQL](/api/graphiql.md) to inspect the internal schema and test a scoped query. The versioned public schema will be a curated contract, not a direct promise that every reflected database table is available.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scaleconnect.com.au/api/graphql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.