Objects and Records
Objects define the types of records a workspace stores—for example equipment, maintenance requests, sites, contracts, or inspections. Tourfold provides standard and system objects, and a workspace can create custom objects for concepts specific to its business. Both use the same typed Objects and Records contract.
The model has three layers:
| Layer | What it defines | Example |
|---|---|---|
| Object | A record type and its display name | equipment |
| Attribute | A typed field on that object | asset_tag (text), operational (boolean) |
| Record | One instance containing attribute values | Rooftop HVAC Unit RTU-17 |
An object is similar to a table, an attribute to a typed column, and a record to a row. Unlike a database schema, the API also models localized labels, display templates, select choices, state workflows, relationships, validation, permissions, and stable public identities.
Choose REST or GraphQL
The two APIs are complementary:
| Task | API |
|---|---|
| Create or change objects and attributes | REST |
| Create, update, or delete records | REST |
| List or structurally query records | REST |
| Read a connected record graph in one request | GraphQL |
| Download the workspace-generated GraphQL schema | GraphQL schema endpoint |
GraphQL is read-only. Its types and fields are generated from the same object definitions used by REST, so changing an object changes the workspace GraphQL schema. See the GraphQL guide for schema naming, queries, pagination, limits, and errors.
Quickstart
The following requests create an equipment object and its first record. All examples use the public
/api/v2 surface and a Bearer token.
1. Create the object
curl -X POST "https://api.tourfold.com/api/v2/definitions/objects" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "equipment",
"name": {
"en": { "singular": "Equipment item", "plural": "Equipment" },
"de": { "singular": "Anlage", "plural": "Anlagen" }
},
"display_template": "{{name}} ({{asset_tag}})",
"attributes": [
{
"slug": "name",
"type": "text",
"name": { "en": "Name", "de": "Name" },
"config": { "is_required": true }
},
{
"slug": "asset_tag",
"type": "text",
"name": { "en": "Asset tag", "de": "Anlagenkennzeichen" },
"config": { "is_required": true, "is_unique": true }
},
{
"slug": "operational",
"type": "boolean",
"name": { "en": "Operational", "de": "Betriebsbereit" },
"config": { "default": true }
}
]
}'
The response is 201 Created and contains the canonical object. Tourfold assigns immutable UUIDs to the
object and each attribute, adds the four system attributes, and returns lock_version for subsequent
schema writes.
OpenAPI: createObject
2. Create a record
curl -X POST "https://api.tourfold.com/api/v2/objects/equipment/records" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true
}
}'
The response separates system metadata from custom data:
{
"id": "6f3d2a10-0000-4000-8000-000000000117",
"created_at": "2026-08-26T09:30:00Z",
"updated_at": "2026-08-26T09:30:00Z",
"lock_version": 0,
"data": {
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17",
"operational": true
}
}
OpenAPI: createRecord
3. Read it with GraphQL
After downloading the workspace schema, the same object can be queried by its slug-derived root field:
query EquipmentByAssetTag {
equipment(where: { asset_tag: { _eq: "AFS-RTU-17" } }, first: 1) {
edges {
node {
id
name
asset_tag
operational
}
}
}
}
Identity and safe renames
Objects and attributes have an immutable, server-assigned id and a mutable slug. Select options and
states follow the same pattern with an immutable id and mutable value.
Use slugs for readable, interactive calls. Within one workspace, store UUIDs in durable integrations and send existing UUIDs back during declarative schema updates. This lets you rename a slug or option value without creating a new resource or breaking relationships.
IDs are meaningful in their workspace context. Cloning a workspace or template regenerates object, attribute, option, and state UUIDs, so a cross-workspace reference must carry the workspace identity and map the source resource to its target counterpart; do not assume a cloned resource keeps its source UUID.
Permissions
Objects and records use both grants and per-object access control:
| Grant | Allows |
|---|---|
objects:configuration:read | Read the object catalog and definitions without schema editing |
schemas:write | Author tenant-owned Object and Vehicle schemas through their supported operations |
objects:configuration:edit-permissions | Manage a protected object's permission matrix, unless the caller owns it |
objects:records:read | Read records through REST and GraphQL |
objects:records:create | Create records |
objects:records:update | Update records |
objects:records:delete | Delete records |
schemas:write is a separate workspace-wide permission. It includes schema reads and measure-unit
authoring, but does not grant access to records or permission-matrix changes. System- and
plugin-managed schemas remain locked. Owners and admins receive it by default.
Object definitions remain visible as tenant metadata; inaccessible objects are not silently removed from the catalog.
Mutable objects (is_readonly: false) have their own permission matrix. Entries target everyone, a
role, or a user and assign read or write; manage is resolved from ownership/management authority
and is not assignable in the matrix. Read-only system objects (is_readonly: true) are grant-gated and have no editable matrix.
Each entry has exactly one principal shape:
principal_type: "everyone"— omit bothrole_nameanduser_id.principal_type: "role"— supply a non-blankrole_nameand omituser_id.principal_type: "user"— supplyuser_idand omitrole_name.
Missing, contradictory, or duplicate principal fields return 422 validation-failed with an indexed
pointer such as #/entries/0/role_name; they are never silently ignored.
Permission matrices are whole-set resources: PUT {"entries": [...]} replaces the complete matrix and
{"entries": []} clears it. Reading or changing one requires schema read access (objects:configuration:read or
schemas:write) plus the edit-permissions grant or object ownership. Use
getObjectPermissions and
updateObjectPermissions.
A denied REST record request returns 403 access-denied with data.reason = "not_member". GraphQL keeps
the field in the generated schema and returns an explicit field error instead of an empty connection.
Continue
- Objects and attributes: identity, localization, schema writes, and all attribute types.
- Records: CRUD, value shapes, filtering, sorting, batch writes, and optimistic locking.
- Relationships: target objects, managed reverse attributes, cardinality, and traversal.
- Attribute field guide: choose each type by its validation, query, and integration behavior.
- Integration playbooks: evolve schemas and synchronize records safely.
- GraphQL: workspace schemas and connected reads.
- Errors: RFC 9457 problem documents and field-level pointers.