Skip to main content

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:

LayerWhat it definesExample
ObjectA record type and its display nameequipment
AttributeA typed field on that objectasset_tag (text), operational (boolean)
RecordOne instance containing attribute valuesRooftop 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:

TaskAPI
Create or change objects and attributesREST
Create, update, or delete recordsREST
List or structurally query recordsREST
Read a connected record graph in one requestGraphQL
Download the workspace-generated GraphQL schemaGraphQL 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:

GrantAllows
objects:configuration:readRead the object catalog and definitions without schema editing
schemas:writeAuthor tenant-owned Object and Vehicle schemas through their supported operations
objects:configuration:edit-permissionsManage a protected object's permission matrix, unless the caller owns it
objects:records:readRead records through REST and GraphQL
objects:records:createCreate records
objects:records:updateUpdate records
objects:records:deleteDelete 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 both role_name and user_id.
  • principal_type: "role" — supply a non-blank role_name and omit user_id.
  • principal_type: "user" — supply user_id and omit role_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.