GraphQL Overview
Tourfold exposes a GraphQL API alongside the REST API. It exists for one job the REST surface does not do well: reading Object, Vehicle, Task and Tour records with filters, sorting, pagination and relationship traversal in a single request, against a schema generated from your workspace definitions.
What it covers, and what it does notβ
| Queries | Workspace Object, Vehicle, Task and Tour records (system_tour) and their relationships, including read-only built-in Object projections. |
| Mutations | None. GraphQL is read-only. Create, update and delete go through the owning resourceβs REST endpoints. |
| Subscriptions | None. Use webhooks for change notifications. |
| Core resources | Read-only built-in object projections can be queried and traversed. Their native REST APIs remain the write surface. |
The schema is specific to your workspace. It is derived from the workspace schema catalog, so two workspaces have different types, and yours changes when you add a field or a relation. There is therefore no static schema document to publish β you download the current one from the API (see Schema and naming).
Endpointsβ
| Query | POST https://api.tourfold.com/api/v2/graphql |
| Schema (SDL) | GET https://api.tourfold.com/api/v2/graphql/schema |
Both need Authorization: Bearer <token>. Record queries enforce each resourceβs native read permissions.
Each queried collection enforces its own read permissions. See
Authentication and permissions.
Request formatβ
POST /api/v2/graphql takes the standard GraphQL-over-HTTP JSON envelope:
| Field | Type | Notes |
|---|---|---|
query | String | Required. The document to execute. Maximum 10,000 characters. |
variables | Object | Optional. Values for the document's variable definitions. |
operationName | String | Optional. Required only when query holds more than one operation. |
operationName keeps GraphQL's own camelCase spelling rather than Tourfold's snake_case REST JSON
convention: this envelope belongs to the GraphQL protocol, not to the REST contract.
Response media typeβ
Send Accept: application/graphql-response+json to receive the GraphQL-specific JSON media type.
Accept: application/json remains supported for clients that do not yet send it. Both representations
carry the same GraphQL envelope; transport failures remain application/problem+json.
Tourfold supports this media type and the standard request envelope without claiming conformance to every status-code rule in the still-evolving GraphQL-over-HTTP draft. Query-level failures therefore keep the documented HTTP 200 contract below.
Quickstartβ
Every root field is a Relay connection, so you select
through edges { node { β¦ } } rather than reading a plain list. There is no limit argument β page
size is first (or last); see Pagination.
The examples throughout this section use two tenant-created objects from a fictional workspace, Alpine
Facility Services: equipment (building plant, e.g. a rooftop HVAC unit) and maintenance_request,
related so each piece of equipment has many maintenance requests. Adapt the field names to your own
schema.
query FirstEquipmentPage {
equipment(first: 2, order_by: [{ name: asc }]) {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
cursor
node {
id
name
asset_tag
operational
}
}
}
}
curl -X POST "https://api.tourfold.com/api/v2/graphql" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/graphql-response+json" \
-H "Content-Type: application/json" \
-d '{
"query": "query FirstEquipmentPage { equipment(first: 2, order_by: [{ name: asc }]) { totalCount pageInfo { hasNextPage endCursor } edges { cursor node { id name asset_tag operational } } } }",
"operationName": "FirstEquipmentPage"
}'
{
"data": {
"equipment": {
"totalCount": 3,
"pageInfo": { "hasNextPage": true, "endCursor": "Y3Vyc29yOjE=" },
"edges": [
{
"cursor": "Y3Vyc29yOjA=",
"node": {
"id": "6f3d2a10-0000-4000-8000-000000000101",
"name": "Basement Chiller CH-02",
"asset_tag": "AFS-CH-02",
"operational": true
}
},
{
"cursor": "Y3Vyc29yOjE=",
"node": {
"id": "6f3d2a10-0000-4000-8000-000000000102",
"name": "Passenger Lift LIFT-01",
"asset_tag": "AFS-LIFT-01",
"operational": true
}
}
]
}
},
"extensions": {
"cost": { "estimated_rows": 23, "limit": 100000 }
}
}
Responses report what they costβ
A response carries extensions.cost whenever the request reached cost analysis: estimated_rows is how
far the server calculated the response could expand, and limit is the budget it is measured against. It
is reported on success too, not only on refusals, so you can tune a document before it starts being
rejected.
It is absent when the request failed earlier than analysis β a syntax or validation error β so treat it as optional. See Errors and limits.
Errorsβ
There are two distinct failure modes, and they do not look alike:
- Transport failures β a missing or expired token, a malformed JSON body, a
queryover the 10,000-character maximum β are HTTP 4xx with an RFC 9457 problem document. - Query failures β anything the GraphQL engine or Tourfold rejects about the document itself β are
HTTP 200 with an
errorsarray in the body.datamay still be partially populated.
Never infer success from the status code alone: check for errors. Full detail, including the stable
extensions.code catalog, is in Errors and limits.
Typical workflowβ
- Obtain a Bearer token exactly as for REST, with the read permissions for the resources you query (Authentication and permissions).
- Download your workspace's schema from
GET /api/v2/graphql/schemaand point your GraphQL client or IDE at it (Schema and naming). - Build queries with
whereandorder_by(Filtering and sorting). - Page with
first/after(Pagination). - Watch
extensions.costand stay inside the published limits (Errors and limits).