Skip to main content

Tourfold API (2.0.0)

Download OpenAPI specification:Download

Tourfold API Support: support@tourfold.com URL: https://docs.tourfold.com/docs/api/ License: MIT

Tourfold is a comprehensive SaaS platform for field service management. Our API provides programmatic access to manage jobs, tours, users and much more.

Use the endpoints documented here to automate dispatching flows, synchronize your account data, and build custom integrations for your operators and mobile clients.

Request and response examples follow Alpine Facility Services GmbH, a fictional Vienna maintenance company. The example identities are illustrative and are not created automatically in customer workspaces.

For detailed documentation, workflow guides, and onboarding support, visit https://docs.tourfold.com.

Billing Profile

Tenant billing profile API

Get billing profile

Returns the tenant billing profile used for invoices and Stripe customer metadata.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

AlpineBillingProfile

{
  • "billing_full_name": "Mara Berger",
  • "billing_business_name": "Alpine Facility Services GmbH",
  • "billing_vat_number": "ATU12345678",
  • "billing_country_code": "AT",
  • "billing_email": "billing@example.invalid",
  • "billing_address_line1": "Riverside Office 17",
  • "billing_city": "Vienna",
  • "billing_postal_code": "1210",
  • "billing_state_province": "Vienna",
  • "lock_version": 0
}

Update the billing profile

JSON Merge Patch (RFC 7386): omitted fields remain unchanged; a field set to null is cleared. Fields required for invoicing (billing_email, billing_address_line1, billing_city, billing_postal_code, billing_country_code, and a full name or business name) cannot be cleared โ€” explicit null on those is rejected with 422. Updates the tenant billing profile and syncs supported fields to Stripe when the tenant has a Stripe customer.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
billing_full_name
string or null

Billing contact full name. Omitted leaves the value unchanged; explicit null clears it, but a business name must then be present (a full name or business name is required for invoicing).

billing_business_name
string or null

Billing business name. Omitted leaves the value unchanged; explicit null clears it, but a full name must then be present (a full name or business name is required for invoicing).

billing_vat_number
string or null

VAT number. Read-only after signup โ€” contact support to change. Omitted leaves the value unchanged; explicit null clears it.

billing_country_code
string or null

ISO 3166-1 alpha-2 billing country code. Read-only after signup โ€” contact support to change. Required for invoicing: omitted leaves the value unchanged; explicit null is rejected with 422.

billing_email
string or null

Email address that receives PDF invoices. Required for invoicing: omitted leaves the value unchanged; explicit null is rejected with 422.

billing_address_line1
string or null

Street address, first line. Required for invoicing: omitted leaves the value unchanged; explicit null is rejected with 422.

billing_address_line2
string or null

Street address, second line. Omitted leaves the value unchanged; explicit null clears it.

billing_city
string or null

City. Required for invoicing: omitted leaves the value unchanged; explicit null is rejected with 422.

billing_postal_code
string or null

Postal code. Required for invoicing: omitted leaves the value unchanged; explicit null is rejected with 422.

billing_state_province
string or null

State / province / region. Omitted leaves the value unchanged; explicit null clears it.

lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch) if a profile already exists; omitting it skips the concurrency check. Ignored when creating the first profile.

Responses

Request samples

Content type
application/merge-patch+json

UpdateBillingProfileNull

{
  • "billing_address_line2": null,
  • "billing_city": "Vienna",
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedAlpineBillingProfile

{
  • "billing_full_name": "Mara Berger",
  • "billing_business_name": "Alpine Facility Services GmbH",
  • "billing_vat_number": "ATU12345678",
  • "billing_country_code": "AT",
  • "billing_email": "billing@example.invalid",
  • "billing_address_line1": "Riverside Office 17",
  • "billing_city": "Vienna",
  • "billing_postal_code": "1210",
  • "billing_state_province": "Vienna",
  • "lock_version": 0
}

Objects

Typed Objects API

Get an object's permission matrix

Returns the object's class-level access-control entries (per role/user/everyone). Requires the objects:configuration:read grant plus, per object, the objects:configuration:edit-permissions grant or ownership. Only protected objects have a matrix (readOnly objects return 422).

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

Responses

Response samples

Content type
application/json

EquipmentPermissions

{
  • "object_slug": "equipment",
  • "entries": [
    ]
}

Replace an object's permission matrix

Stores the supplied entries as the object's complete class-level matrix โ€” a whole-set declarative replace, not a merge; {"entries":[]} clears the matrix. Requires the objects:configuration:read grant plus, per object, the objects:configuration:edit-permissions grant or ownership.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

Request Body schema: application/json
required
required
Array of objects (ObjectPermissionEntryInput)

The complete list of entries the type should have after this call.

Array
principal_type
required
string
Enum: "everyone" "role" "user"

The kind of principal receiving access.

role_name
string

Required when principal_type is role; forbidden otherwise.

user_id
string <uuid>

Required when principal_type is user; forbidden otherwise.

level
required
string
Enum: "read" "write"

Access level to grant to the principal.

Responses

Request samples

Content type
application/json
Example

ReplaceEquipmentPermissions

{
  • "entries": [
    ]
}

Response samples

Content type
application/json

ReplacedEquipmentPermissions

{
  • "object_slug": "equipment",
  • "entries": [
    ]
}

Users

User management API. Users can be managed through these endpoints.

Replace tags assigned to a user

Replaces the tags assigned to a user. Empty tag_ids removes all assigned tags.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the user.

Request Body schema: application/json
required
tag_ids
required
Array of strings <uuid> unique [ items <uuid > ]

Tag IDs to assign to the user. Empty array removes all assigned tags.

lock_version
integer or null <int64>

Optimistic locking version of the user aggregate; validated when provided (409 on mismatch), omitting it skips the concurrency check

Responses

Request samples

Content type
application/json
Example

ReplaceWithUrgentTag

{
  • "tag_ids": [
    ],
  • "lock_version": 0
}

Response samples

Content type
application/json

JonasWithReplacedTags

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

List skills assigned to a user

Returns the skills assigned to a user.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user whose skills should be retrieved

Responses

Response samples

Content type
application/json

JonasSkills

{
  • "items": [
    ]
}

Replace skills assigned to a user

Replaces the skills assigned to a user. Empty skill_ids removes all assigned skills.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the user.

Request Body schema: application/json
required
skill_ids
required
Array of strings <uuid> unique [ items <uuid > ]

Skill IDs to assign to the user. Empty array removes all assigned skills.

lock_version
integer or null <int64>

Optimistic locking version of the user aggregate; validated when provided (409 on mismatch), omitting it skips the concurrency check

Responses

Request samples

Content type
application/json
Example

ReplaceWithHvacSkill

{
  • "skill_ids": [
    ],
  • "lock_version": 0
}

Response samples

Content type
application/json

JonasWithReplacedSkills

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

List users

Returns a paginated list of users in your account. Service accounts and API-only users are excluded.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

sort
Array of strings
Example: sort=last_name:asc

Repeated sorting criteria in field:direction format. Allowed fields: id, email, first_name, last_name, status, created_at, updated_at. Default: created_at:desc.

search
string

Search term for email, first name, or last name.

role
string
Example: role=driver

Filter by role name. Matching is case-insensitive.

status
string
Default: "ACTIVE"
Enum: "ACTIVE" "BLOCKED" "INACTIVE" "ALL"

Filter by user status (ACTIVE, BLOCKED, INACTIVE, ALL). Default is ACTIVE.

role_ids
Array of strings <uuid> [ items <uuid > ]

Filter users by one or more role UUIDs. Only users assigned to at least one of the specified roles are returned.

skill_ids
Array of strings <uuid> [ items <uuid > ]

Filter users by one or more skill UUIDs. Only users with at least one of the specified skill offerings are returned.

tag_names
Array of strings

Filter users by tag name (OR semantics: returns users that have at least one of the given tags). Multiple values are supported. When omitted, no tag filtering is applied.

updated_from
string <date-time>
Example: updated_from=2024-01-01T00:00:00Z

Lower bound for updated_at (inclusive, RFC 3339). When combined with updated_to, restricts the result to users modified within the window โ€” useful for incremental sync.

updated_to
string <date-time>
Example: updated_to=2024-12-31T23:59:59Z

Upper bound for updated_at (exclusive, RFC 3339). updated_from must be strictly before updated_to.

Responses

Response samples

Content type
application/json

UsersResponse

{
  • "items": [
    ],
  • "page": {
    }
}

Create a user

Creates a user and assigns roles permitted for the caller. Owner-role assignment requires the ownership transfer operation. Email is immutable after creation. Where the workspace manages its people's profiles, firstname and lastname are required and phone_number is optional. Where people manage their own profile (one sign-in account for all their workspaces; is_profile_self_managed on their users), this invites the person by email and the request must not carry firstname, lastname or phone_number: the user has no name until the person's first sign-in (profile_status PENDING), whether or not they already have a Tourfold account. A person new to Tourfold gets an invitation email; a person who already has an account gets an email saying they were added.

Authorizations:
BearerAuth
header Parameters
Origin
string
Request Body schema: application/json
required
email
required
string <email> non-empty

Email address of the user

firstname
string

First name of the user. Required where the workspace manages its people's profiles. Where people manage their own profile (one sign-in account for all their workspaces; is_profile_self_managed on their users) it must be omitted: the person enters it at first sign-in, and sending it is rejected with 422, problem type users/profile-self-managed. A blank value is rejected. Cannot contain < > & " $ % ! # ? ยง ; * ~ / \ | ^ = [ ] { } ( ), line breaks or control characters.

lastname
string

Last name of the user. Required where the workspace manages its people's profiles. Where people manage their own profile (one sign-in account for all their workspaces; is_profile_self_managed on their users) it must be omitted: the person enters it at first sign-in, and sending it is rejected with 422, problem type users/profile-self-managed. A blank value is rejected. Cannot contain < > & " $ % ! # ? ยง ; * ~ / \ | ^ = [ ] { } ( ), line breaks or control characters.

phone_number
string

International phone number. An explicit '+' country code is required; common formatting is accepted and normalized to canonical E.164. National numbers are rejected. Omit the field to leave it unset; a blank value is rejected. Where people manage their own profile it must be omitted, like the names (422, problem type users/profile-self-managed).

role_ids
required
Array of strings <uuid> non-empty unique [ items <uuid > ]

Roles to assign to the user

skill_ids
Array of strings <uuid> unique [ items <uuid > ]

Skills to assign to the user

tag_ids
Array of strings <uuid> unique [ items <uuid > ]

Tags to assign to the user. When omitted, no tags are assigned.

Responses

Request samples

Content type
application/json
Example

CreateAlpineTechnician

{
  • "email": "jonas.leitner@example.invalid",
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "phone_number": "+43 664 123 45 67",
  • "role_ids": [
    ],
  • "skill_ids": [
    ],
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
Example

CreateUserResponse

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

Unblock a user

Unblocks a user who was blocked due to failed login attempts.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user to unblock

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Resend set password email

Asks Keycloak to resend the set-password link to an invited user who has not signed in yet. Where people manage their own profile (is_profile_self_managed), it resends the invitation while profile_status is PENDING: the set-password link to a person new to Tourfold, an email that they were added to one who already has an account.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user to receive the set-password email

header Parameters
Origin
string

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Resend user invitation

Resends the invitation email for an invited user whose profile_status is PENDING (a set-password link for a person new to Tourfold, or an email that they were added to one who already has an account), or the set-password email where the workspace manages its people's profiles.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user to receive the invitation email

header Parameters
Origin
string

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Transfer tenant ownership

Transfers the owner role to the target user. Only the current owner may call this endpoint. The current owner loses owner and keeps admin.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the user.

Responses

Response samples

Content type
application/json

TransferredOwner

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

Deactivate a user

Deactivates the user, preventing them from accessing the system.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user to deactivate

Responses

Response samples

Content type
application/json

DeactivatedUser

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [ ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T10:00:00Z",
  • "status": "INACTIVE",
  • "lock_version": 1,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [ ]
}

Activate a user

Activates the user, allowing them to access the system.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user to activate

Responses

Response samples

Content type
application/json

ActivatedUser

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

Get a user

Returns a single user by their unique identifier.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user to retrieve

Responses

Response samples

Content type
application/json

UserResponse

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

Delete a user

Soft-deletes a user by marking the record as deleted (sets deleted_at timestamp). When anonymize=true, also anonymizes personal data (email, firstname, lastname, phone). The user will no longer appear in any API responses. Users cannot delete themselves. Users with the owner role cannot be deleted.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>
Example: 1ec2dffe-2a5b-4c59-9ea2-9f0c3c5ab5af

UUID of the user to delete

query Parameters
anonymize
boolean
Example: anonymize=true

When true, anonymizes personal data (email, firstname, lastname, phone) in addition to soft-deleting

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a user

JSON Merge Patch (RFC 7386) update of a user. Fields omitted remain unchanged, fields set to null are cleared. Email cannot be changed. When the user's is_profile_self_managed is true, only the user can change firstname, lastname and phone_number; sending their current values is accepted. A name or phone change is saved to the user's sign-in account first.

Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid>

UUID of the user.

Request Body schema: application/merge-patch+json
required
firstname
string

First name of the user. Omitted leaves the value unchanged. Required: it cannot be cleared, and null or a blank value is rejected. Cannot contain < > & " $ % ! # ? ยง ; * ~ / \ | ^ = [ ] { } ( ), line breaks or control characters.

lastname
string

Last name of the user. Omitted leaves the value unchanged. Required: it cannot be cleared, and null or a blank value is rejected. Cannot contain < > & " $ % ! # ? ยง ; * ~ / \ | ^ = [ ] { } ( ), line breaks or control characters.

phone_number
string or null

International phone number. An explicit '+' country code is required; common formatting is accepted and normalized to canonical E.164. National numbers are rejected. Omitted leaves the value unchanged; explicit null clears it; a blank value is rejected.

role_ids
Array of strings <uuid> unique [ items <uuid > ]

Roles to assign to the user. Omitted leaves the assignment unchanged; when provided it replaces the assigned roles and must contain at least one role. Explicit null and empty arrays are rejected (422).

lock_version
integer or null <int64>

Optimistic locking version of the user aggregate; validated when provided (409 on mismatch), omitting it skips the concurrency check

Responses

Request samples

Content type
application/merge-patch+json
Example

UpdateUserNull

{
  • "lock_version": 2,
  • "firstname": "Mara",
  • "phone_number": null
}

Response samples

Content type
application/json

UpdateUserResponse

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

Get current user

Returns the currently authenticated user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

CurrentUserResponse

{
  • "id": "00000000-0000-4000-8000-000000001002",
  • "email": "jonas.leitner@example.invalid",
  • "phone_number": "+436641234567",
  • "roles": [
    ],
  • "skills": [
    ],
  • "firstname": "Jonas",
  • "lastname": "Leitner",
  • "profile_status": "COMPLETE",
  • "created_at": "2026-08-20T08:05:00Z",
  • "updated_at": "2026-08-20T08:05:00Z",
  • "status": "ACTIVE",
  • "lock_version": 0,
  • "can_resend_set_password_email": false,
  • "is_profile_self_managed": true,
  • "tags": [
    ]
}

List workspace members for user pickers

Returns the workspace's human users with their display name and status, for choosing values of user fields on records. Any signed-in user may call it; the response never contains email addresses or other contact details. Deleted users and service accounts are never listed. Results are ordered by display name, then id.

Authorizations:
BearerAuth
query Parameters
search
string
Example: search=lei

Matches first name, last name, full name or email address.

status
string
Default: "ACTIVE"
Enum: "ACTIVE" "ALL"

ACTIVE (default) lists active members; ALL adds deactivated members.

page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

UserDirectory

{
  • "items": [
    ],
  • "page": {
    }
}

Tasks

Minimal task management and filterable backlog

List tasks

Requires the 'tasks:read' grant.

Authorizations:
BearerAuth
query Parameters
search
string

Case-insensitive literal title substring or exact task number (123 or Task-123); blank is invalid

status
string
Enum: "open" "done"

Filter by completion state; omitted returns both states

assignee_user_id
string <uuid>

Exact assignee; omitted includes every assignee and unassigned tasks

object_id
string <uuid>

Object or concrete Vehicle definition UUID; requires record_id

record_id
string <uuid>

Record UUID; requires object_id. Matches ad hoc links in any role or named custom relationships when the target is readable. Returns each Task once with the same matching for page totals

page
integer <int32> >= 0
Default: 0

Zero-based page number

size
integer <int32> [ 1 .. 100 ]
Default: 20

Maximum tasks per page

sort
string
Default: "created_at:desc"
Enum: "natural_id" "natural_id:asc" "natural_id:desc" "created_at" "created_at:asc" "created_at:desc" "updated_at" "updated_at:asc" "updated_at:desc" "title" "title:asc" "title:desc" "status" "status:asc" "status:desc" "id" "id:asc" "id:desc"

One field[:direction] criterion. Fields: natural_id, created_at, updated_at, title, status, id. Directions: asc, desc; omitted direction means asc. Default: created_at:desc. Stable id tie-breaker.

ids
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Only these Task UUIDs; repeat ids for each value.

has_visit
boolean

True for visit tasks, false for other types

definition_id
string <uuid>

Exact concrete Task definition

natural_id
integer <int64> >= 1

Exact human task number

type
string

Concrete Task definition: built-in name, custom slug or UUID

execution_type
string
Enum: "simple" "workflow_single_choice_question" "workflow_free_text_question" "visit"

Execution behavior across definitions

Responses

Response samples

Content type
application/json

TaskBacklog

{
  • "items": [
    ],
  • "page": {
    }
}

Create a task

Creates a simple or visit Task. Question Tasks are created only by workflow approval steps. Requires the 'tasks:write' grant.

Authorizations:
BearerAuth
Request Body schema: application/json
required
type
required
string [ 1 .. 63 ] characters

Definition selector: simple, visit, a custom Task definition slug, or a concrete Task definition UUID. Immutable after creation.

title
required
string [ 1 .. 255 ] characters \S

Nonblank Task title

assignee_user_id
string or null <uuid>

User in this tenant; omitted or null leaves the Task unassigned

Array of objects (TaskLinkedRecordInput)

Complete record references; omission defaults to an empty array and null is rejected

object

Custom values by attribute slug. Omitted fields receive defaults; null data is rejected.

TaskVisitInput (object) or null

Required for a Visit definition; omitted or null for a Simple definition. The selected definition controls this requirement.

Responses

Request samples

Content type
application/json

SimpleTask

{
  • "type": "simple",
  • "title": "Call customer to confirm delivery"
}

Response samples

Content type
application/json

OpenTask

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": "1",
  • "definition_id": "46600000-0000-4000-8000-000000000001",
  • "data": { },
  • "type": "simple",
  • "execution_type": "simple",
  • "title": "Call customer to confirm delivery",
  • "status": "open",
  • "linked_records": [ ],
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0
}

Answer a Task interaction

Requires tasks:write and an active human user. Assignment organizes work and does not grant or restrict answering. Commits the accepted response, Task completion and durable owner continuation atomically. Identical retries by the same authorized human return the saved response even with the original lock_version. The workflow resumes asynchronously through the selected option path; rejection may continue. Expired/cancelled interactions cannot be answered.

Authorizations:
BearerAuth
path Parameters
task_id
required
string <uuid>

Task UUID in this tenant

Request Body schema: application/json
required
interaction_id
required
string <uuid>
lock_version
integer or null <int64> >= 0
type
required
string
option_id
required
string [ 1 .. 64 ] characters \S
comment
string [ 1 .. 2000 ] characters \S

Responses

Request samples

Content type
application/json

ChooseApproval

{
  • "type": "single_choice",
  • "interaction_id": "6ba7b811-9dad-41d1-80b4-00c04fd430c8",
  • "option_id": "approved",
  • "lock_version": 0
}

Response samples

Content type
application/json

AcceptedChoice

{
  • "type": "workflow_single_choice_question",
  • "execution_type": "workflow_single_choice_question",
  • "id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
  • "natural_id": "1",
  • "definition_id": "46600000-0000-4000-8000-000000000003",
  • "title": "Approve assistance",
  • "status": "done",
  • "linked_records": [ ],
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:01:00Z",
  • "lock_version": 1,
  • "interaction": {
    }
}

Get a task

Requires the 'tasks:read' grant.

Authorizations:
BearerAuth
path Parameters
task_id
required
string <uuid>

UUID of the task in the current tenant

Responses

Response samples

Content type
application/json

OpenTask

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": "1",
  • "definition_id": "46600000-0000-4000-8000-000000000001",
  • "data": { },
  • "type": "simple",
  • "execution_type": "simple",
  • "title": "Call customer to confirm delivery",
  • "status": "open",
  • "linked_records": [ ],
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0
}

Delete a task

Only normal Tasks can be deleted. Question Tasks retain their decision history and return 409. Requires the 'tasks:write' grant.

Authorizations:
BearerAuth
path Parameters
task_id
required
string <uuid>

UUID of the task in the current tenant

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a task

Question Tasks permit reassignment but reject ordinary status changes and changes to their title or record context. Type is immutable. Requires the 'tasks:write' grant.

Authorizations:
BearerAuth
path Parameters
task_id
required
string <uuid>

UUID of the task in the current tenant

Request Body schema:
required
title
string [ 1 .. 255 ] characters

Nonblank title; null is rejected.

status
string
Enum: "open" "done"

Complete or reopen a normal Task; question Tasks reject this field with 409. Null is rejected.

assignee_user_id
string or null <uuid>

User in the current tenant. Null clears the assignee.

Array of objects (TaskLinkedRecordInput)

Replaces the entire array, including roles. Empty array removes all links; null is rejected. Existing restricted links may be retained or removed.

lock_version
integer or null <int64> >= 0

Version from the previous read. Stale versions return 409. Omitted or null skips the version precondition.

object (UpdateTaskVisit)

Replace the fixed visit destination. Only valid for visit tasks; null is rejected.

object

Custom value patch: omitted fields stay unchanged, field null clears when allowed. Empty object preserves all values; null data is rejected. Not supported on workflow questions.

Responses

Request samples

Content type

CompleteAndUnassign

{
  • "status": "done",
  • "assignee_user_id": null,
  • "lock_version": 0
}

Response samples

Content type
application/json

CompletedTask

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": "1",
  • "definition_id": "46600000-0000-4000-8000-000000000001",
  • "data": { },
  • "type": "simple",
  • "execution_type": "simple",
  • "title": "Call customer to confirm delivery",
  • "status": "done",
  • "linked_records": [ ],
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:05:00Z",
  • "lock_version": 1
}

List records related through a Task attribute

Returns canonical target records ordered by UUID. Requires tasks:read and the target collection read permission before records or totals are returned.

Authorizations:
BearerAuth
path Parameters
task_id
required
string <uuid>

Task UUID

attribute_ref
required
string

Relationship attribute UUID or slug

query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

Responses

Response samples

Content type
application/json

EmptyPage

{
  • "items": [ ],
  • "page": {
    }
}

Sms Report

Query SMS message history for reporting and auditing. Returns all SMS sent through the system with status, timestamps, and gateway information.

List SMS message history

        Returns a paginated list of SMS messages for the current tenant, with optional filtering by date range and status.

        **Date Range:**
        - Defaults to last 28 days if not specified
        - Filters on the `scheduled_at` timestamp using a half-open range
        - Use RFC 3339 format (e.g., 2024-01-15T10:30:00Z)

        **Status Values:**
        - SCHEDULED: Waiting to be sent
        - SENDING: Currently being sent
        - SENT: Successfully accepted by gateway
        - DELIVERED: Confirmed delivered to recipient (Twilio only, via webhook)
        - READ: Confirmed read by recipient (Twilio only, via webhook)
        - FAILED: Failed to send

        **Sorting:**
        - Default: `scheduled_at:desc` (newest first)
        - Allowed fields: scheduled_at, sent_at, status, created_at, to_number, gateway_name
        - Format: `field:asc` or `field:desc`
        - Multiple sort criteria supported
    
Authorizations:
BearerAuth
query Parameters
scheduled_from
string <date-time>
Example: scheduled_from=2024-01-01T00:00:00Z

Lower bound for scheduled_at (inclusive, RFC 3339). Defaults to 28 days ago.

scheduled_to
string <date-time>
Example: scheduled_to=2024-12-31T23:59:59Z

Upper bound for scheduled_at (exclusive, RFC 3339). Defaults to now.

status
string
Enum: "SCHEDULED" "SENDING" "SENT" "DELIVERED" "READ" "FAILED"
Example: status=SENT

Filter by SMS status

page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 1000 ]
Default: 100
Example: size=100

Number of items per page (max 1000). The cap is deliberately higher than the platform default of 100 because this is a report/export-style endpoint.

sort
Array of strings
Example: sort=scheduled_at:desc

Repeated sorting criteria in field:direction format. Allowed fields: id, scheduled_at, sent_at, status, created_at, to_number, from_number, gateway_name. Default: scheduled_at:desc.

Responses

Response samples

Content type
application/json

SmsReportExample

{
  • "items": [
    ],
  • "page": {
    }
}

TourTaskAssignments

Tour-owned Task membership and automatic visit stops

List tour Task assignments

Requires tours:read, or tours:read-own for memberships in published tours containing the current human user. Filters combine with AND; results sort by assignment id ascending.

Authorizations:
BearerAuth
query Parameters
tour_id
string <uuid>

Exact Tour UUID

task_ids
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Filter by Task UUIDs; repeat task_ids for each value.

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Page size

Responses

Response samples

Content type
application/json

Success

{
  • "items": [
    ],
  • "page": {
    }
}

Assign a Task to a tour

Requires tasks:read and tours:update, or tours:execute-own for an own ad-hoc tour. Creates a visit stop atomically for a visit Task. Task content and version remain unchanged.

Authorizations:
BearerAuth
Request Body schema: application/json
required
task_id
required
string <uuid>
tour_id
required
string <uuid>

Responses

Request samples

Content type
application/json

Request

{
  • "task_id": "07b8775e-49d7-4980-adfe-1423a87765ab",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522"
}

Response samples

Content type
application/json

Success

{
  • "id": "6b4528bd-8a92-497c-9aa9-6c049d99a5e2",
  • "task_id": "07b8775e-49d7-4980-adfe-1423a87765ab",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "tour_natural_id": 1,
  • "position": 0,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0
}

Get a tour Task assignment

Requires tours:read or tours:read-own for a published tour containing the current human user.

Authorizations:
BearerAuth
path Parameters
assignment_id
required
string <uuid>

Assignment UUID

Responses

Response samples

Content type
application/json

Success

{
  • "id": "6b4528bd-8a92-497c-9aa9-6c049d99a5e2",
  • "task_id": "07b8775e-49d7-4980-adfe-1423a87765ab",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "tour_natural_id": 1,
  • "position": 0,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0
}

Unassign a Task from its tour

Requires tours:update, or tours:execute-own for an own ad-hoc tour. Removes its visit stop atomically and preserves the Task.

Authorizations:
BearerAuth
path Parameters
assignment_id
required
string <uuid>

Assignment UUID

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Move a Task to another tour

Requires tasks:read and planning access to both tours: tours:update, or tours:execute-own for an own ad-hoc tour. Preserves the assignment UUID. An exclusively task-backed stop moves with it; leaving a combined or dispatcher stop creates a new visit stop; neither changes Task content or version.

Authorizations:
BearerAuth
path Parameters
assignment_id
required
string <uuid>

Assignment UUID

Request Body schema:
required
tour_id
string <uuid>
lock_version
integer or null <int64> >= 0

Assignment version. Omitted or null skips the precondition; stale versions return 409.

Responses

Request samples

Content type

Request

{
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "lock_version": 0
}

Response samples

Content type
application/json

Success

{
  • "id": "6b4528bd-8a92-497c-9aa9-6c049d99a5e2",
  • "task_id": "07b8775e-49d7-4980-adfe-1423a87765ab",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "tour_natural_id": 1,
  • "position": 0,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0
}

vehicle-definitions

Native Vehicle definitions and shared custom attributes

Get a vehicle definition

Get a vehicle definition.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "attributes": [
    ],
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

Replace a Vehicle definition

Atomically replace metadata and the complete authored attribute set. Omitted owned fields are removed; inherited/native/generated fields remain and must not be submitted. IDs preserve identity across renames; id-less existing slugs preserve identity. Validate the template against the final schema. Omitted icon, color and display_template are cleared. Plugin and system definitions are locked.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

Request Body schema: application/json
required
natural_id_key
string or null^[A-Z][A-Z0-9]{0,15}$

Optional natural ID prefix, unique across definitions when set. Null means numeric-only string IDs. Omission preserves the prefix on PATCH and means no prefix on creation or replacement. Use 1โ€“16 uppercase letters or digits, starting with a letter. Changing it changes displayed IDs without changing record identity or counters.

slug
required
string <= 63 characters ^[a-z][a-z0-9_]*$

Definition slug.

required
object

Complete localized names.

required
Array of any (AttributeInput) <= 20 items

Complete authored attribute set. Empty removes all owned fields, subject to data/dependency guards.

display_template
string [ 1 .. 2000 ] characters

Template for the final schema. Omission or null restores the native label fallback; blank strings are rejected.

lock_version
integer <int64> >= 0

Optional version precondition; stale versions return 409.

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon key from the client icon catalog, for example truck. Clients render a default icon for unknown keys. Omission means no icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Palette color of the definition icon. Omission or null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Attribute slugs shown, in order, under the record name and the clicked location in a map popup, for example ["plate_number", "color"]. Each attribute at most once; list-valued attributes (tags, skills, multi-value relationships) are not allowed. Renaming or deleting an attribute updates the list. Omission means none.

Responses

Request samples

Content type
application/json

replace

{
  • "slug": "bicycle",
  • "name": {
    },
  • "attributes": [
    ],
  • "lock_version": 0
}

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "attributes": [
    ],
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

Delete an empty Vehicle definition

Delete a tenant-owned definition only when it has no vehicles and no schema dependencies. Removes its attribute storage and outgoing relationships. Managed definitions cannot be deleted.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update Vehicle definition metadata

Partially update a Vehicle definition by UUID or slug. Omission preserves optional metadata; null clears icon, color, natural_id_key or display_template. Unset color is transparent. Plugin and system definitions allow icon, color and natural ID prefix changes only; their schema remains locked. Name translations and slug can also be changed. The UUID remains stable; the old slug stops resolving after rename. Attributes use their nested endpoints.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

Request Body schema: application/merge-patch+json
required
natural_id_key
string or null^[A-Z][A-Z0-9]{0,15}$

Optional natural ID prefix, unique across definitions when set. Null means numeric-only string IDs. Omission preserves the prefix on PATCH and means no prefix on creation or replacement. Use 1โ€“16 uppercase letters or digits, starting with a letter. Changing it changes displayed IDs without changing record identity or counters.

slug
string <= 63 characters

New definition slug; UUID and storage identity remain unchanged. Omitted preserves it; null is rejected.

object

Merge names by language and noun form. A null language removes its translation. Empty maps preserve current values. At least one localized name must remain; root null is rejected.

display_template
string or null [ 1 .. 2000 ] characters

Label template using {{slug}} native-field or column-backed attribute placeholders. Other attribute types are not supported in labels yet. Null restores the native fallback; blank strings are rejected.

lock_version
integer or null <int64> >= 0

Optional version precondition; stale versions return 409.

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon catalog key. Omission preserves it; null restores the default icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Icon background palette color. Omission preserves it; null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Ordered popup field selection. Omission preserves it; null clears it to an empty list; an array replaces it. Lists and structured JSON fields are unsupported.

Responses

Request samples

Content type
application/merge-patch+json

label

{
  • "display_template": "Bike {{battery_wh}} Wh",
  • "lock_version": 0
}

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "attributes": [
    ],
  • "display_template": "Bike {{battery_wh}} Wh",
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

Replace the attribute order

Replaces the display order of all attributes atomically: the system attributes (id, created_at, updated_at, lock_version), the native definition_id and natural_id, inherited attributes such as location and managed reverse relationships, and the definition's own attributes. List every slug of the definition's attributes exactly once; the response returns attributes in this order, which also drives record forms and the default list columns. Only the order changes. Until an order is saved, id and the native fields come first and created_at, updated_at and lock_version come last. Later attribute additions are appended. Plugin and system definitions are locked.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

Request Body schema: application/json
required
attribute_slugs
required
Array of strings non-empty

Slug of every attribute of the definition, each exactly once, in display order (first = topmost). This is the set of slugs in the definition's attributes.

lock_version
integer <int64> >= 0

Optimistic-locking version of the definition: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

batteryFirst

{
  • "attribute_slugs": [
    ],
  • "lock_version": 0
}

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "attributes": [
    ],
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

List vehicle definitions

Vehicle definitions ordered by created_at ascending, then id ascending. Read with vehicles:read or schemas:write; authoring requires schemas:write.

Authorizations:
BearerAuth
query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page number

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

bicycle

{
  • "items": [
    ],
  • "page": {
    }
}

Create a vehicle definition

Create a tenant-owned Vehicle definition using the shared attribute types and optional display configuration; the native Vehicle base is implicit.

Authorizations:
BearerAuth
Request Body schema: application/json
required
natural_id_key
string or null^[A-Z][A-Z0-9]{0,15}$

Optional natural ID prefix, unique across definitions when set. Null means numeric-only string IDs. Omission preserves the prefix on PATCH and means no prefix on creation or replacement. Use 1โ€“16 uppercase letters or digits, starting with a letter. Changing it changes displayed IDs without changing record identity or counters.

slug
required
string <= 63 characters ^[a-z][a-z0-9_]*$

Vehicle definition slug. The plugin_ prefix is reserved for plugin-managed definitions; all, self and this are reserved words.

required
object

Localized singular/plural names.

Array of any (AttributeInput) <= 20 items

Shared attribute definitions. All shared attribute types are supported, including relationships and ordinary location attributes; the intrinsic location is inherited and read-only.

display_template
string [ 1 .. 2000 ] characters

Optional record label template using {{slug}} placeholders for native fields or column-backed attributes. Relationship, location, tags and skills placeholders are not supported yet. Blank strings are rejected.

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon key from the client icon catalog, for example truck. Clients render a default icon for unknown keys. Omission means no icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Palette color of the definition icon. Omission or null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Attribute slugs shown, in order, under the record name and the clicked location in a map popup, for example ["plate_number", "color"]. Each attribute at most once; list-valued attributes (tags, skills, multi-value relationships) are not allowed. Renaming or deleting an attribute updates the list. Omission means none.

Responses

Request samples

Content type
application/json

bicycle

{
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "attributes": [
    ]
}

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "attributes": [
    ],
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

Add a Vehicle attribute

Add one attribute to a tenant-owned Vehicle definition, using the same typed attribute payload as Objects. Returns the complete updated definition. Existing record values are preserved; defaults apply to future record creation, without backfilling existing records. The optional lock_version refers to the definition. Plugin and system definitions are locked.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

Request Body schema: application/json
required
id
string <uuid>

Existing attribute id (omit on create; send to update/rename)

slug
required
string <= 200 characters ^[a-z][a-z0-9_]*$

Attribute slug; self, this and platform record fields are reserved.

type
required
string

Attribute type selecting this configuration.

object

Attribute label per language tag, e.g. {"en": "Purchase price"}

description
string

Optional attribute description

object (TextAttributeConfigInput)

Configuration for text attributes.

lock_version
integer <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

range

{
  • "slug": "range_km",
  • "type": "number",
  • "name": {
    },
  • "config": {
    },
  • "lock_version": 0
}

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "attributes": [
    ],
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

Delete a Vehicle attribute

Delete an owned attribute and its stored values/relationship edges. Generated reverse fields are removed together. Clear or update a display template referencing this attribute first. Native location and inherited/managed attributes cannot be deleted.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

attribute_ref
required
string

Owned attribute UUID or slug

Responses

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 3,
  • "attributes": [
    ],
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

Update a Vehicle attribute

Merge an owned attribute by UUID or slug. Omitted fields are preserved; option/state arrays replace their set. Attribute and choice IDs preserve values through renames. Type, uniqueness, cardinality and relationship target are immutable. Managed and inherited attributes, including the native location, cannot be changed.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

attribute_ref
required
string

Owned attribute UUID or slug

Request Body schema: application/merge-patch+json
required
id
string or null <uuid>

Optional identity assertion; must match the routed attribute.

type
string or null
Enum: "text" "license_plate" "vin" "number" "date" "date_time" "boolean" "select" "state" "capacity" "measure" "currency" "rating" "email" "phone" "tags" "required_skills" "provided_skills" "relationship" "location" "raw_json" "rich_text" "full_name" "links" null

Optional type assertion; cannot change the stored type.

slug
string <= 200 characters ^[a-z][a-z0-9_]*$

New slug. Omission preserves it; null cannot clear it.

object

Merge localized labels. Null at a language key removes that translation.

description
string or null

Null clears the description; blank text is rejected.

object or null

Merge type-specific configuration keys with the stored configuration. Null clears an optional setting; null config resets optional configuration. Required settings, immutable uniqueness, unknown keys and keys belonging to another type are validated after merging.

Array of objects (SelectOptionInput)

Select only: replaces choices; [] clears them. Existing choice IDs preserve stored values.

Array of objects (StateInput)

State only: replaces states; [] clears them. Existing state IDs preserve stored values.

lock_version
integer or null <int64> >= 0

Optional definition version precondition.

Responses

Request samples

Content type
application/merge-patch+json

rename

{
  • "slug": "estimated_range_km",
  • "lock_version": 1
}

Response samples

Content type
application/json

bicycle

{
  • "id": "11111111-9999-4444-8888-111111111111",
  • "slug": "bicycle",
  • "natural_id_key": "BIKE",
  • "name": {
    },
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 2,
  • "attributes": [
    ],
  • "resource_type": "vehicle",
  • "is_readonly": false,
  • "is_relationship_target": true,
  • "map_marker_fields": [ ]
}

Workflows

Tenant-wide workflow authoring and immutable publication. Requires workflows:manage; definitions and history may contain tenant-wide data.

List workflows

Requires the 'workflows:manage' grant. Metadata only, without loading graphs. The trigger summary refers to the published version.

Authorizations:
BearerAuth
query Parameters
search
string <= 255 characters

Literal case-insensitive substring of name; blank is invalid

is_enabled
boolean

Filter by enablement

is_published
boolean

Filter by presence of a published version

trigger_object_id
string <uuid>

Exact custom-object UUID selected by the published trigger

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

sort
string
Default: "created_at:desc"
Enum: "created_at" "created_at:asc" "created_at:desc" "updated_at" "updated_at:asc" "updated_at:desc" "name" "name:asc" "name:desc" "id" "id:asc" "id:desc" "run_count" "run_count:asc" "run_count:desc" "last_published_at" "last_published_at:asc" "last_published_at:desc" "last_failed_run_at" "last_failed_run_at:asc" "last_failed_run_at:desc"

One field[:direction] criterion. Fields: created_at, updated_at, name, id, run_count, last_published_at, last_failed_run_at. asc/desc; omitted direction means asc. Default created_at:desc with stable id tie-breaker. Missing timestamps sort last in either direction. Run statistics use the local history projection.

Responses

Response samples

Content type
application/json

WorkflowPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create a workflow

Requires the 'workflows:manage' grant. Creates a disabled workflow parent without executable content. Create a nested working version to author its graph. Optional origin_tour_template_id records the saved template from which authoring began and additionally requires tour-templates:read; an unknown template returns 404.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters
description
string [ 1 .. 1000 ] characters

Optional plain-text description, at most 1000 characters after trimming. Omit it when there is none; a blank value returns 422.

origin_tour_template_id
string <uuid>

Optional creation origin. Requires tour-templates:read. Retained for the template's workflow panel even when actions change; origin alone never blocks template deletion.

Responses

Request samples

Content type
application/json

NamedWorkflow

{
  • "name": "Follow up with new people",
  • "description": "Creates a follow-up task for every new person."
}

Response samples

Content type
application/json

WorkflowParent

{
  • "id": "00000000-0000-4000-8000-000000000030",
  • "name": "Follow up with new people",
  • "description": "Creates a follow-up task for every new person.",
  • "is_enabled": false,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0
}

List workflow versions

Requires the 'workflows:manage' grant. Working and published version summaries with exactly one current publication, ordered by version_number descending with stable id tie-breaker.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

Responses

Response samples

Content type
application/json

VersionPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create a working workflow version

Requires workflows:manage. Creates the sole editable version, empty or copied from a version belonging to this workflow. An existing working version returns 409. Numbers are allocated at creation and never reused after deletion. Creating a version does not change the current publication or live state.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

Request Body schema: application/json
required
source_version_id
string <uuid>

Version from this workflow to copy. The source stays unchanged.

Responses

Request samples

Content type
application/json
Example

EmptyVersion

{ }

Response samples

Content type
application/json

WorkingVersion

{
  • "id": "00000000-0000-4000-8000-000000000040",
  • "workflow_id": "00000000-0000-4000-8000-000000000030",
  • "version_number": 1,
  • "name": "Follow up with new people",
  • "definition": {
    },
  • "layout": {
    },
  • "interpreter_version": 1,
  • "action_version": 1,
  • "state": "draft",
  • "is_current": false,
  • "lock_version": 0,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "validation_issues": [
    ]
}

Publish a workflow version

Requires workflows:manage. Script and Agent graphs additionally require workflows:code:execute and every grant required by their selected tools. Validates the saved graph and freezes inline Script/Agent configuration and tool contracts atomically. Agents use bounded READ tools, aggregate budgets and shared AI metering. First publication enables the workflow atomically; later publications preserve its enabled or paused state. Existing runs retain their original graph and dependencies.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

version_id
required
string <uuid>

Working version UUID belonging to this workflow

Request Body schema: application/json
required
lock_version
integer <int64> >= 0

Stale values return 409; omitted or null skips the precondition.

Responses

Request samples

Content type
application/json

PublishSavedDraft

{
  • "lock_version": 1
}

Response samples

Content type
application/json

PublishedVersion

{
  • "id": "00000000-0000-4000-8000-000000000040",
  • "workflow_id": "00000000-0000-4000-8000-000000000030",
  • "version_number": 1,
  • "name": "Follow up with new people",
  • "published_at": "2023-02-14T10:00:00Z",
  • "definition": {
    },
  • "layout": {
    },
  • "interpreter_version": 1,
  • "action_version": 1,
  • "state": "published",
  • "is_current": true,
  • "lock_version": 2,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "validation_issues": [ ]
}

Get a workflow

Requires the 'workflows:manage' grant. Returns metadata, the working-version pointer and the sole current-publication pointer. Read nested versions for graph content and validation issues.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

Responses

Response samples

Content type
application/json

WorkflowParent

{
  • "id": "00000000-0000-4000-8000-000000000030",
  • "name": "Follow up with new people",
  • "description": "Creates a follow-up task for every new person.",
  • "is_enabled": false,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0
}

Delete a workflow

Requires the 'workflows:manage' grant. Removes a workflow from management views while retaining published history. Rejects deletion while admitted runs lack a confirmed terminal outcome.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a workflow

Requires the 'workflows:manage' grant. Merge metadata or enablement. Null clears description; changing it does not create a draft. Update executable content through the nested working version. Disabling stops future admissions; admitted runs continue. Null is rejected for required fields; arrays replace as a whole.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

Request Body schema:
required
name
string [ 1 .. 255 ] characters
description
string or null [ 1 .. 1000 ] characters

Plain-text description, at most 1000 characters after trimming. Null clears it and a blank value returns 422. Changing it does not create a draft or need publishing.

is_enabled
boolean
lock_version
integer or null <int64> >= 0

Stale values return 409; omitted or null skips the precondition.

Responses

Request samples

Content type
Example

RenameWorkflow

{
  • "name": "Customer follow-up",
  • "lock_version": 0
}

Response samples

Content type
application/json

WorkflowParent

{
  • "id": "00000000-0000-4000-8000-000000000030",
  • "name": "Follow up with new people",
  • "description": "Creates a follow-up task for every new person.",
  • "is_enabled": false,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "draft_version_id": "00000000-0000-4000-8000-000000000040"
}

Get a workflow version

Requires the 'workflows:manage' grant. Returns graph content, layout and validation for a working version, or the immutable snapshot for a published version. is_current identifies the sole current publication; earlier publications remain history.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

version_id
required
string <uuid>

Version UUID belonging to this workflow

Responses

Response samples

Content type
application/json

PublishedVersion

{
  • "id": "00000000-0000-4000-8000-000000000040",
  • "workflow_id": "00000000-0000-4000-8000-000000000030",
  • "version_number": 1,
  • "name": "Follow up with new people",
  • "published_at": "2023-02-14T10:00:00Z",
  • "definition": {
    },
  • "layout": {
    },
  • "interpreter_version": 1,
  • "action_version": 1,
  • "state": "published",
  • "is_current": true,
  • "lock_version": 2,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "validation_issues": [ ]
}

Delete a working workflow version

Requires workflows:manage. Deletes only an unpublished, unreferenced working version. Published versions remain immutable history. The allocated version number is never reused.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

version_id
required
string <uuid>

Working version UUID belonging to this workflow

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a working workflow version

Requires workflows:manage. Merge definition and layout; arrays replace whole sets and null cannot clear required structures. Published versions return 409. Incomplete valid graph shapes can be saved with validation_issues; publication requires all blockers to be resolved. The version lock is independent of the parent metadata lock.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in this tenant

version_id
required
string <uuid>

Working version UUID belonging to this workflow

Request Body schema: application/merge-patch+json
required
object (WorkflowDefinitionUpdate)

Merge fields into a working version definition. Arrays replace as a whole; null is rejected. Max 50 triggers, 20 actions, 100 edges, 32 tokens per action and 64 KiB serialized definition.

object (WorkflowLayoutPatch)

Omitted positions remain unchanged. An empty nodes array clears positions. Null is rejected. Max 100 positions and 64 KiB serialized layout.

lock_version
integer or null <int64> >= 0

Working version precondition, independent of the parent lock. Stale values return 409; omitted or null skips the check.

Responses

Request samples

Content type
application/merge-patch+json
Example

SaveDefinition

{
  • "lock_version": 0,
  • "definition": {
    }
}

Response samples

Content type
application/json

SavedWorkingVersion

{
  • "id": "00000000-0000-4000-8000-000000000040",
  • "workflow_id": "00000000-0000-4000-8000-000000000030",
  • "version_number": 1,
  • "name": "Follow up with new people",
  • "definition": {
    },
  • "layout": {
    },
  • "interpreter_version": 1,
  • "action_version": 1,
  • "state": "draft",
  • "is_current": false,
  • "lock_version": 1,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "validation_issues": [ ]
}

List available workflow tools

Requires workflows:manage. Returns available exact contracts, filtered by current tool grants and sorted by name/version. Does not execute tools. supported_step_kinds identifies the supported consumers: Scripts support record and Tour SDK tools; Agents support READ tools plus native web.search@1 and web.fetch@1. Native web discovery requires workflows:code:execute. Scripts may explicitly select local writes. No pagination or cache.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

NoPermittedTools

{
  • "items": [ ]
}

Describe a Task action's field contracts

Requires workflows:manage and tasks:read for Read, or tasks:write for Create/Update. Select definitions from Task definition discovery. Custom input names are stable attribute UUIDs; native inputs retain their names. Read outputs expose typed custom data by slug. No records are read and no cache is retained.

Authorizations:
BearerAuth
path Parameters
definition_id
required
string <uuid>

Concrete Simple or Visit Task definition UUID

query Parameters
action
required
string
Enum: "create_task" "read_task" "update_task"

Task action whose authoring contract to describe

Responses

Response samples

Content type
application/json

simpleTask

{
  • "type": "create_task",
  • "input_schema": {
    },
  • "output_schema": {
    }
}

List workflow references to a resource

Requires workflows:manage and tour-templates:read for template targets, tasks:read for Task targets, or objects:configuration:read for Object schema targets. Current includes active drafts, publications (also paused workflows), and origins of non-deleted workflows. All includes retained versions and deleted workflows. Origins do not block deletion. Task schema and required fixed relationship dependencies remain blocking in retained history; other historical references do not. Results are ordered by workflow name/ID, version descending, source ID and reference ID. Deleted targets may retain reference history.

Authorizations:
BearerAuth
query Parameters
target_type
required
string
Enum: "tour_template" "object_definition" "object_attribute" "task_definition" "task_relationship_record"

Resource type

target_id
required
string <uuid>

Resource UUID

object_id
string <uuid>

Required for object_attribute (owning definition), or task_relationship_record (target definition)

scope
string
Default: "current"
Enum: "current" "all"

Current authoring references or all retained history

blocks_deletion
boolean

Filter by the current deletion-blocking policy

page
integer <int32> >= 0
Default: 0

Page number, starting at 0. Defaults to 0; must be nonnegative.

size
integer <int32> [ 1 .. 100 ]
Default: 20

Number of references per page, from 1 to 100. Defaults to 20.

Responses

Response samples

Content type
application/json
Example

EmptyReferences

{
  • "items": [ ],
  • "page": {
    }
}

List available workflow objects

Requires workflows:manage. Tenant-wide object metadata, sorted by English name or slug with UUID tie-breaker. purpose=trigger excludes built-in objects. purpose=record includes structurally supported record-operation targets, including eligible built-ins. Does not read records or grant record access. No cache.

Authorizations:
BearerAuth
query Parameters
search
string <= 255 characters

Literal search across slug and translated names; blank is invalid

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

purpose
string
Default: "trigger"
Enum: "trigger" "record"

Object eligibility for a trigger or record operation

Responses

Response samples

Content type
application/json

AvailableObjects

{
  • "items": [
    ],
  • "page": {
    }
}

Describe a record step's field contracts

Requires workflows:manage and objects:records:read plus ordinary object READ ACL. Selecting writable fields also requires objects:records:update and object WRITE ACL. Returns object/field choices, exact projected output schema and canonical input schemas without reading records. At most 512 distinct IDs per selection; omit empty selections. Incomplete related scopes are allowed here; publication separately validates the full explicit closure. No cache.

Authorizations:
BearerAuth
path Parameters
object_id
required
string <uuid>

UUID of the custom object whose field contracts are being described

query Parameters
readable_attribute_ids
Array of strings <uuid> [ 1 .. 512 ] items [ items <uuid > ]

Selected readable attribute UUIDs. Repeat this plural query key once per value; CSV is rejected. At most 512 distinct values; omit for none.

writable_attribute_ids
Array of strings <uuid> [ 1 .. 512 ] items [ items <uuid > ]

Selected writable attribute UUIDs. Repeat this plural query key once per value; CSV is rejected. At most 512 distinct values; omit for none.

Responses

Response samples

Content type
application/json

UnselectedFields

{
  • "object": {
    },
  • "fields": [ ],
  • "output_schema": {
    },
  • "writable_fields": [ ]
}

List workflow trigger fields

Requires workflows:manage. Scalar trigger values for mappings, conditions and changed-field filters: text, number, boolean and date_time. Title tokens require text fields. display_name comes first, then attributes by slug. Does not read records. No cache.

Authorizations:
BearerAuth
path Parameters
object_id
required
string <uuid>

Custom-object UUID in this tenant

Responses

Response samples

Content type
application/json

AvailableFields

{
  • "items": [
    ]
}

Get workflow authoring capabilities

Requires workflows:manage. Returns implemented trigger/action types, publication limits, Script runtime limits and Agent output modes, budget ceilings and exact model configurations. Does not read records, contact providers, check worker health or grant execution permission. Tool selection remains separately grant-filtered at /workflows/tools; publication and execution validate current authority. Existing versions retain their frozen settings; provider rate estimates are captured per dispatch. No cache.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

SupportedCapabilities

{
  • "format_version": 1,
  • "trigger_types": [
    ],
  • "action_types": [
    ],
  • "task_actions": [ ],
  • "tour_actions": [ ],
  • "limits": {
    },
  • "scripts": {
    },
  • "agents": {
    }
}

Get compact workflow authoring context

Requires workflows:manage. Resolve one exact custom-object UUID or slug and its scalar trigger fields in one read. An optional assignee search returns the first five candidates with pagination metadata. Include capabilities for Script/Agent limits and models; tools for at most seven grant-filtered SDK/native contracts; record_schema for exact field/choice/read/write contracts. record_schema also requires objects:records:read plus object READ ACL; writable selections require objects:records:update plus object WRITE ACL. Does not read records, execute steps or change configuration. Existing step-version contracts remain available from the version read endpoints. No cache.

Authorizations:
BearerAuth
query Parameters
object_ref
required
string [ 1 .. 255 ] characters

Exact custom-object slug or UUID

assignee_search
string [ 1 .. 255 ] characters

Optional literal assignee name/email search, returning the first five matches

include
Array of strings [ 1 .. 3 ] items
Items Enum: "capabilities" "record_schema" "tools"

Optional metadata parts; repeat once per distinct value

readable_attribute_ids
Array of strings <uuid> [ 1 .. 512 ] items [ items <uuid > ]

Readable attribute UUIDs for included record_schema; at most 512 distinct values

writable_attribute_ids
Array of strings <uuid> [ 1 .. 512 ] items [ items <uuid > ]

Writable attribute UUIDs for included record_schema; at most 512 distinct values

Responses

Response samples

Content type
application/json

BasicContext

{
  • "object": {
    },
  • "trigger_fields": [
    ]
}

List workflow assignees

Requires workflows:manage. All non-deleted tenant users accepted by Task assignment, including inactive, API-only and service-account users. Independent of users:read. Fixed case-insensitive display-name order (trimmed first and last names, email fallback), then UUID. Answering a human question has separate active-human restrictions. No cache.

Authorizations:
BearerAuth
query Parameters
search
string <= 255 characters

Literal case-insensitive first-name, last-name, full-name or email search; omitted lists all eligible users, blank is invalid

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

Responses

Response samples

Content type
application/json

AvailableAssignees

{
  • "items": [ ],
  • "page": {
    }
}

vehicle-records

Native vehicles scoped by Vehicle definition

List vehicles in a definition

List vehicles in a definition. Repeat include to expand named relationship pointers by one level under record. A 10-second execution deadline also covers canonical display-name search.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page number

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

sort
Array of strings

Common fields and sortable definition attributes (is_sortable); one to-one relationship.field hop. Repeat field:direction criteria; default created_at:desc with an id tie-breaker.

search
string

Literal case-insensitive substring of canonical display_name (maximum 256 characters). Applied before count and pagination.

include
Array of strings

Relationship attributes to expand one level. Repeat include for multiple relationships; unknown names return 422 at #/include.

Responses

Response samples

Content type
application/json

bicycle

{
  • "items": [
    ],
  • "page": {
    }
}

Create a vehicle in a definition

Create a vehicle in a definition.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

Request Body schema: application/json
required
object

Definition-owned attribute values, including relationships and inline references. Omitted attributes receive their configured defaults.

property name*
additional property
any

Responses

Request samples

Content type
application/json

bicycle

{
  • "data": {
    }
}

Response samples

Content type
application/json

bicycle

{
  • "id": "aaaaaaaa-cccc-4ccc-8ccc-dddddddddddd",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "natural_id": "BIKE-7",
  • "display_name": "BIKE-7",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "data": {
    }
}

Query records related to a vehicle

Queries the full linked set and returns canonical target records in kind-discriminated wrappers. Uses the target collection grammar: flat attributes for a concrete definition, common fields for the Vehicle family. Target read access is checked before any result or count. Read-only, with a 10-second wall-clock deadline (503 records/query-timeout).

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

vehicle_id
required
string <uuid>

Vehicle UUID

attribute_ref
required
string

Relationship attribute UUID or slug

Request Body schema: application/json
required
object

Filter tree evaluated against the target collection's attributes (Vehicle families accept common fields only). Relationship filters may nest up to four levels.

sort
Array of strings

Sort clauses field:asc|desc. Direct fields are discovered through is_sortable; one-to-one paths use relationship.field:asc|desc. To-many and chained paths are rejected. Default: created_at:desc.

page
integer <int32> [ 0 .. 21474836 ]
Default: 0

Page number (0-based, max 21474836).

size
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

Responses

Request samples

Content type
application/json

query

{
  • "sort": [
    ],
  • "page": 0,
  • "size": 20
}

Response samples

Content type
application/json

records

{
  • "items": [
    ],
  • "page": {
    }
}

Query vehicles in a definition

Uses the same flat attribute filter and sort grammar as Objects. Filters and sorting precede count and pagination. Relationship targets require read access, including empty collections. Read-only, with a 10-second wall-clock deadline (503 records/query-timeout).

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

Request Body schema: application/json
required
object

Filter tree with and/or arrays, not, and field operator objects. Operators are eq/ne/in/gt/gte/lt/lte/contains/starts_with/ends_with/is_null where applicable. Maximum four filter levels. Scoped queries also accept relationship sub-filters. Aggregate fields: id, definition_id, natural_id, created_at, updated_at.

sort
Array of strings

field:asc|desc clauses (bare field means asc). Scoped queries allow sortable attribute slugs and one to-one relationship.field hop. Aggregate queries allow only common fields. Default created_at:desc, with stable id tiebreaker.

search
string <= 256 characters

Literal case-insensitive substring of canonical display_name, applied before count and pagination. Trimmed; blank returns 422.

include
Array of strings

Relationship attributes to expand one level. Expansion adds the canonical target record under record; relationships inside it remain compact.

page
integer <int32> [ 0 .. 21474836 ]
Default: 0

Zero-based page number.

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page.

Responses

Request samples

Content type
application/json

query

{
  • "filter": {
    },
  • "sort": [
    ],
  • "page": 0,
  • "size": 20
}

Response samples

Content type
application/json

records

{
  • "items": [
    ],
  • "page": {
    }
}

Query vehicles across definitions

Only id, definition_id, natural_id, created_at and updated_at are queryable. Filtering definition_id never enables definition-specific filters or sorts. Search matches canonical display names across definitions. Read-only, with a 10-second wall-clock deadline (503 records/query-timeout).

Authorizations:
BearerAuth
Request Body schema: application/json
required
object

Filter tree with and/or arrays, not, and field operator objects. Operators are eq/ne/in/gt/gte/lt/lte/contains/starts_with/ends_with/is_null where applicable. Maximum four filter levels. Scoped queries also accept relationship sub-filters. Aggregate fields: id, definition_id, natural_id, created_at, updated_at.

sort
Array of strings

field:asc|desc clauses (bare field means asc). Scoped queries allow sortable attribute slugs and one to-one relationship.field hop. Aggregate queries allow only common fields. Default created_at:desc, with stable id tiebreaker.

search
string <= 256 characters

Literal case-insensitive substring of canonical display_name, applied before count and pagination. Trimmed; blank returns 422.

include
Array of strings

Relationship attributes to expand one level. Expansion adds the canonical target record under record; relationships inside it remain compact.

page
integer <int32> [ 0 .. 21474836 ]
Default: 0

Zero-based page number.

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page.

Responses

Request samples

Content type
application/json

query

{
  • "filter": {
    },
  • "page": 0,
  • "size": 20
}

Response samples

Content type
application/json

records

{
  • "items": [
    ],
  • "page": {
    }
}

Get a vehicle in a definition

Get a vehicle in a definition. Repeat include to expand named relationship pointers by one level under record.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

vehicle_id
required
string <uuid>

Native vehicle UUID

query Parameters
include
Array of strings

Relationship attributes to expand one level. Repeat include for multiple relationships; unknown names return 422 at #/include.

Responses

Response samples

Content type
application/json

bicycle

{
  • "id": "aaaaaaaa-cccc-4ccc-8ccc-dddddddddddd",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "natural_id": "BIKE-7",
  • "display_name": "BIKE-7",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "data": {
    }
}

Delete a vehicle record

Permanently delete a Vehicle in its concrete definition. Requires vehicles:delete. Active or ended device connection history, BW/ร–AMTC tour history and remaining ร–AMTC branch assignments return 409. Successful deletion removes attribute values, tags, skills, locations and relationship edges atomically and emits vehicle.deleted. No body or version is accepted.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

vehicle_id
required
string <uuid>

Native vehicle UUID

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update vehicle attribute values

Omitted fields stay unchanged. Null clears an optional attribute within data. data cannot be null. Attribute changes advance one shared lock_version; a semantic no-op leaves it unchanged. BW active-tour restrictions apply.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

vehicle_id
required
string <uuid>

Native vehicle UUID

Request Body schema:
required
object

Supplied attributes replace their values; null clears a clearable attribute. Empty object changes nothing.

lock_version
integer or null <int64> >= 0

Optional version precondition; stale versions return 409.

Responses

Request samples

Content type

bicycle

{
  • "lock_version": 0,
  • "data": {
    }
}

Response samples

Content type
application/json

bicycle

{
  • "id": "aaaaaaaa-cccc-4ccc-8ccc-dddddddddddd",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "natural_id": "BIKE-7",
  • "display_name": "BIKE-7",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "data": {
    }
}

List related records for a vehicle

Returns canonical target records in kind-discriminated wrappers, ordered by UUID. Target read permission is required before records or counts are returned. Accepts a forward or generated reverse relationship attribute.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

vehicle_id
required
string <uuid>

Native vehicle UUID

attribute_ref
required
string

Relationship attribute UUID or slug

query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page number

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

Responses

Response samples

Content type
application/json

relatedVehicles

{
  • "items": [
    ],
  • "page": {
    }
}

Get a vehicle by a unique attribute

Lookup inside one definition using a declared unique scalar attribute (config.is_unique). Attribute UUIDs and slugs are accepted. Text matches the stored key exactly; numeric values parse as decimals and choices accept their value or UUID. Plate and VIN are not normalized or implicitly unique. Returns the canonical Vehicle record.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

attribute_ref
required
string

Unique attribute UUID or slug

query Parameters
attribute_value
required
string

Required non-blank key. Query encoding preserves URL path delimiters.

Responses

Response samples

Content type
application/json

bicycle

{
  • "id": "aaaaaaaa-cccc-4ccc-8ccc-dddddddddddd",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "natural_id": "BIKE-7",
  • "display_name": "BIKE-7",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "data": {
    }
}

List vehicles across definitions

List vehicles across definitions using common fields only. A 10-second execution deadline also covers canonical display-name search.

Authorizations:
BearerAuth
query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page number

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

sort
Array of strings

Native fields only: id, natural_id, definition_id, created_at, updated_at. Repeat field:direction criteria; default created_at:desc with an id tie-breaker.

search
string

Literal case-insensitive substring of canonical display_name (maximum 256 characters). Applied before count and pagination.

Responses

Response samples

Content type
application/json

bicycle

{
  • "items": [
    ],
  • "page": {
    }
}

devices

Devices

Get workspace Device settings

Returns workspace enrollment settings and the default Tourfold app location policy. Device overrides take precedence. Use lock_version when updating to detect concurrent edits.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

WorkspaceDeviceSettings

{
  • "admin_managed_devices": false,
  • "app_location_tracking_policy": "continuous",
  • "lock_version": 0
}

Update workspace Device settings

Merge patch: omission preserves a setting; null is rejected for required settings. Device overrides take precedence over the workspace location policy.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
admin_managed_devices
boolean

Require administrator provisioning for Device enrollment. Cannot be null.

app_location_tracking_policy
string
Enum: "disabled" "during_work" "continuous"

Default Tourfold app GPS collection policy. Cannot be null.

lock_version
integer or null <int64>

Optional version; stale values return 409. Omission or null skips the check.

Responses

Request samples

Content type
application/merge-patch+json

UpdateAppLocationPolicy

{
  • "app_location_tracking_policy": "during_work",
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedWorkspaceDeviceSettings

{
  • "admin_managed_devices": false,
  • "app_location_tracking_policy": "during_work",
  • "lock_version": 1
}

vehicle-locations

Canonical Vehicle position and source status

Read the Vehicle's current position and observation time

Returns 200 with no location when unknown. Stale positions from the selected association are retained. Deselecting a source retains its last-known fix but prevents it from supplying new observations. Observation age can be derived from location.located_at when present. The selected association and position provenance are separate.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Vehicle definition UUID or slug

vehicle_id
required
string <uuid>

Native vehicle UUID

Responses

Response samples

Content type
application/json

example

{
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "source_status": "selected",
  • "source": {
    },
  • "location": {
    },
  • "vehicle_association_id": "00000000-0000-4000-8000-000000000011"
}

Measure Units

Tenant capacity measure-unit registry (kg, mยณ, litres, โ€ฆ)

List measure units

Returns measure units ordered by name, paginated.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

CapacityUnitsPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create a measure unit

Creates a tenant measure unit with a unique name and symbol.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Human-readable name, e.g. "Kilogram"

symbol
required
string [ 1 .. 64 ] characters

Symbol, e.g. "kg"

Responses

Request samples

Content type
application/json

CreateKilogramsUnit

{
  • "name": "Kilograms",
  • "symbol": "kg"
}

Response samples

Content type
application/json

CreatedKilogramsUnit

{
  • "id": "00000000-0000-4000-8000-000000006501",
  • "name": "Kilograms",
  • "symbol": "kg",
  • "created_at": "2026-08-20T08:20:00Z",
  • "updated_at": "2026-08-20T08:20:00Z",
  • "lock_version": 0
}

Get a measure unit by id

Returns one tenant measure unit by its UUID.

Authorizations:
BearerAuth
path Parameters
measure_unit_id
required
string <uuid>

UUID of the measure unit.

Responses

Response samples

Content type
application/json

KilogramsUnit

{
  • "id": "00000000-0000-4000-8000-000000006501",
  • "name": "Kilograms",
  • "symbol": "kg",
  • "created_at": "2026-08-20T08:20:00Z",
  • "updated_at": "2026-08-20T08:20:00Z",
  • "lock_version": 0
}

Delete a measure unit

Permanently removes a tenant measure unit. Refused with 409 while any object, task or vehicle definition attribute (capacity with unit_kind: measure, or measure) still references it.

Authorizations:
BearerAuth
path Parameters
measure_unit_id
required
string <uuid>

UUID of the measure unit.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a measure unit

Partial update: omitted fields remain unchanged.

Authorizations:
BearerAuth
path Parameters
measure_unit_id
required
string <uuid>

UUID of the measure unit.

Request Body schema: application/merge-patch+json
required
name
string [ 1 .. 255 ] characters

Human-readable name, e.g. "Kilogram". Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” name is required and cannot be cleared.

symbol
string [ 1 .. 64 ] characters

Symbol, e.g. "kg". Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” symbol is required and cannot be cleared.

lock_version
integer or null <int64>

Lock version for optimistic locking

Responses

Request samples

Content type
application/merge-patch+json

UpdateKilogramsName

{
  • "name": "Kilograms (kg)",
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedKilogramsUnit

{
  • "id": "00000000-0000-4000-8000-000000006501",
  • "name": "Kilograms (kg)",
  • "symbol": "kg",
  • "created_at": "2026-08-20T08:20:00Z",
  • "updated_at": "2026-08-20T09:20:00Z",
  • "lock_version": 1
}

Tour Stops

Ordered standalone and task-backed destinations

List all tour stops

Requires tours:read, or tours:read-own for a published Tour containing the current user (checked first; concealed or unknown Tours return 404). Returns every stop in position order; maximum 500. When any stop is task_visit or has non-empty task_ids, also requires tasks:read (failing with 403 access-denied, reason missing_grant and required_grants [tasks:read]).

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent tour UUID

Responses

Response samples

Content type
application/json

Success

{
  • "items": [
    ]
}

Append a standalone stop

Requires tours:update, or tours:execute-own for an own ad-hoc tour. Task stops are created by assigning visit tasks.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent tour UUID

Request Body schema: application/json
required
required
FixedLocationInput (object) or FixedLocationInput (object) (FixedLocationInput)

Fixed location: both coordinates or an address with street and country_code. Tracking must be resolved and removed before copying.

Any of
lat
required
number <double> [ -90 .. 90 ]

Latitude in WGS84 degrees

lon
required
number <double> [ -180 .. 180 ]

Longitude in WGS84 degrees

address_label
string [ 1 .. 1000 ] characters

Optional human-readable destination label

street
string [ 1 .. 1000 ] characters

Street and house number

street_additional
string [ 1 .. 1000 ] characters

Additional address line

city
string [ 1 .. 1000 ] characters

City or locality

region
string [ 1 .. 1000 ] characters

State or region

postal_code
string [ 1 .. 1000 ] characters

Postal code

country_code
string [ 1 .. 1000 ] characters

Country code

located_at
string <date-time>

Time the position was observed; never the copy time

Responses

Request samples

Content type
application/json

Request

{
  • "location": {
    }
}

Response samples

Content type
application/json

Success

{
  • "id": "a1b937f0-cdea-48aa-b8b7-c24ca6a6de26",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "type": "standalone",
  • "position": 0,
  • "location": {
    },
  • "status": "open",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "task_ids": [ ]
}

Combine two stops

Requires tours:update or own ad-hoc planning access. Moves every Task assignment from the source stop to the destination, removes the source, and compacts the order atomically. The destination keeps its location and lifetime. No Task is changed. Combining explicitly removes the source, including a dispatcher-created source; the destination keeps its existing completion state.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent Tour UUID

stop_id
required
string <uuid>

Destination stop UUID to keep

Request Body schema: application/json
required
source_stop_id
required
string <uuid>

A different stop in the same tour

lock_version
integer or null <int64> >= 0

Parent Tour version. Omitted or null skips the precondition; stale versions return 409.

Responses

Request samples

Content type
application/json

Request

{
  • "source_stop_id": "686e3665-4c5a-42aa-9f6c-8bc606f66c1a",
  • "lock_version": 2
}

Response samples

Content type
application/json

Combined

{
  • "id": "a1b937f0-cdea-48aa-b8b7-c24ca6a6de26",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "type": "task_visit",
  • "position": 0,
  • "task_ids": [
    ],
  • "location": {
    },
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1
}

Get a tour stop

Requires tours:read, or tours:read-own for a published Tour containing the current user (checked first; concealed or unknown Tours and stops return 404). The planned location belongs to the stop; task_ids identifies all grouped Tasks. When the stop is task_visit or has non-empty task_ids, also requires tasks:read (failing with 403 access-denied, reason missing_grant and required_grants [tasks:read]).

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent tour UUID

stop_id
required
string <uuid>

Stop UUID belonging to this tour

Responses

Response samples

Content type
application/json

Success

{
  • "id": "a1b937f0-cdea-48aa-b8b7-c24ca6a6de26",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "type": "standalone",
  • "position": 0,
  • "location": {
    },
  • "status": "open",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "task_ids": [ ]
}

Delete a standalone stop

Requires tours:update or own ad-hoc planning access. Task-backed stops are removed through task assignment. Dispatcher-created stops with assignments return 409 until unassigned.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent tour UUID

stop_id
required
string <uuid>

Stop UUID belonging to this tour

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a stop

Requires tours:update or own ad-hoc planning access for location edits. Status-only edits also allow tours:execute-own for participants. The planned location of task-backed stops is editable, but their completion is controlled by the assigned Tasks.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent tour UUID

stop_id
required
string <uuid>

Stop UUID belonging to this tour

Request Body schema:
required
object (UpdateFixedLocation)

Merge fields into the current location. Omit to preserve; null clears a field. The merged location must remain complete.

status
string
Enum: "open" "done"
lock_version
integer or null <int64> >= 0

Stop version, not parent tour version. Omitted or null skips the precondition.

Responses

Request samples

Content type

Request

{
  • "status": "done",
  • "lock_version": 0
}

Response samples

Content type
application/json

Success

{
  • "id": "a1b937f0-cdea-48aa-b8b7-c24ca6a6de26",
  • "tour_id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "type": "standalone",
  • "position": 0,
  • "location": {
    },
  • "status": "done",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "task_ids": [ ]
}

Grants

Grant listing API.

List grants

Returns the list of grants available for roles.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

GrantListResponse

{
  • "items": [
    ]
}

vehicle-device-associations

Device assignment lifecycle and history

List device assignments and history

Fixed ordering: started_at descending, then id ascending. By default only active episodes are returned. Optional vehicle_id, device_id, and operational filters combine with AND.

Authorizations:
BearerAuth
query Parameters
vehicle_id
string <uuid>
device_id
string <uuid>
operational
boolean
lifecycle
string
Default: "current"
Enum: "current" "all"
page
integer <int32> >= 0
Default: 0
size
integer <int32> [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json

example

{
  • "items": [ ],
  • "page": {
    }
}

Attach a device to a Vehicle

Creates a fixed or portable association, or selects an operational work Device. The first configured tracker or fixed tablet is selected automatically; portable Devices require explicit source selection. Existing plugin work-Device rules take precedence. A matching active pair and configuration returns 200; contradictory create intent conflicts.

Authorizations:
BearerAuth
Request Body schema: application/json
required
vehicle_id
required
string <uuid>
device_id
required
string <uuid>
association_mode
string
Enum: "fixed" "portable"

Required unless operational is true, in which case the plugin's operational mode applies by default.

operational
boolean

Select this Device as the Vehicle's operational work Device (available when an enabled plugin uses operational work Devices).

is_location_source
boolean

Omitted applies source defaults. Explicit selection must respect tracker/fixed priority.

is_preferred_fixed_source
boolean

Choose this fixed app Device for GPS when no tracker has priority.

Responses

Request samples

Content type
application/json

device

{
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "device_id": "00000000-0000-4000-8000-000000000002",
  • "association_mode": "portable",
  • "is_location_source": true
}

Response samples

Content type
application/json

example

{
  • "id": "00000000-0000-4000-8000-000000000011",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "device_id": "00000000-0000-4000-8000-000000000002",
  • "association_mode": "portable",
  • "started_at": "2023-02-14T10:00:00Z",
  • "operational": false,
  • "is_location_source": true,
  • "is_preferred_fixed_source": false,
  • "lock_version": 0,
  • "device_details_restricted": false
}

Transfer a device to another Vehicle

Optionally checks lock_version against the active episode. An ended episode always conflicts. Closes it and creates a new episode atomically. A target equal to the current Vehicle returns 200 without creating history. The required association_mode configures the new Vehicle pair; source defaults are validated at the destination. A same-Vehicle request must match the existing mode; use PATCH to change or confirm it. Plugin rules remain enforced.

Authorizations:
BearerAuth
path Parameters
association_id
required
string <uuid>

UUID of the device assignment episode, including ended episodes

Request Body schema: application/json
required
vehicle_id
required
string <uuid>
association_mode
required
string
Enum: "fixed" "portable"
lock_version
integer <int64> >= 0

Responses

Request samples

Content type
application/json

handover

{
  • "vehicle_id": "00000000-0000-4000-8000-000000000003",
  • "association_mode": "portable",
  • "lock_version": 0
}

Response samples

Content type
application/json

example

{
  • "id": "00000000-0000-4000-8000-000000000011",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "device_id": "00000000-0000-4000-8000-000000000002",
  • "association_mode": "portable",
  • "started_at": "2023-02-14T10:00:00Z",
  • "operational": false,
  • "is_location_source": true,
  • "is_preferred_fixed_source": false,
  • "lock_version": 0,
  • "device_details_restricted": false
}

End a device assignment

Ends the interval immediately, retaining history and the last-known vehicle position. The ended source cannot supply new positions. Repeating end is a no-op. Operational plugin restrictions still apply.

Authorizations:
BearerAuth
path Parameters
association_id
required
string <uuid>

UUID of the device assignment episode, including ended episodes

Responses

Response samples

Content type
application/json

example

{
  • "id": "00000000-0000-4000-8000-000000000011",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "device_id": "00000000-0000-4000-8000-000000000002",
  • "association_mode": "portable",
  • "started_at": "2023-02-14T10:00:00Z",
  • "ended_at": "2023-02-14T11:00:00Z",
  • "operational": false,
  • "is_location_source": false,
  • "is_preferred_fixed_source": false,
  • "lock_version": 1,
  • "device_details_restricted": false
}

Read one assignment episode

Ended episodes remain addressable.

Authorizations:
BearerAuth
path Parameters
association_id
required
string <uuid>

UUID of the device assignment episode, including ended episodes

Responses

Response samples

Content type
application/json

example

{
  • "id": "00000000-0000-4000-8000-000000000011",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "device_id": "00000000-0000-4000-8000-000000000002",
  • "association_mode": "portable",
  • "started_at": "2023-02-14T10:00:00Z",
  • "operational": false,
  • "is_location_source": true,
  • "is_preferred_fixed_source": false,
  • "lock_version": 0,
  • "device_details_restricted": false
}

Update association mode and source selection

Management updates may configure mode and fixed preference. A human with vehicles:device-location:use-self may instead change only is_location_source and lock_version for their proven current Device on an authorized Tour, using X-Device-Authorization. This path needs no vehicles:read grant and returns only the callerโ€™s own association and source flags; it does not grant management reads. The source and preferred fixed Device are changed atomically; tracker/fixed priority and plugin work guards apply. An ended association conflicts. Source changes advance versions of affected associations.

Authorizations:
BearerAuth
path Parameters
association_id
required
string <uuid>

Active Vehicleโ€“Device association UUID

header Parameters
X-Device-Authorization
string

Required for narrow current-Device source selection; omitted for management. Missing proof: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Request Body schema: application/merge-patch+json
required
association_mode
string
Enum: "fixed" "portable"
operational
boolean
is_location_source
boolean
is_preferred_fixed_source
boolean
lock_version
integer <int64> >= 0

Responses

Request samples

Content type
application/merge-patch+json

select

{
  • "is_location_source": true,
  • "lock_version": 0
}

Response samples

Content type
application/json

selected

{
  • "id": "00000000-0000-4000-8000-000000000011",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "device_id": "00000000-0000-4000-8000-000000000002",
  • "association_mode": "portable",
  • "started_at": "2023-02-14T10:00:00Z",
  • "operational": false,
  • "is_location_source": true,
  • "is_preferred_fixed_source": false,
  • "lock_version": 0,
  • "device_details_restricted": false
}

Webhooks Catalog

Discover the event types you can subscribe to, and how deliveries are signed.

Webhook Delivery

When events occur in Tourfold, webhook payloads are sent via HTTP POST to your configured endpoint URLs. Each delivery carries these headers:

  • webhook-id: Unique message id (UUID). Stable across retries of the same event โ€” use it to deduplicate at-least-once deliveries.
  • webhook-timestamp: Unix timestamp in seconds at which this delivery attempt was signed.
  • webhook-signature: Signature in the form v1,<base64> (see below).
  • request-id (and correlation-id when available): tracing ids you can quote to support.

Signature Verification

Deliveries are signed following the Standard Webhooks specification โ€” verify them with an official standardwebhooks library for your language, passing your endpoint's secret (the full whsec_... string) and the three webhook-* headers.

Verifying manually instead: the signature is an HMAC-SHA256 over the string {webhook-id}.{webhook-timestamp}.{raw_body} โ€” the three parts joined with a literal dot, where raw_body is the exact request body bytes as received (do not re-serialize the JSON). The HMAC key is the secret after stripping the whsec_ prefix and base64-decoding the remainder.

key            = base64_decode( secret without the "whsec_" prefix )
signed_content = webhook_id + "." + webhook_timestamp + "." + raw_body
expected       = "v1," + base64( hmac_sha256( key, utf8_bytes(signed_content) ) )
valid          = constant_time_compare(expected, webhook_signature_header)

To protect against replay, also reject deliveries whose webhook-timestamp is outside your tolerance window (5 minutes is a common choice).

The secret is returned exactly once โ€” on endpoint creation and on secret rotation.

Body shape

Every delivery has the same envelope: type (the event type), id, event_id, timestamp, payload_version, tenant_id, optional actor and request, and data. The resource itself is at data.object, and data.previous_attributes carries the old values of whatever an edit changed.

data.object always identifies the resource, and within one payload_version its fields are only ever added to โ€” never removed, renamed or retyped. Treat the key set as open and ignore keys you do not recognise.

List subscribable webhook event types

Returns every event type this workspace can subscribe to, as <resource path>.<verb>.

Subscribe to exact names or to patterns: a trailing * after any path prefix (folder.*), a leading * for one verb across all resources (*.created), or * for everything. A wildcard verb widens the path to a prefix; a named verb pins it exactly โ€” so folder.* also matches folder.permissions.updated, while folder.updated does not.

The list is tenant-scoped because it includes one set of event types per object definition, which is the main reason to fetch it at runtime rather than hard-coding it.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

EventTypes

{
  • "items": [
    ]
}

Sms Gateways

Manage SMS gateway configurations per tenant. Gateways are evaluated by priority (0 = primary) for failover. Provider credentials are write-only: responses report them as *_configured flags and never return a value.

List all SMS gateways for the current tenant

Returns gateways ordered by priority (0 = primary). Disabled gateways are included. Credentials are never returned; *_configured flags report whether one is stored.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

GatewaysList

{
  • "items": [
    ]
}

Create a new SMS gateway

Creates a tenant SMS gateway and returns its effective priority and configuration. Every credential of the chosen provider variant is required on create.

Authorizations:
BearerAuth
Request Body schema: application/json
required
enabled
boolean

Whether delivery is enabled; defaults to true.

name
required
string non-empty

Operator-visible gateway name.

priority
integer <int32> >= 0

Zero-based failover position; omit to append.

type
required
string

Gateway provider kind; immutable after creation.

required
object (TwilioGatewayConfig)

Required Twilio credentials and sender configuration.

Responses

Request samples

Content type
application/json

CreateAlpineTwilioGateway

{
  • "name": "Alpine primary SMS",
  • "type": "TWILIO",
  • "priority": 0,
  • "enabled": true,
  • "twilio_config": {
    }
}

Response samples

Content type
application/json

CreateTwilioGateway

{
  • "id": "11111111-2222-3333-4444-555555555555",
  • "name": "Primary Twilio",
  • "type": "TWILIO",
  • "priority": 0,
  • "enabled": true,
  • "lock_version": 0,
  • "twilio_config": {
    }
}

Send a test SMS through a gateway

Sends a test message through the selected gateway synchronously and returns once the gateway has accepted it. Delivery-status updates for the returned tracking id arrive through the SMS_GATEWAY_TEST_RESULT:V1 server-sent event. The outcome is recorded in the SMS report either way.

Authorizations:
BearerAuth
path Parameters
sms_gateway_id
required
string <uuid>

Gateway identifier

Request Body schema: application/json
required
phone_number
required
string non-empty

International recipient number with an explicit '+' country code. Formatted input is normalized to E.164.

Responses

Request samples

Content type
application/json

SendTechnicianTestSms

{
  • "phone_number": "+436641234567"
}

Response samples

Content type
application/json

TestSmsSent

{
  • "tracking_id": "00000000-0000-4000-8000-000000004901"
}

Reorder gateways atomically

Reorders all gateways for the current tenant; request must list every gateway exactly once in the desired order (0 = primary).

Authorizations:
BearerAuth
Request Body schema: application/json
required
gateway_ids
required
Array of strings <uuid> non-empty [ items <uuid > ]

Responses

Request samples

Content type
application/json

PrioritizeGateways

{
  • "gateway_ids": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Get a single SMS gateway

Returns the gateway configuration for the given ID. Credentials are never returned; *_configured flags report whether one is stored.

Authorizations:
BearerAuth
path Parameters
sms_gateway_id
required
string <uuid>

Gateway identifier

Responses

Response samples

Content type
application/json

GatewayResponse

{
  • "id": "11111111-2222-3333-4444-555555555555",
  • "name": "Primary Twilio",
  • "type": "TWILIO",
  • "priority": 0,
  • "enabled": true,
  • "lock_version": 0,
  • "twilio_config": {
    }
}

Delete an SMS gateway

Permanently removes the tenant SMS gateway.

Authorizations:
BearerAuth
path Parameters
sms_gateway_id
required
string <uuid>

Gateway identifier

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update an SMS gateway

Allows partial updates (name, enabled flag, priority). A provided configuration replaces the stored one; credentials omitted from it are kept, credentials provided in it are rotated.

Authorizations:
BearerAuth
path Parameters
sms_gateway_id
required
string <uuid>

Gateway identifier

Request Body schema: application/merge-patch+json
required
lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check

name
string

Display name of the gateway. Omitted leaves the value unchanged; explicit null is rejected (422) โ€” it cannot be cleared.

enabled
boolean

Whether the gateway is enabled. Omitted leaves the value unchanged; explicit null is rejected (422) โ€” it cannot be cleared.

priority
integer <int32>

Evaluation priority (0 = primary). Omitted leaves the value unchanged; explicit null is rejected (422) โ€” it cannot be cleared.

object (TwilioGatewayConfig)

Replaces the whole Twilio configuration when provided (gateway must be of type TWILIO). Omitted leaves the configuration unchanged; explicit null is rejected (422). Secret fields inside the configuration may be omitted to keep the stored values; a provided secret replaces (rotates) the stored one.

object or object or object or object (CustomSmsSettings)

Responses

Request samples

Content type
application/merge-patch+json
Example

DisableGateway

{
  • "lock_version": 0,
  • "enabled": false
}

Response samples

Content type
application/json

UpdateGateway

{
  • "id": "11111111-2222-3333-4444-555555555555",
  • "name": "Renamed Gateway",
  • "type": "TWILIO",
  • "priority": 0,
  • "enabled": false,
  • "lock_version": 1,
  • "twilio_config": {
    }
}

Records

Typed Records API

Batch-create records

Creates many records across objects in one request, with sibling cross-linking via item key + relationship {ref}. The batch is atomic: all records are created in a single transaction, and any failure rolls back the whole batch. At most 100 items per request (422 above the limit).

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
Array of objects (BatchRecordItem) [ 1 .. 100 ] items

Records to create, in order (1..100 items)

Array ([ 1 .. 100 ] items)
object
required
string non-empty

Target object (slug or id)

key
string

Optional cross-link key, unique within the request

required
object

Record data keyed by attribute slug

Responses

Request samples

Content type
application/json

Rtu17WithMaintenanceRequest

{
  • "items": [
    ]
}

Response samples

Content type
application/json

BatchResult

{
  • "records": [
    ]
}

List records

Lists an object's records (paged). The GET surface accepts only the declared pagination, sort, include, and canonical display-name search parameters. Use POST โ€ฆ/records/query for all attribute filtering and boolean/reference composition. Sorting uses repeatable sort=<field>:asc|desc; the default is created_at:desc.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

query Parameters
page
integer [ 0 .. 21474836 ]
Default: 0

Page number (0-based, max 21474836).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

sort
Array of strings
Example: sort=manufacturer.name:asc

Repeated field:asc|desc clauses. Direct fields are discovered through the object definition's is_sortable; one-to-one paths such as manufacturer.name:asc are supported for sortable target fields. To-many and chained relationship paths are rejected. Default: created_at:desc.

include
Array of strings
Example: include=maintenance_requests

Relationship attributes to expand one level. Repeat include for multiple relationships; valid names are relationship attributes in the object definition. Unknown names return 422 at #/include.

search
string [ 0 .. 256 ] characters

Literal case-insensitive substring of canonical display_name, applied before count and pagination. Trims surrounding whitespace; blank returns 422. Percent and underscore are literal. Includes do not affect labels. Complex labels use bounded rendering under the query deadline.

Responses

Response samples

Content type
application/json
Example

RecordPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create a record

Creates one record for an object.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

Request Body schema: application/json
required
required
object

Record data keyed by attribute slug

property name*
additional property
any

Responses

Request samples

Content type
application/json

CreateRtu17

{
  • "data": {
    }
}

Response samples

Content type
application/json

Rtu17Record

{
  • "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 1,
  • "data": {
    }
}

Query related records

Filters, sorts, and pages the records linked through one relationship attribute. Filters may traverse relationships up to four levels. Sorting accepts scalar fields and one to-one relationship path such as manufacturer.name:asc. The default is created_at:desc. Vehicle targets currently support the paginated related-record GET endpoint only; structured queries return 422.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

record_id
required
string <uuid>

Record id.

attribute_ref
required
string

Relationship attribute slug

Request Body schema: application/json
required
object

Filter tree evaluated against the target collection's attributes (Vehicle families accept common fields only). Relationship filters may nest up to four levels.

sort
Array of strings

Sort clauses field:asc|desc. Direct fields are discovered through is_sortable; one-to-one paths use relationship.field:asc|desc. To-many and chained paths are rejected. Default: created_at:desc.

page
integer <int32> [ 0 .. 21474836 ]
Default: 0

Page number (0-based, max 21474836).

size
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

Responses

Request samples

Content type
application/json

OpenRequestsByPriority

{
  • "filter": {
    },
  • "sort": [
    ],
  • "page": 0,
  • "size": 20
}

Response samples

Content type
application/json

RecordPage

{
  • "items": [
    ],
  • "page": {
    }
}

Query records

Powerful query for what GET โ€ฆ/records query params can't express: and/or/not boolean composition and nested relationship / tagsยทskills sub-filters, using the same operator names (eq, ne, in, gt, gte, lt, lte, contains, starts_with, ends_with, is_null). filter grammar: keys at any level AND together; a leaf is { "<attribute>": { "<op>": <value>, โ€ฆ } }; and/or take an array of nodes and not takes a single node; a relationship / reference attribute key takes a nested filter evaluated against the target object's attributes, including further relationship filters, and matches when at least one related record matches (an empty {} matches any related record). A comparison never matches an unset value, so ne and not include records whose value is unset. On a multi-select, in matches any of the values and contains all of them. Nesting is limited to 4 levels. Returns the same { items, page } envelope as GET โ€ฆ/records.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

Request Body schema: application/json
required
search
string [ 0 .. 256 ] characters

Literal case-insensitive substring of the canonical display_name, combined with filter before count and pagination. Surrounding whitespace is trimmed; blank returns 422. Includes do not affect the label. Complex labels are rendered in bounded batches under the query deadline.

object

Filter tree keyed by attribute slug plus and/or/not; operators: eq/ne/in/gt/gte/lt/lte/contains/starts_with/ends_with/is_null. ne and not include records whose value is unset; on a multi-select, in matches any of the values and contains all of them.

sort
Array of strings

Sort clauses field:asc|desc. Direct fields are discovered through is_sortable; one-to-one paths use relationship.field:asc|desc. To-many and chained paths are rejected. Default: created_at:desc.

include
Array of strings

Relationship attributes to expand one level. Expansion adds the canonical target record under record; relationships inside it remain compact.

page
integer <int32> [ 0 .. 21474836 ]
Default: 0

Page number (0-based, max 21474836).

size
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

Responses

Request samples

Content type
application/json
Example

simple comparison

{
  • "filter": {
    }
}

Response samples

Content type
application/json
Example

RecordPage

{
  • "items": [
    ],
  • "page": {
    }
}

Get a record

Fetches one record by id. Repeat include to expand named relationship pointers by one level. Expansion adds the target's canonical record under record; the compact record_id, object, and display_name fields remain present.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

record_id
required
string <uuid>

Record id.

query Parameters
include
Array of strings
Example: include=maintenance_requests

Relationship attributes to expand one level. Repeat include for multiple relationships; valid names are relationship attributes in the object definition. Unknown names return 422 at #/include.

Responses

Response samples

Content type
application/json
Example

Rtu17Record

{
  • "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 1,
  • "data": {
    }
}

Delete a record

Deletes one record by id.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

record_id
required
string <uuid>

Record id.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a record (merge-patch)

JSON Merge Patch (RFC 7386): a key present in data sets it, an omitted key is unchanged, null clears an optional attribute, [] clears an edge set, and a location null clears the entire value. lock_version is validated when provided (409 on mismatch); omitting it skips the concurrency check.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

record_id
required
string <uuid>

Record id.

Request Body schema:
required
object

Partial record data keyed by attribute slug

lock_version
integer or null <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
Example

MarkOperational

{
  • "lock_version": 1,
  • "data": {
    }
}

Response samples

Content type
application/json

Rtu17Record

{
  • "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 1,
  • "data": {
    }
}

List related records

Lists the records linked to this record via the given relationship attribute, paged. Ordering is stable by record id (relationship edges carry no user-facing sort key).

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

record_id
required
string <uuid>

Record id.

attribute_ref
required
string

Relationship attribute slug

query Parameters
page
integer [ 0 .. 21474836 ]
Default: 0

Page number (0-based, max 21474836).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

RecordPage

{
  • "items": [
    ],
  • "page": {
    }
}

Get a record by a unique attribute

Business-key lookup: returns the record whose unique {attribute_ref} equals the attribute_value query parameter without knowing its id. Requires {attribute_ref} to have config.is_unique: true (else 422). Attribute UUIDs and slugs are accepted. Text matches the stored key exactly; numeric values parse as decimals and choices accept their value or UUID.

Authorizations:
BearerAuth
path Parameters
object_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Unique attribute slug or UUID

query Parameters
attribute_value
required
string

Value the unique attribute must equal. Query encoding preserves values containing URL path delimiters.

Responses

Response samples

Content type
application/json

Rtu17Record

{
  • "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  • "definition_id": "11111111-9999-4444-8888-111111111111",
  • "display_name": "Rooftop HVAC Unit RTU-17 (AFS-RTU-17)",
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 1,
  • "data": {
    }
}

vehicle-provider-connection-authorizations

Consent and clearance of provider connections, and the durable requests that ask the provider for them.

List a provider connection's authorization operations

Newest first, then by id. Includes the revocation queued by disconnecting. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

query Parameters
page
integer <int32> >= 0
Default: 0
size
integer <int32> [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json

example

{
  • "items": [
    ],
  • "page": {
    }
}

Ask the provider about a connection's authorization

Queues durable work and answers 202 with it; the worker then calls the provider, and the operation's status is read at Location. authorize can contact the Vehicle's owner, so it first checks whether consent already exists and never sends a second request for an answer that was lost. Repeating the same request_id returns the same operation in its current state. revoke applies to an ended connection: disconnecting already queued it, and asking again restarts a failed revocation. Needs vehicles:read and connected-vehicles:authorizations:write, and the connected-vehicles entitlement.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

Request Body schema: application/json
required
action
required
string
Enum: "authorize" "refresh" "revoke"

authorize asks the provider for consent or clearance and can contact the Vehicle's owner. refresh reads the current state from the provider. revoke withdraws access after the connection ended; disconnecting queues it, and requesting it again restarts a failed revocation.

request_id
required
string <uuid>

Your key for this request. Repeating it returns the same operation instead of asking the provider again; using it for another action conflicts. For revoke, it makes restarting a failed revocation repeatable.

Responses

Request samples

Content type
application/json
Example

authorize

{
  • "action": "authorize",
  • "request_id": "e39fd6a8-909e-450b-a2cb-a04d65d62a5c"
}

Response samples

Content type
application/json
Example

queued

{
  • "id": "00000000-0000-4000-8000-000000000041",
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "action": "authorize",
  • "status": "queued",
  • "requested_at": "2023-02-14T10:00:00Z",
  • "attempts": 0
}

Read a provider connection's authorization

The consent or clearance as last learnt from the provider, and the revocation once the connection ended. Never asks the provider; request refresh for that. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

Responses

Response samples

Content type
application/json
Example

pending

{
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "provider": "DRVN",
  • "status": "pending",
  • "checked_at": "2023-02-14T10:00:05Z",
  • "last_operation": {
    }
}

Read one authorization operation

Progress and outcome. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

authorization_operation_id
required
string <uuid>

UUID of the authorization operation

Responses

Response samples

Content type
application/json

succeeded

{
  • "id": "00000000-0000-4000-8000-000000000041",
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "action": "authorize",
  • "status": "succeeded",
  • "requested_at": "2023-02-14T10:00:00Z",
  • "started_at": "2023-02-14T10:00:04Z",
  • "finished_at": "2023-02-14T10:00:05Z",
  • "attempts": 1,
  • "outcome_status": "pending"
}

Read the provider's raw answer to an authorization operation

The body the provider sent and the HTTP exchange behind it, credentials redacted; empty while no attempt has reached the provider. Needs vehicles:read and connected-vehicles:raw-data:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

authorization_operation_id
required
string <uuid>

UUID of the authorization operation

Responses

Response samples

Content type
application/json

refused

{}

Deleted Events

    Delete event tracking for CDC-style incremental sync with delete detection.
    
    This endpoint allows external systems (e.g., Airbyte connectors) to poll for entity deletions 
    within a time range, enabling downstream systems to remove stale records.
    
    Events are retained for 28 days before automatic cleanup.

List deleted events

        Returns a paginated list of delete events within the specified time range.
        
        Use this endpoint for CDC-style incremental sync to detect which entities have been deleted.
        Events are sorted by `deleted_at` (ascending) with secondary sort by `id` for deterministic pagination.
        
        **Cursor-based incremental sync:**
        - Use `deleted_at` as the cursor field
        - On first sync, use a `deleted_from` timestamp in the past and `deleted_to` as current time
        - On subsequent syncs, use the last `deleted_at` value from the previous sync as the new `deleted_from`
    
Authorizations:
BearerAuth
query Parameters
deleted_from
required
string <date-time>
Example: deleted_from=2024-01-01T00:00:00Z

Lower bound for deleted_at (inclusive, RFC 3339).

deleted_to
required
string <date-time>
Example: deleted_to=2024-01-02T00:00:00Z

Upper bound for deleted_at (exclusive, RFC 3339).

entity_type
string
Example: entity_type=user

Filter by entity type (e.g., user, vehicle, tour). If not specified, returns all entity types.

page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 1000 ]
Default: 100
Example: size=100

Number of elements per page (max 1000). The cap is deliberately higher than the platform default of 100 because sync-style consumers replay deletions in bulk.

Responses

Response samples

Content type
application/json

DeletedEventsListResponse

{
  • "items": [
    ],
  • "page": {
    }
}

Audit Log

Audit log management API. Audit logs can be queried and managed through these endpoints.

List audit logs

Retrieve audit logs with optional filters for time range, scope type, event type, and actor. The scope type / event type pairs recorded in this workspace are listed by listAuditLogEventTypes. Requires 'audit-logs:read' grant.

Authorizations:
BearerAuth
query Parameters
occurred_from
string <date-time>
Example: occurred_from=2024-01-01T00:00:00Z

Lower bound for event occurrence time (inclusive, RFC 3339). Defaults to 1 day ago.

occurred_to
string <date-time>
Example: occurred_to=2024-12-31T23:59:59Z

Upper bound for event occurrence time (exclusive, RFC 3339). Defaults to now.

scope_type
string
Example: scope_type=USER

Filter by scope type, the kind of entity an event applies to (e.g. USER, TENANT, DEVICE). Recorded values are listed by listAuditLogEventTypes.

scope_id
string
Example: scope_id=00000000-0000-4000-8000-000000001002

Filter by the ID of the affected entity (e.g., specific user ID, tour ID, case ID)

event_type
string
Example: event_type=USER_CREATED

Filter by event type (e.g. USER_CREATED, BRAND_UPDATED). Recorded values are listed by listAuditLogEventTypes.

actor_id
string
Example: actor_id=00000000-0000-4000-8000-000000001001

Filter by the ID of the actor who performed the action

page
integer >= 0
Default: 0

Page number (0-based). First page is 0.

size
integer [ 1 .. 1000 ]
Default: 50
Example: size=50

Number of items per page. Maximum allowed is 1000.

sort
Array of strings
Example: sort=scope_type:asc

Repeated sorting criteria in field:direction format. Allowed fields: id, original_event_time, scope_type, event_type, actor_id. Default: original_event_time:desc.

Responses

Response samples

Content type
application/json

AuditLogsResponse

{
  • "items": [
    ],
  • "page": {
    }
}

List audit log event types

List the distinct scope type / event type pairs recorded in this workspace's audit log, for building the scope_type and event_type filter choices of listAuditLogs. Requires 'audit-logs:read' grant.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

AuditLogEventTypesResponse

{
  • "items": [
    ]
}

connected-vehicle-provider-accounts

The workspace's provider accounts (DRVN, High Mobility) as Vehicle connections name them. Their configuration and credentials are managed in the workspace settings.

List the provider accounts Vehicles can be connected through

Every provider account of the workspace, ordered by name, disabled ones included. An account's id is the provider_account_id that connects a Vehicle through it. Needs connected-vehicle-providers:read, connected-vehicle-providers:write or connected-vehicles:create, and the connected-vehicles entitlement.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

accounts

{
  • "items": [
    ]
}

Tours

Generic manual tours and execution

List tours

Requires tours:read, or tours:read-own for published tours containing the current human user. planned_start_from is inclusive and planned_start_to exclusive.

Authorizations:
BearerAuth
query Parameters
search
string

Literal description substring or exact positive tour number

natural_id
integer <int64> >= 1

Exact human tour number

participant_user_id
string <uuid>

Exact participant UUID

publication_status
string
Enum: "draft" "published"

Publication state

execution_status
string
Enum: "not_started" "in_progress" "finished"

Execution state

planned_start_from
string <date-time>

Inclusive planned-start boundary, RFC 3339

planned_start_to
string <date-time>

Exclusive planned-start boundary, RFC 3339

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Page size

sort
string
Default: "natural_id:desc"
Enum: "planned_start_at" "planned_start_at:asc" "planned_start_at:desc" "natural_id" "natural_id:asc" "natural_id:desc" "description" "description:asc" "description:desc" "created_at" "created_at:asc" "created_at:desc" "updated_at" "updated_at:asc" "updated_at:desc" "id" "id:asc" "id:desc"

One field[:asc|desc]: planned_start_at, natural_id, description, created_at, updated_at, id; newest tour number first by default; stable id tie-breaker. Drafts without a start sort last ascending.

Responses

Response samples

Content type
application/json

Success

{
  • "items": [
    ],
  • "page": {
    }
}

Create a draft tour

Requires tours:create. Resolves the named template, or Default for omitted/null tour_template_id, and copies its latest content. Named templates require tour-templates:read and tour_date. Default requires tour_date only for inherited relative planned times. Tasks require tasks:write. Initial vehicles require tours:update plus readable Tour/Vehicle scope; busy Vehicles require per-selection acknowledge_active_use. Numbers are allocated by the server and are never reused.

Authorizations:
BearerAuth
Request Body schema: application/json
required
One of
tour_template_id
required
string <uuid>

Named Tour template UUID; omitted/null applies the protected Default

tour_date
required
string <date>

Calendar date in the template timezone; required for a named template or inherited relative times

description
string or null [ 1 .. 255 ] characters

Omitted inherits; null leaves unset

participant_user_ids
Array of strings <uuid> <= 100 items unique [ items <uuid > ]

Active human users only; defaults to empty. Unique, at most 100.

planned_start_at
string or null <date-time>

Absolute RFC 3339 timestamp; omission inherits, null leaves unset

planned_end_at
string or null <date-time>

Absolute RFC 3339 timestamp; omission inherits, null leaves unset. Must be after the final start when both are set

required_skill_ids
Array of strings <uuid> <= 1000 items unique [ items <uuid > ]

Omission inherits required skills; [] clears them

Array of objects (TourVehicleSelection) <= 100 items

Initial Vehicle assignments; at most 100 unique Vehicles. Requires Tour Vehicle management and Vehicle read authority.

Responses

Request samples

Content type
application/json

Request

{
  • "description": "Morning visits"
}

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "planned_start_at": "2023-02-14T10:00:00Z",
  • "origin": "planned",
  • "publication_status": "draft",
  • "execution_status": "not_started",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "vehicles": [ ]
}

Use a Vehicle on an active Tour

Requires an active Tour, Vehicle read permission and tours:update, or tours:vehicles:assign-own for a participant with Tour read access. Tour execution permission is not required. Device source selection additionally requires devices:vehicles:assign-self and vehicles:device-location:use-self unless configured hardware already supplies location. Coordinates assignment, actual use, participant cleanup and source selection atomically. Device proof supplies the exact observed association. Other active Vehicle use conflicts.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

header Parameters
X-Device-Authorization
string

Required when device_context is supplied; omitted for dispatcher commands without Device context. Missing proof: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Request Body schema: application/json
required
lock_version
integer or null <int64> >= 0
required
object (TourVehicleUse)
object (TourDeviceContext)

Responses

Request samples

Content type
application/json

Request

{
  • "vehicle_use": {
    }
}

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "planned_start_at": "2023-02-14T10:00:00Z",
  • "origin": "planned",
  • "publication_status": "published",
  • "published_at": "2023-02-14T10:00:00Z",
  • "started_at": "2023-02-14T10:01:00Z",
  • "execution_status": "in_progress",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "vehicles": [ ]
}

Start a tour

Requires tours:update or tours:execute-own for a participant. Publish first; every participant and Vehicle must be free of another active tour. Membership, portable cleanup, fixed-Device human session revocation and source selection commit atomically. Device proof requires exact observed episode context. Repeating an already-active Start succeeds only when the requested intent already holds; different Vehicle or source intent conflicts and requires use-vehicle.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

header Parameters
X-Device-Authorization
string

Required when device_context is supplied; omitted for dispatcher commands without Device context. Missing proof: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Request Body schema: application/json
required
lock_version
integer or null <int64> >= 0
object (TourVehicleUse)
object (TourDeviceContext)

Responses

Request samples

Content type
application/json

Request

{
  • "lock_version": 0,
  • "device_context": {
    }
}

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "planned_start_at": "2023-02-14T10:00:00Z",
  • "origin": "planned",
  • "publication_status": "published",
  • "published_at": "2023-02-14T10:00:00Z",
  • "started_at": "2023-02-14T10:01:00Z",
  • "execution_status": "in_progress",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "vehicles": [ ]
}

Publish a tour

Requires tours:update. At least one participant is required. Planned start and end are optional.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

Request Body schema: application/json
required
lock_version
integer or null <int64> >= 0

Omitted or null skips the precondition; stale versions return 409.

Responses

Request samples

Content type
application/json

Request

{
  • "lock_version": 0
}

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "planned_start_at": "2023-02-14T10:00:00Z",
  • "origin": "planned",
  • "publication_status": "published",
  • "published_at": "2023-02-14T10:00:00Z",
  • "execution_status": "not_started",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "vehicles": [ ]
}

Finish a tour

Requires tours:update or tours:execute-own for a participant. All tasks and standalone stops must be done; nothing is completed implicitly.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

Request Body schema: application/json
required
lock_version
integer or null <int64> >= 0

Omitted or null skips the precondition; stale versions return 409.

Responses

Request samples

Content type
application/json

Request

{
  • "lock_version": 0
}

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "planned_start_at": "2023-02-14T10:00:00Z",
  • "origin": "planned",
  • "publication_status": "published",
  • "published_at": "2023-02-14T10:00:00Z",
  • "started_at": "2023-02-14T10:01:00Z",
  • "finished_at": "2023-02-14T11:00:00Z",
  • "execution_status": "finished",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "vehicles": [ ]
}

Start an ad-hoc tour

Requires tours:start-ad-hoc and an active human user. Resolves one effective template (Default for omitted/null tour_template_id), then creates, publishes and starts the Tour and its work atomically. Named templates additionally require tour-templates:read; templates with Tasks require tasks:write. Omitted tour_date uses the template timezone and the command clock. Optional Vehicle use and proven Device context follow the same atomic coordination as planned Start. An active participant conflict includes data.tour_id.

Authorizations:
BearerAuth
header Parameters
X-Device-Authorization
string

Required when device_context is supplied; omitted for dispatcher commands without Device context. Missing proof: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Request Body schema: application/json
required
object (TourVehicleUse)
object (TourDeviceContext)
tour_template_id
string or null <uuid>

Named template UUID; omitted/null applies Default

tour_date
string or null <date>

Calendar date in the template timezone; omission derives it from the command clock

description
string or null [ 1 .. 255 ] characters

Omission inherits; null leaves unset

planned_start_at
string or null <date-time>

Omission inherits; null leaves unset

planned_end_at
string or null <date-time>

Omission inherits; null leaves unset

required_skill_ids
Array of strings <uuid> <= 1000 items unique [ items <uuid > ]

Omission inherits; [] clears requirements

Responses

Request samples

Content type
application/json

Request

{
  • "description": "Ad-hoc visits"
}

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "published_at": "2023-02-14T10:00:00Z",
  • "started_at": "2023-02-14T10:00:00Z",
  • "origin": "ad_hoc",
  • "publication_status": "published",
  • "execution_status": "in_progress",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "vehicles": [ ]
}

Get a tour

Requires tours:read or tours:read-own for a published Tour containing the current user. include=stops returns Stops without Task arrays or identifiers; include=tasks also returns ordered nested/root Tasks and assignment versions. Repeat include to combine; tasks implies stops. Task expansion and Task-derived Stop destinations require tasks:read. A denied expansion fails completely with 403 access-denied, reason missing_grant and required_grants [tasks:read]. One consistent snapshot; at most 500 Stops and 10,000 Tasks plus Stops. No include retains the summary.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

query Parameters
include
Array of strings non-empty
Items Enum: "stops" "tasks"

Opt-in expansion depth; repeat for multiple values. Comma-separated values are invalid.

Responses

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "planned_start_at": "2023-02-14T10:00:00Z",
  • "origin": "planned",
  • "publication_status": "draft",
  • "execution_status": "not_started",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "vehicles": [ ]
}

Delete an unstarted tour

Requires tours:delete and tours:update. Atomically unassigns and preserves its tasks, then removes its stops. Started tours cannot be deleted.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a tour

Requires tours:update, or tours:execute-own for an ad-hoc Tour containing the current user. A Vehicle-only update also permits tours:vehicles:assign-own for a participant with Tour read access. Vehicle assignments additionally require vehicles:read; newly added Vehicles must use an eligible definition. Replaces the complete Vehicle list; per-selection acknowledge_active_use acknowledges active use elsewhere for future planning, never concurrent actual use. Active changes reconcile participant Devices atomically. Type, identity and lifecycle are server controlled.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

Request Body schema:
required
description
string or null [ 1 .. 255 ] characters

Omission preserves the description; null clears it. Blank strings are rejected.

participant_user_ids
Array of strings <uuid> <= 100 items unique [ items <uuid > ]

Replaces the complete participant set.

planned_start_at
string or null <date-time>

Omission preserves the planned start; null clears it before the tour starts.

planned_end_at
string or null <date-time>

Omission preserves the planned end; null clears it until the tour finishes. Must be after planned_start_at when both are set.

required_skill_ids
Array of strings <uuid> <= 1000 items unique [ items <uuid > ]

Replace authored required skills; omission preserves, [] clears. The system Vehicle requirement blocks first Start without an eligible Vehicle; other missing skills are advisory

Array of objects (TourVehicleSelection) <= 100 items

Complete intended Vehicle set; omission preserves, [] removes all. Maximum 100 unique Vehicles.

lock_version
integer or null <int64> >= 0

Omitted or null skips the precondition; stale versions return 409.

Responses

Request samples

Content type

Request

{
  • "description": "Afternoon visits",
  • "lock_version": 0
}

Response samples

Content type
application/json

Success

{
  • "id": "2aeb50b2-a41c-4a5f-a498-7651a0938522",
  • "natural_id": 1,
  • "required_skill_ids": [ ],
  • "stop_count": 0,
  • "task_count": 0,
  • "description": "Morning visits",
  • "participant_user_ids": [
    ],
  • "planned_start_at": "2023-02-14T10:00:00Z",
  • "origin": "planned",
  • "publication_status": "draft",
  • "execution_status": "not_started",
  • "created_by_user_id": "b8746c3e-2ea1-4939-981b-d68777dc611a",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "vehicles": [ ]
}

Read Tour settings

Requires Tours read, own read, create, ad-hoc Start or update authority, tour-templates:read, or tenant:settings:update. Returns the protected Default template, system Vehicle skill, exclusions and settings version without granting template listing or editing.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

Default

{
  • "default_tour_template_id": "a46c234e-f8ba-42ad-955e-f103d514df76",
  • "vehicle_skill_id": "5a6970f9-9860-43cb-8c41-85e27f9c202b",
  • "excluded_vehicle_definition_ids": [ ],
  • "lock_version": 0
}

Update Tour settings

Requires tenant:settings:update. Replace excluded Vehicle definitions; omission preserves, [] permits all and null is invalid. Existing active assignments continue; first Start and new assignments recheck exclusions.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
excluded_vehicle_definition_ids
Array of strings <uuid> <= 1000 items unique [ items <uuid > ]

Complete exclusion set of up to 1000 unique Vehicle definition UUIDs; [] clears

lock_version
integer or null <int64> >= 0

Optional settings version; omission/null skips the precondition

Responses

Request samples

Content type
application/merge-patch+json

ClearExclusions

{
  • "excluded_vehicle_definition_ids": [ ],
  • "lock_version": 0
}

Response samples

Content type
application/json

AllDefinitions

{
  • "default_tour_template_id": "a46c234e-f8ba-42ad-955e-f103d514df76",
  • "vehicle_skill_id": "5a6970f9-9860-43cb-8c41-85e27f9c202b",
  • "excluded_vehicle_definition_ids": [ ],
  • "lock_version": 0
}

Read Tour Vehicle-assignment history

Requires tours:read or tours:read-own for a published Tour containing the current user. lifecycle=current (default) selects removed_at absent, including finished use; all includes removed episodes. Fixed assigned_at descending, id ascending order. Vehicle labels are current, not historical, and omitted without vehicles:read. Assignment and Vehicle identities remain visible. No write operations are offered on this collection.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Tour UUID

query Parameters
lifecycle
string
Default: "current"
Enum: "current" "all"

Current membership or all retained episodes

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Page size

Responses

Response samples

Content type
application/json

Empty

{
  • "items": [ ],
  • "page": {
    }
}

schema-definitions

Read-only discovery with explicit resource ownership; author through resource-specific definition APIs

Discover visible schema definitions

Includes supported native schemas without making them editable Objects. Owner visibility is applied before pagination. Includes concrete Object, Vehicle and Task definitions and supported native projections. Internal Vehicle and Task family roots are excluded. Results are ordered by slug, then ID.

Authorizations:
BearerAuth
query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page number

size
integer <int32> [ 1 .. 100 ]
Default: 20

Page size

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

Empty

{
  • "items": [ ],
  • "page": {
    }
}

Resolve a schema definition and its resource owner

Returns logical fields and ownership for a supported definition identified by slug or UUID. The owning resource controls metadata access. Discovery does not grant record access or make native schemas editable through Object APIs.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Definition slug or UUID

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

Tag

{
  • "id": "cccebcdf-0de1-4a45-ac74-47fa9bd4b27b",
  • "slug": "tag",
  • "resource_type": "tag",
  • "name": {
    },
  • "attributes": [ ],
  • "managed_by": "system",
  • "schema_policy": "locked",
  • "is_readonly": true,
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

Roles

Role listing API.

List roles

Lists all workspace roles with enabled grants and a can_assign indicator. Visibility does not imply assignability. System roles sort first, then name and id ascending.

Authorizations:
BearerAuth
query Parameters
search
string
Example: search=dispatcher

Case-insensitive partial match on role name.

page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

RolesResponse

{
  • "items": [
    ],
  • "page": {
    }
}

Create a role

Creates a role with the provided grants. New grants the caller does not possess are rejected. System-only and hidden login grants cannot be edited through this API.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string non-empty

Role name

grants
required
Array of strings unique

List of grants enabled for this role

assignable_by_roles
required
Array of strings <uuid> non-empty unique [ items <uuid > ]

Role IDs that are allowed to assign this role

description
string

Optional role description

requires_second_factor
boolean

When true, users holding this role must complete a second-factor challenge (currently a login PIN) at login. Defaults to false when omitted.

Responses

Request samples

Content type
application/json

CreateTechnicianRole

{
  • "name": "technician",
  • "grants": [
    ],
  • "assignable_by_roles": [
    ],
  • "description": "Field technicians who maintain customer equipment."
}

Response samples

Content type
application/json

CreateRoleResponse

{
  • "id": "00000000-0000-4000-8000-000000001101",
  • "name": "technician",
  • "description": "Field technicians who maintain customer equipment.",
  • "grants": [
    ],
  • "assignable_by_roles": [
    ],
  • "member_count": 1,
  • "can_assign": true,
  • "editable": true,
  • "is_system_role": false,
  • "requires_second_factor": false,
  • "lock_version": 0
}

Get a role

Returns a single role by its unique identifier.

Authorizations:
BearerAuth
path Parameters
role_id
required
string <uuid>
Example: 4b3c2d1e-9a8b-4c6d-8e0f-1234567890ab

UUID of the role to retrieve

Responses

Response samples

Content type
application/json

RoleResponse

{
  • "id": "00000000-0000-4000-8000-000000001101",
  • "name": "technician",
  • "description": "Field technicians who maintain customer equipment.",
  • "grants": [
    ],
  • "assignable_by_roles": [
    ],
  • "member_count": 1,
  • "can_assign": true,
  • "editable": true,
  • "is_system_role": false,
  • "requires_second_factor": false,
  • "lock_version": 0
}

Delete a role

Deletes a role by its unique identifier.

Authorizations:
BearerAuth
path Parameters
role_id
required
string <uuid>

UUID of the role.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a role

JSON Merge Patch (RFC 7386): omitted fields remain unchanged; a field set to null is cleared (description). New grants the caller does not possess are rejected; existing grants outside their control are preserved even when omitted from the replacement grants set. System-only and hidden login grants cannot be edited.

Authorizations:
BearerAuth
path Parameters
role_id
required
string <uuid>

UUID of the role.

Request Body schema: application/merge-patch+json
required
lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check

name
string

Role name. Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” name is required and cannot be cleared.

grants
Array of strings unique

List of grants enabled for this role; replaces the full grant set when provided. Omitted leaves the value unchanged. Explicit null is rejected (422).

assignable_by_roles
Array of strings <uuid> unique [ items <uuid > ]

Role IDs that are allowed to assign this role; replaces the full set when provided. Omitted leaves the value unchanged. Explicit null is rejected (422).

description
string or null

Optional role description. Omitted leaves the value unchanged; explicit null clears it.

requires_second_factor
boolean or null

When true, users holding this role must complete a second-factor challenge (currently a login PIN) at login. Omitted leaves the value unchanged.

Responses

Request samples

Content type
application/merge-patch+json

UpdateRoleNull

{
  • "name": "technician",
  • "description": null
}

Response samples

Content type
application/json

UpdateRoleResponse

{
  • "id": "00000000-0000-4000-8000-000000001101",
  • "name": "technician",
  • "description": "Field technicians who maintain customer equipment.",
  • "grants": [
    ],
  • "assignable_by_roles": [
    ],
  • "member_count": 1,
  • "can_assign": true,
  • "editable": true,
  • "is_system_role": false,
  • "requires_second_factor": false,
  • "lock_version": 0
}

Tags

Tag management API

List tags

Returns a paginated list of tags. Available to all authenticated users.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

AlpineTagsPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create a tag

Creates a new tag. Requires 'tags:create' grant.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string non-empty

Tag name

color
required
string non-empty

Tag color (hex or CSS color value)

Responses

Request samples

Content type
application/json

CreateUrgentTag

{
  • "name": "urgent",
  • "color": "#D92D20"
}

Response samples

Content type
application/json

CreatedUrgentTag

{
  • "id": "00000000-0000-4000-8000-000000005001",
  • "name": "urgent",
  • "color": "#D92D20",
  • "created_at": "2026-08-20T08:15:00Z",
  • "updated_at": "2026-08-20T08:15:00Z",
  • "lock_version": 0,
  • "usage_count": 1
}

Get a tag

Returns a single tag by its ID. Available to all authenticated users.

Authorizations:
BearerAuth
path Parameters
tag_id
required
string <uuid>

UUID of the tag.

Responses

Response samples

Content type
application/json

UrgentTag

{
  • "id": "00000000-0000-4000-8000-000000005001",
  • "name": "urgent",
  • "color": "#D92D20",
  • "created_at": "2026-08-20T08:15:00Z",
  • "updated_at": "2026-08-20T08:15:00Z",
  • "lock_version": 0,
  • "usage_count": 1
}

Delete a tag

Deletes a tag by ID. Requires 'tags:update' grant.

Authorizations:
BearerAuth
path Parameters
tag_id
required
string <uuid>

UUID of the tag.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a tag

Partial update: omitted fields remain unchanged. Requires 'tags:update' grant.

Authorizations:
BearerAuth
path Parameters
tag_id
required
string <uuid>

UUID of the tag.

Request Body schema: application/merge-patch+json
required
name
string

Tag name. Omit to leave the value unchanged. Must not be null or blank.

color
string

Tag color (hex or CSS color value). Omit to leave the value unchanged. Must not be null or blank.

lock_version
integer or null <int64>

Optimistic lock version. If provided, the update will fail with 409 if the stored version does not match.

Responses

Request samples

Content type
application/merge-patch+json

UpdateUrgentTagColor

{
  • "color": "#B42318",
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedUrgentTag

{
  • "id": "00000000-0000-4000-8000-000000005001",
  • "name": "urgent",
  • "color": "#B42318",
  • "created_at": "2026-08-20T08:15:00Z",
  • "updated_at": "2026-08-20T09:15:00Z",
  • "lock_version": 1,
  • "usage_count": 1
}

Tour templates

Reusable configuration for creating independent Tours, Tasks and Stops

List tour templates

Requires tour-templates:read. Counts and skill IDs are included without loading every template's contents.

Authorizations:
BearerAuth
query Parameters
search
string [ 1 .. 255 ] characters

Nonblank literal name substring

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Page size

sort
string
Default: "name:asc"

One field[:asc|desc]: name, created_at, updated_at or id. Defaults to name:asc with stable UUID tie-breaker.

Responses

Response samples

Content type
application/json

Success

{
  • "items": [ ],
  • "page": {
    }
}

Create a tour template

Requires tour-templates:create. Saves the entire validated aggregate atomically, including definition-bound custom Task inputs. Template item UUIDs may be supplied by the editor; operational resources are created only when the template is used.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters
required
object (TourTemplateTourDefaultsWrite)
Array of any (TourTemplateTaskWrite) [ 0 .. 10000 ] items
Array of objects (TourTemplateStopWrite) [ 0 .. 500 ] items
Array of any (TourTemplateOrderItemWrite) [ 0 .. 10000 ] items

Responses

Request samples

Content type
application/json

Request

{
  • "name": "Morning inspection",
  • "tour_defaults": {
    },
  • "tasks": [ ],
  • "stops": [ ],
  • "items": [ ]
}

Response samples

Content type
application/json

Success

{
  • "id": "a46c234e-f8ba-42ad-955e-f103d514df76",
  • "name": "Morning inspection",
  • "is_default": false,
  • "tour_defaults": {
    },
  • "tasks": [ ],
  • "stops": [ ],
  • "items": [ ],
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "needs_configuration": false
}

Get a tour template

Requires tour-templates:read, or tours:create/tours:start-ad-hoc for the protected Default only. Returns complete saved contents, custom Task inputs, configuration repair fields and order; bounded Default access grants no listing, editing or named-template reads.

Authorizations:
BearerAuth
path Parameters
tour_template_id
required
string <uuid>

Template UUID

Responses

Response samples

Content type
application/json

Success

{
  • "id": "a46c234e-f8ba-42ad-955e-f103d514df76",
  • "name": "Morning inspection",
  • "is_default": false,
  • "tour_defaults": {
    },
  • "tasks": [ ],
  • "stops": [ ],
  • "items": [ ],
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "needs_configuration": false
}

Delete a tour template

Requires tour-templates:delete. The protected Default and current workflow references block deletion. Generated Tours remain independent; historical or origin-only references do not block deletion.

Authorizations:
BearerAuth
path Parameters
tour_template_id
required
string <uuid>

Template UUID

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a tour template

Requires tour-templates:update. Nested defaults merge; supplied arrays replace completely. Omitted lock_version skips the precondition. Saving does not change previously created Tours.

Authorizations:
BearerAuth
path Parameters
tour_template_id
required
string <uuid>

Template UUID

Request Body schema:
required
name
string [ 1 .. 255 ] characters
object (UpdateTourTemplateTourDefaults)
Array of any (TourTemplateTaskWrite) <= 10000 items
Array of objects (TourTemplateStopWrite) <= 500 items
Array of any (TourTemplateOrderItemWrite) <= 10000 items
lock_version
integer or null <int64> >= 0

Optional optimistic concurrency check

Responses

Request samples

Content type

Request

{
  • "name": "Morning inspection",
  • "tour_defaults": {
    },
  • "lock_version": 0
}

Response samples

Content type
application/json

Success

{
  • "id": "a46c234e-f8ba-42ad-955e-f103d514df76",
  • "name": "Morning inspection",
  • "is_default": false,
  • "tour_defaults": {
    },
  • "tasks": [ ],
  • "stops": [ ],
  • "items": [ ],
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "needs_configuration": false
}

Skills

Skills management API

List skills

Returns a paginated list of skills.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

sort
Array of strings
Example: sort=name:asc

Repeated sorting criteria in field:direction format. Allowed fields: id, name, short_key, created_at, updated_at. Default: name:asc.

search
string

Search term matched against name and short_key.

updated_from
string <date-time>

Lower bound for updated_at (inclusive, RFC 3339).

updated_to
string <date-time>

Upper bound for updated_at (exclusive, RFC 3339). Must be later than updated_from.

Responses

Response samples

Content type
application/json

SkillsResponse

{
  • "items": [
    ],
  • "page": {
    }
}

Create a skill

Creates a new skill with the provided information

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 0 .. 255 ] characters

Skill name

short_key
required
string [ 0 .. 6 ] characters

Short key, unique in the workspace (case-insensitive)

Responses

Request samples

Content type
application/json

CreateHvacMaintenanceSkill

{
  • "name": "HVAC maintenance",
  • "short_key": "HVAC"
}

Response samples

Content type
application/json

SkillResponse

{
  • "id": "00000000-0000-4000-8000-000000006001",
  • "name": "HVAC maintenance",
  • "short_key": "HVAC",
  • "managed_by": "tenant",
  • "created_at": "2026-08-20T08:12:00Z",
  • "updated_at": "2026-08-20T08:12:00Z",
  • "lock_version": 0
}

Get skill by ID

Retrieves a specific skill by its ID

Authorizations:
BearerAuth
path Parameters
skill_id
required
string <uuid>

UUID of the skill.

Responses

Response samples

Content type
application/json

SkillsResponse

{
  • "id": "00000000-0000-4000-8000-000000006001",
  • "created_at": "2026-08-20T08:12:00Z",
  • "updated_at": "2026-08-20T08:12:00Z",
  • "name": "HVAC maintenance",
  • "short_key": "HVAC",
  • "managed_by": "tenant",
  • "lock_version": 0
}

Delete skill

Deletes a skill by its ID

Authorizations:
BearerAuth
path Parameters
skill_id
required
string <uuid>

UUID of the skill.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a skill

Partial update: omitted fields remain unchanged (JSON Merge Patch, RFC 7386).

Authorizations:
BearerAuth
path Parameters
skill_id
required
string <uuid>

UUID of the skill.

Request Body schema: application/merge-patch+json
required
name
string

Skill name (max 255 characters). Omitted leaves the value unchanged; explicit null is rejected (422) โ€” it is required and cannot be cleared.

short_key
string

Short key identifier (max 10 characters). Omitted leaves the value unchanged; explicit null is rejected (422) โ€” it is required and cannot be cleared.

lock_version
integer or null <int64>

Optimistic-locking version of the skill: validated when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/merge-patch+json
Example

UpdateSkillName

{
  • "lock_version": 2,
  • "name": "Advanced HVAC maintenance"
}

Response samples

Content type
application/json

UpdateSkillResponse

{
  • "id": "00000000-0000-4000-8000-000000006001",
  • "name": "HVAC maintenance",
  • "short_key": "HVAC",
  • "managed_by": "tenant",
  • "created_at": "2026-08-20T08:12:00Z",
  • "updated_at": "2026-08-20T08:12:00Z",
  • "lock_version": 0
}

Billing Invoices

Tenant billing invoice API

List billing invoices

Returns invoice summaries for Stripe-backed self-service tenants. Other plan kinds return an empty list. Stripe is the source of truth: the service fetches a bounded window of the most recent 100 invoices from Stripe and page/size paginate over that fetched window (newest first). page.total_elements therefore never exceeds 100 even if Stripe holds more history.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

AlpineInvoicesPage

{
  • "items": [
    ],
  • "page": {
    }
}

Get billing invoice download URL

Returns the Stripe invoice PDF URL after verifying the invoice belongs to this tenant's Stripe customer.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string

Identifier of the invoice.

Responses

Response samples

Content type
application/json

Webhook Endpoints

Manage webhook endpoints and subscriptions

List webhook endpoints

Returns a page of webhook endpoints configured for the current tenant. Pass object_id to return only endpoints whose stored subscription explicitly names that object definition.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

object_id
string <uuid>
Example: object_id=6b1e0f22-0000-4000-8000-000000000001

Return only endpoints holding a subscription scoped to this object. Broader patterns such as * also deliver that object's events but are not matched here, since their stored pattern does not name the object.

Responses

Response samples

Content type
application/json

AlpineWebhookEndpointsPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create a webhook endpoint

Creates a webhook endpoint with optional subscriptions and returns the generated secret once.

Authorizations:
BearerAuth
Request Body schema: application/json
required
display_name
required
string [ 1 .. 255 ] characters

Human readable endpoint name

endpoint_url
required
string <uri> [ 1 .. 2048 ] characters ^https?://.+$

HTTPS destination URL. Plain HTTP is accepted only when the server's explicit local-development escape hatch is enabled.

signature_scheme
string
Default: "HMAC_SHA256"
Value: "HMAC_SHA256"

Signature scheme

enabled
boolean
Default: true

Whether deliveries are enabled

retry
boolean
Default: true

Whether failed deliveries should be retried

subscriptions
Array of strings [ 0 .. 100 ] items [ items <= 512 characters ]

Webhook event types to subscribe to

Responses

Request samples

Content type
application/json

CreateAlpineIntegrationEndpoint

{}

Response samples

Content type
application/json

CreatedAlpineIntegrationEndpoint

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "display_name": "Alpine maintenance integration",
  • "signature_scheme": "HMAC_SHA256",
  • "enabled": true,
  • "retry": true,
  • "subscriptions": [
    ],
  • "invalid_subscriptions": [ ],
  • "created_at": "2026-08-20T08:40:00Z",
  • "updated_at": "2026-08-20T08:40:00Z",
  • "lock_version": 0,
  • "secret": "whsec_example_not_a_real_secret"
}

Rotate webhook secret

Rotates and returns a new secret. The previous secret is invalidated. The change takes effect immediately and the operation takes no request body.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the webhook endpoint.

Responses

Response samples

Content type
application/json

RotatedAlpineIntegrationSecret

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "display_name": "Alpine maintenance integration",
  • "signature_scheme": "HMAC_SHA256",
  • "enabled": true,
  • "retry": true,
  • "subscriptions": [
    ],
  • "invalid_subscriptions": [ ],
  • "created_at": "2026-08-20T08:40:00Z",
  • "updated_at": "2026-08-20T09:45:00Z",
  • "lock_version": 2,
  • "secret": "whsec_rotated_example_not_a_real_secret"
}

Get a webhook endpoint

Returns one webhook endpoint configured for the current tenant. The signing secret is never returned.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the webhook endpoint.

Responses

Response samples

Content type
application/json

AlpineIntegrationEndpoint

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "display_name": "Alpine maintenance integration",
  • "signature_scheme": "HMAC_SHA256",
  • "enabled": true,
  • "retry": true,
  • "subscriptions": [
    ],
  • "invalid_subscriptions": [ ],
  • "created_at": "2026-08-20T08:40:00Z",
  • "updated_at": "2026-08-20T08:40:00Z",
  • "lock_version": 0
}

Delete a webhook endpoint

Deletes a webhook endpoint and all its subscriptions.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the webhook endpoint.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a webhook endpoint

Partial update: omitted fields remain unchanged. Include subscriptions to replace them, or omit to keep existing subscriptions.

Authorizations:
BearerAuth
path Parameters
endpoint_id
required
string <uuid>

UUID of the webhook endpoint.

Request Body schema:
required
display_name
string [ 1 .. 255 ] characters

Human readable endpoint name. Omitted leaves the value unchanged. Explicit null and blank strings are rejected (422).

endpoint_url
string <uri> [ 1 .. 2048 ] characters

HTTPS destination URL. Plain HTTP is accepted only when the server's explicit local-development escape hatch is enabled. Omitted leaves the value unchanged. Explicit null and blank strings are rejected (422).

signature_scheme
string
Value: "HMAC_SHA256"

Signature scheme. Omitted leaves the value unchanged. Explicit null is rejected (422).

enabled
boolean

Whether deliveries are enabled. Omitted leaves the value unchanged. Explicit null is rejected (422).

retry
boolean

Whether failed deliveries should be retried. Omitted leaves the value unchanged. Explicit null is rejected (422).

subscriptions
Array of strings <= 100 items [ items <= 512 characters ]

Webhook event types to subscribe to. If provided, replaces all existing subscriptions. Omitted leaves the subscriptions unchanged. Explicit null is rejected (422).

lock_version
integer <int64>

Optimistic lock version: validated when provided (409 on mismatch); omitting it skips the concurrency check. Explicit null is rejected (422).

Responses

Request samples

Content type
Example

ReplaceIntegrationSubscriptions

{
  • "subscriptions": [
    ],
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedAlpineIntegrationEndpoint

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "display_name": "Alpine maintenance integration",
  • "signature_scheme": "HMAC_SHA256",
  • "enabled": true,
  • "retry": true,
  • "subscriptions": [
    ],
  • "invalid_subscriptions": [ ],
  • "created_at": "2026-08-20T08:40:00Z",
  • "updated_at": "2026-08-20T09:40:00Z",
  • "lock_version": 1
}

Webhook Testing

Test webhook endpoint connectivity

Trigger a test webhook

Immediately delivers a test webhook to the specified endpoint to verify connectivity

Authorizations:
BearerAuth
Request Body schema: application/json
required
endpoint_id
required
string <uuid>

Endpoint id to send a test webhook to

Responses

Request samples

Content type
application/json

TestAlpineIntegrationEndpoint

{
  • "endpoint_id": "00000000-0000-4000-8000-000000008001"
}

Response samples

Content type
application/json

SuccessfulAlpineWebhookTest

{
  • "last_test_tried_at": "2026-08-20T09:50:00Z",
  • "test_was_successful": true
}

Comments

Polymorphic comments on target objects.

List comments on a target

Returns comments on the given target, paginated. sort follows the v2 <mode>:<direction> convention: threaded:desc (default โ€” root comments newest-first; replies always oldest-first within each thread), threaded:asc, flat:desc, flat:asc. In threaded mode the page numbers refer to root comments and the response interleaves each root with its replies. Requires the comments read grant and read access to the target object.

Authorizations:
BearerAuth
query Parameters
target_type
required
string
Example: target_type=object:equipment

Family-prefixed identifier of the object the comments are attached to. Examples: "object:<slug>" for object records, such as "object:equipment".

target_id
required
string <uuid>
Example: target_id=22222222-2222-3333-4444-555555555555

Id of the target object the comments are attached to.

page
integer >= 0
Default: 0

Page number (0-based). In threaded mode this refers to the root-comment page.

size
integer [ 1 .. 1000 ]
Default: 20
Example: size=20

Number of root comments per page (threaded) or items per page (flat). Range 1..1000. The 1000 cap is intentionally higher than the platform default (100) because the comments list is the primary read path for moderation, audit-log, and AI-assistant scrapes โ€” workflows that need the full thread in one shot rather than paged. Frontends paginate at 20โ€“50; the high cap is for server-side and integration callers.

sort
string
Default: "threaded:desc"
Enum: "threaded:desc" "threaded:asc" "flat:desc" "flat:asc"
Example: sort=threaded:desc

Sort instruction in <mode>:<direction> form. Default threaded:desc.

Responses

Response samples

Content type
application/json

EquipmentCommentsPage

{
  • "items": [
    ],
  • "unread_count": 0,
  • "page": {
    }
}

Post a new comment

Creates a comment on the given target. Create access follows the target adapter for the supplied target_type. Server-side dedup: a duplicate submission by the same author against the same target with the same body within the configured window (default 60s) returns the existing comment with HTTP 200 instead of inserting a duplicate.

Both the 201 (fresh insert) and 200 (dedup) responses include a Location: /api/v2/comments/{comment_id} header pointing at the persisted row, per RFC 7231.

Authorizations:
BearerAuth
Request Body schema: application/json
required
target_type
required
string non-empty

Family-prefixed identifier of the object the comment is attached to. Examples: "object:<slug>" for object records, such as "object:equipment". Each supported family is registered by a target adapter that owns existence and authorization checks.

target_id
required
string <uuid>

Id of the target object the comment is attached to.

parent_comment_id
string <uuid>

Id of the parent comment when posting a reply. Must exist and belong to the same target. Omit (or send null) to post a root comment.

body_markdown
required
string [ 1 .. 10000 ] characters

Comment body in markdown. Server enforces the v2 allow-list (bold, italic, strikethrough (GFM ~~text~~), inline code, headings level 1โ€“3, fenced code blocks, ordered/unordered lists, blockquotes, http(s) links, inline image references via the attachment:<uuid> scheme). Headings level 4+, raw HTML, tables, plain http(s) images, and non-http(s) link schemes are rejected with comments.body-invalid-markdown. Mention a user with @[name](user:<id>); the name is for readability only and is not stored (responses show the user's current name).

attachment_ids
Array of strings <uuid> [ items <uuid > ]

Filestore file ids previously obtained from POST /api/v2/comments/attachments/uploads. Each id must have been used to upload a real file (upload status UPLOADED); files uploaded for other features are rejected with comments/attachment-not-from-comments. Inline references in the body via ![alt](attachment:<uuid>) must also be listed here. Position in the array becomes the chip-row order for non-inline files. Defaults to an empty array (no attachments). Capped at comments.attachments.max-per-comment (default 10) โ€” exceeding the cap returns comments/too-many-attachments (422).

Responses

Request samples

Content type
application/json

CreateEquipmentMaintenanceComment

{
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "body_markdown": "Replacement filter ordered."
}

Response samples

Content type
application/json

DeduplicatedFilterComment

{
  • "id": "00000000-0000-4000-8000-000000007501",
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "root_comment_id": "00000000-0000-4000-8000-000000007501",
  • "body_markdown": "Replacement filter ordered.",
  • "author": {
    },
  • "created_at": "2026-03-03T10:45:00Z",
  • "updated_at": "2026-03-03T10:45:00Z",
  • "lock_version": 0,
  • "is_edited": false,
  • "is_moderated": false,
  • "is_deleted": false,
  • "is_deleted_by_moderator": false,
  • "is_unread": false,
  • "reactions": [ ],
  • "mentions": [ ],
  • "attachments": [ ]
}

Restore a soft-deleted comment (moderator only)

Clears the soft-delete tombstone on a comment. Always a moderator action; requires the comments:update grant. Returns 422 when the comment is not currently soft-deleted (comments.cannot-restore-not-deleted).

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the soft-deleted comment to restore.

Responses

Response samples

Content type
application/json

RestoredFilterComment

{
  • "id": "00000000-0000-4000-8000-000000007501",
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "root_comment_id": "00000000-0000-4000-8000-000000007501",
  • "body_markdown": "Replacement filter ordered.",
  • "author": {
    },
  • "created_at": "2026-03-03T10:45:00Z",
  • "updated_at": "2026-03-03T10:45:00Z",
  • "lock_version": 0,
  • "is_edited": false,
  • "is_moderated": false,
  • "is_deleted": false,
  • "is_deleted_by_moderator": false,
  • "is_unread": false,
  • "reactions": [ ],
  • "mentions": [ ],
  • "attachments": [ ]
}

Add an emoji reaction to a comment

Adds one of Tourfold's supported emoji reactions (๐Ÿ‘ โค๏ธ ๐Ÿ˜‚ ๐ŸŽ‰ ๐Ÿ˜ฎ ๐Ÿ˜ข ๐Ÿ‘€ ๐Ÿ™Œ) by the calling user to the named comment. Requires comments:read and read access to the comment target. Idempotent: 201 on the first add, 200 on a duplicate add (no row inserted, no SSE / webhook emitted). Tombstoned comments reject reactions with comments.reaction-on-deleted-comment (422).

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment to react to.

Request Body schema: application/json
required
emoji
required
string
Enum: "๐Ÿ‘" "โค๏ธ" "๐Ÿ˜‚" "๐ŸŽ‰" "๐Ÿ˜ฎ" "๐Ÿ˜ข" "๐Ÿ‘€" "๐Ÿ™Œ"

Emoji to react with. Supported values are ๐Ÿ‘ โค๏ธ ๐Ÿ˜‚ ๐ŸŽ‰ ๐Ÿ˜ฎ ๐Ÿ˜ข ๐Ÿ‘€ ๐Ÿ™Œ.

Responses

Request samples

Content type
application/json

AddThumbsUp

{
  • "emoji": "๐Ÿ‘"
}

Response samples

Content type
application/json

ExistingThumbsUpReaction

{
  • "id": "00000000-0000-4000-8000-000000007501",
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "root_comment_id": "00000000-0000-4000-8000-000000007501",
  • "body_markdown": "Replacement filter ordered.",
  • "author": {
    },
  • "created_at": "2026-03-03T10:45:00Z",
  • "updated_at": "2026-03-03T10:45:00Z",
  • "lock_version": 0,
  • "is_edited": false,
  • "is_moderated": false,
  • "is_deleted": false,
  • "is_deleted_by_moderator": false,
  • "is_unread": false,
  • "reactions": [
    ],
  • "mentions": [ ],
  • "attachments": [ ]
}

Mark a single comment as unread for the caller

Adds (or refreshes) the caller's unread override for the comment. Requires comments:read and read access to the comment target. The comment is then unread regardless of where the cursor sits. The cursor is not moved.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment to mark unread.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Clear the caller's unread override on a single comment

Removes the caller's per-comment unread override, if any. Requires comments:read and read access to the comment target. Does not move the cursor. Idempotent: a no-op success when no override exists.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment to clear the unread override on.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Advance the caller's read cursor on a target

Sets the caller's read cursor on (target_type, target_id) to the named comment (inclusive). Requires comments:read and read access to the target. Monotonic โ€” naming an older comment is a no-op success returning the existing cursor. As a side effect, clears the caller's per-comment unread overrides at-or-before the new cursor.

Authorizations:
BearerAuth
Request Body schema: application/json
required
target_type
required
string non-empty

Family-prefixed identifier of the object the cursor lives on. Examples: "object:<slug>" for object records, such as "object:equipment".

target_id
required
string <uuid>

Id of the target object the cursor lives on.

comment_id
required
string <uuid>

Id of the comment the cursor should advance to (inclusive). The comment must belong to the supplied (target_type, target_id) โ€” server returns 422 (comments.read-cursor-target-mismatch) otherwise.

Responses

Request samples

Content type
application/json

MarkEquipmentCommentsRead

{
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "comment_id": "00000000-0000-4000-8000-000000007501"
}

Response samples

Content type
application/json

EquipmentCommentsReadCursor

{
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "last_seen_comment_id": "00000000-0000-4000-8000-000000007501",
  • "last_seen_created_at": "2026-03-03T10:45:00Z"
}

Issue a presigned form for a single comment attachment upload

Validates MIME / size / storage allowance and returns a presigned form descriptor. The client then POSTs the bytes to upload_url as multipart/form-data, including every entry from upload_fields (preserving their original order) followed by the actual file payload under the file part. The returned attachment_id is referenced later in POST /api/v2/comments (or PATCH /api/v2/comments/{comment_id}) via the attachment_ids array. No core_comment_attachments row is created at this point โ€” files uploaded but never referenced are reaped asynchronously by the orphan-cleanup cron. Status is 200, not 201, because no addressable resource is exposed at a Location URL: the attachment_id is only meaningful once a subsequent comment create/edit references it. Requires the comments:create grant.

Not exposed via MCP โ€” agents can't fill in presigned forms; the comments_create and comments_update MCP tools strip any attachment_ids from incoming payloads.

Authorizations:
BearerAuth
Request Body schema: application/json
required
original_file_name
required
string [ 0 .. 255 ] characters

Original filename to persist on the filestore blob. Surfaced back in the attachment chip and download Content-Disposition; users see this exact string.

mime_type
required
string non-empty

MIME type of the file. Almost any MIME is accepted; the server enforces a denylist (comments.attachments.blocked-mime-types) of known XSS vectors and executable formats (SVG, raw HTML / JS, .exe, .msi, shell scripts, โ€ฆ). Inline rendering in the comment body still requires an image MIME or application/pdf; non-image attachments render as chips below the body and link out to download.

size_bytes
required
integer <int64> > 0

File size in bytes. Must be > 0 and โ‰ค comments.attachments.max-bytes-per-file (default 26 214 400 = 25 MiB). The presigned form caps the upload at exactly this size so the client cannot upload a larger file than declared.

Responses

Request samples

Content type
application/json

CreateFilterPhotoUpload

{
  • "original_file_name": "rtu-17-filter.jpg",
  • "mime_type": "image/jpeg",
  • "size_bytes": 248320
}

Response samples

Content type
application/json

FilterPhotoUploadIntent

{}

Get a single comment by id

Returns one comment with its author and caller-scoped is_unread state. Used by the SSE-driven real-time wiring (the create event triggers a thin refetch to resolve the new author) and by deep-link openers that may target a comment which isn't on the currently visible list page. Requires the comments read grant and read access to the target object โ€” the same gating as GET /api/v2/comments.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment.

Responses

Response samples

Content type
application/json

EquipmentMaintenanceComment

{
  • "id": "00000000-0000-4000-8000-000000007501",
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "root_comment_id": "00000000-0000-4000-8000-000000007501",
  • "body_markdown": "Replacement filter ordered.",
  • "author": {
    },
  • "created_at": "2026-03-03T10:45:00Z",
  • "updated_at": "2026-03-03T10:45:00Z",
  • "lock_version": 0,
  • "is_edited": false,
  • "is_moderated": false,
  • "is_deleted": false,
  • "is_deleted_by_moderator": false,
  • "is_unread": false,
  • "reactions": [ ],
  • "mentions": [ ],
  • "attachments": [ ]
}

Soft-delete a comment

Marks the comment as deleted. Author can delete own; users with the comments:delete grant can delete any. Idempotent: if the comment is already soft-deleted, the call is a no-op success. Soft-deleted comments stay in the list as tombstones with is_deleted=true and an empty body_markdown โ€” the frontend renders a tombstone placeholder.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment to soft-delete.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Edit an existing comment

Updates a comment's body. Author can edit own; users with the comments:update grant can edit any. Moderator edits (caller != author) require a non-blank edit_reason โ€” the server returns 422 (comments.moderation-reason-required) when missing. On success an audit row is appended to core_comment_edits in the same transaction; the response carries the updated comment with is_edited (and, for moderator edits, is_moderated) set to true.

Concurrency model: optional optimistic locking. Include the lock_version you last read to guard the edit โ€” if it no longer matches the stored version the API returns 409 Conflict (resource-conflict); omit it (or send null) for last-write-wins, where the request that commits second overwrites the first. Either way every edit is appended to core_comment_edits as a separate audit row, so clients that need to reconcile can consult GET /api/v2/comments/{comment_id}/edits after their write.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment to edit.

Request Body schema: application/merge-patch+json
required
lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check

body_markdown
string

New comment body in markdown. Omit to leave unchanged. Explicit null is rejected. Same allow-list as create: bold, italic, strikethrough (GFM ~~text~~), inline code, headings level 1โ€“3, fenced code blocks, lists, blockquotes, http(s) links. Server enforces the 10_000-character cap and the markdown allow-list. As on create, the name in a mention token is not stored.

edit_reason
string or null

Reason for the edit. Required (non-blank) when the caller is moderating another user's comment under the comments:update grant. Stored on the audit row and surfaced to other moderators via the edit-history endpoint. Ignored for author edits. This is a per-edit annotation: omitting it (or sending null) leaves the edit without a reason rather than carrying over a previous one.

attachment_ids
Array of strings or null <uuid> [ items <uuid > ]

Replacement attachment list. Omit this field to leave the comment's attachments untouched โ€” this is the typical case when the caller only wants to edit body_markdown. Explicit null is rejected. Sending an empty array [] explicitly clears every attachment and marks the dropped blobs deleted in filestore. Sending a populated array replaces the set: rows kept across the edit retain their internal id; rows absent from the array are removed and their blobs marked deleted; new ids are linked. Inline references in body_markdown via ![alt](attachment:<uuid>) must also appear in this array. Capped at comments.attachments.max-per-comment (default 10) โ€” exceeding the cap returns comments/too-many-attachments (422).

Responses

Request samples

Content type
application/merge-patch+json
Example

UpdateFilterComment

{
  • "body_markdown": "Replacement filter ordered for Friday.",
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedFilterComment

{
  • "id": "00000000-0000-4000-8000-000000007501",
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "root_comment_id": "00000000-0000-4000-8000-000000007501",
  • "body_markdown": "Replacement filter ordered for Friday.",
  • "author": {
    },
  • "created_at": "2026-03-03T10:45:00Z",
  • "updated_at": "2026-03-03T11:00:00Z",
  • "lock_version": 1,
  • "last_edited_at": "2026-03-03T11:00:00Z",
  • "is_edited": true,
  • "is_moderated": false,
  • "is_deleted": false,
  • "is_deleted_by_moderator": false,
  • "is_unread": false,
  • "reactions": [ ],
  • "mentions": [ ],
  • "attachments": [ ]
}

Get the page index containing a comment in the list response

Computes which page of GET /api/v2/comments contains [id] under the given sort + size. Used by deep-link openers (frontend ?commentId=โ€ฆ) to jump straight to the right page without paginating one click at a time. In threaded mode the returned page is the page of root comments; if the target is a reply, its row appears under its root on that page. Requires the comments read grant and read access to the target object โ€” the same gating as the list endpoint.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment to locate.

query Parameters
sort
string
Default: "threaded:desc"
Enum: "threaded:desc" "threaded:asc" "flat:desc" "flat:asc"
Example: sort=threaded:desc

Same <mode>:<direction> value as GET /api/v2/comments?sort=โ€ฆ. Default threaded:desc.

size
integer [ 1 .. 1000 ]
Default: 20
Example: size=20

Page size used for the index calculation. Must match the size the client uses when fetching the list, or the page index will be wrong. Range 1..1000.

Responses

Response samples

Content type
application/json

EquipmentCommentPageInfo

{
  • "comment_id": "00000000-0000-4000-8000-000000007501",
  • "root_comment_id": "00000000-0000-4000-8000-000000007501",
  • "mode": "threaded",
  • "page": 0,
  • "total_pages": 1
}

Get a comment's edit history (moderator only)

Returns the ordered audit trail for a single comment, newest-first. Each entry includes the editor reference, the body as it stood before the edit, the (moderator) edit_reason, the per-edit attachment-name diff (attachments_added_names / attachments_removed_names), and is_moderation (derived from editor.id != author.id). Requires the comments:update grant.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment.

Responses

Response samples

Content type
application/json

FilterCommentEditHistory

{
  • "items": [
    ]
}

Get the detail view for a mention target

Returns the mention target's display name and deletion state. Requires comments:read, comments:create, or comments:update. For user mentions, email is omitted and roles remains an empty array ([]) for compatibility.

Deleted targets return 200 with is_deleted=true: a deleted user keeps their display_name, while an anonymized user has an empty display_name (and email omitted, roles: []). Clients must check is_deleted before treating the response as a live target. Unknown ids (e.g. cross-tenant) return 404 comments/mention-target-not-found.

Authorizations:
BearerAuth
path Parameters
target_type
required
string
Value: "user"
Example: user

Mention-type discriminator.

target_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Target id.

Responses

Response samples

Content type
application/json

AlpineUserMentionDetail

{
  • "type": "user",
  • "id": "00000000-0000-4000-8000-000000000102",
  • "display_name": "Jonas Leitner",
  • "is_deleted": false,
  • "roles": [ ]
}

List mention suggestions for the picker

Returns up to limit mention targets matching search for the requested target_type. Ranked: prefix-matches first (alpha-sorted within), substring matches second (alpha-sorted within). Empty search returns the top-N targets alpha-sorted. Requires the comments:create grant โ€” read-only viewers never need the picker. Tenant scope is enforced by the schema interceptor.

Authorizations:
BearerAuth
query Parameters
search
string
Example: search=ali

Free-text query. Matches against first / last name and email for user mentions. Empty / missing โ†’ top-N alpha-sorted.

target_type
string
Example: target_type=user

Mention-type discriminator to search. Currently only user; future variants slot in here.

limit
integer [ 1 .. 50 ]
Default: 10
Example: limit=10

Maximum number of suggestions to return. Range 1..50.

Responses

Response samples

Content type
application/json

AlpineUserMentionSuggestions

{
  • "items": [
    ]
}

Get comment counts for target ids

Returns total and caller-scoped unread counts for every requested target the caller may read, preserving request order. Readable targets with no comments receive explicit zero counts. Missing and unreadable targets are omitted without revealing whether they exist. Tombstones are excluded from both counts.

Authorizations:
BearerAuth
query Parameters
target_type
required
string
Example: target_type=object:equipment

Family-prefixed identifier of the object the comments are attached to. Examples: "object:<slug>" for object records, such as "object:equipment".

target_ids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]
Example: target_ids=22222222-2222-3333-4444-555555555555

Target ids to count for. Supply 1 to 100 UUIDs by repeating the plural target_ids parameter.

Responses

Response samples

Content type
application/json

EquipmentCommentCounts

{
  • "items": [
    ]
}

Re-issue presigned URLs for an existing comment attachment

Presigned URLs returned on the comment list endpoint expire after comments.attachments.download-url-ttl-seconds (default 5 min). This endpoint refreshes them for a single attachment โ€” used by the preview modal when the user opens a chip / inline image long after the comment was first rendered.

Authorisation gate: the caller must be authenticated in the tenant and the parent comment must exist and be live (not soft-deleted), with read access to its target.

Set download=true to sign the original URL for an attachment download with its stored filename. Omitted/false preserves safe inline handling; thumbnail URLs always retain that default.

Error contract:

  • 404 comments/attachment-not-found when no attachment row matches the id, when its parent comment was hard-deleted (FK cascade drops the row), or when the parent comment has been soft-deleted.
  • 404 comments/target-not-found when the parent comment target is unavailable.
  • 404 filestore/file-not-found when the original rendition is unavailable on an active file.
  • 410 comments/attachment-blob-gone when the row exists but the underlying filestore blob has been hard-deleted (target cascade, manual purge, orphan-cleanup gap). The client should NOT retry; the list endpoint still surfaces the row with is_deleted=true so the comment body keeps its placeholder chip.
Authorizations:
BearerAuth
path Parameters
attachment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Comment attachment id.

query Parameters
download
boolean
Default: false

Force attachment download of the original; defaults to safe inline handling.

Responses

Response samples

Content type
application/json

FilterPhotoDownloadUrls

Remove the caller's reaction from a comment

Removes the calling user's reaction row addressed by the opaque {reaction_id} (read from reactions[*].your_reaction_id on a recent CommentResponse). Requires comments:read and read access to the comment target. Returns the updated comment. 404 comments/reaction-not-found when the id does not exist OR belongs to a different user โ€” both cases return the same problem so the surface doesn't leak the existence of other users' reaction rows. The path id (rather than the emoji) avoids the fragile URL-encoding of skin-tone modifiers, ZWJ sequences, and similar. Removal uses the stored value without reparsing it so historical or manually repaired rows remain cleanable.

Authorizations:
BearerAuth
path Parameters
comment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Id of the comment to un-react from. Used only for routing โ€” the reaction id alone is sufficient to identify the row to remove.

reaction_id
required
string <uuid>
Example: 33333333-aaaa-bbbb-cccc-dddddddddddd

Opaque id of the caller's reaction row. Read from reactions[*].your_reaction_id on a recent comment response (set when you_reacted == true).

Responses

Response samples

Content type
application/json

CommentWithoutReaction

{
  • "id": "00000000-0000-4000-8000-000000007501",
  • "target_type": "object:equipment",
  • "target_id": "6f3d2a10-0000-4000-8000-000000000101",
  • "root_comment_id": "00000000-0000-4000-8000-000000007501",
  • "body_markdown": "Replacement filter ordered.",
  • "author": {
    },
  • "created_at": "2026-03-03T10:45:00Z",
  • "updated_at": "2026-03-03T10:45:00Z",
  • "lock_version": 0,
  • "is_edited": false,
  • "is_moderated": false,
  • "is_deleted": false,
  • "is_deleted_by_moderator": false,
  • "is_unread": false,
  • "reactions": [ ],
  • "mentions": [ ],
  • "attachments": [ ]
}

Delete an uploaded-but-not-yet-linked comment attachment

Marks the filestore blob as deleted so storage is reclaimed immediately when the user changes their mind about an attachment in the composer (clicks the pill โœ• before posting the comment). Without this endpoint, abandoned uploads sit on filestore for up to comments.attachments.orphan-retention-hours (default 24) before the nightly orphan-cleanup task sweeps them.

Idempotent. Repeated DELETEs return 204; the second call is a no-op on an already-deleted file.

Scope. Only deletes files whose source_key is COMMENT_ATTACHMENTS AND that are NOT yet linked to a posted comment. Once a file is part of core_comment_attachments the proper removal path is the comment-delete endpoint (which cascades blob removal via the comment hard-delete hook).

Authorisation gate. Requires the comments:create grant โ€” same as the upload-intent endpoint. There is no per-uploader check: filestore does not track uploader identity and UUID-unguessability + schema-per-tenant isolation are the gates against cross-user / cross-tenant abuse, matching the orphan-cleanup task's posture (which also treats every unreferenced file the same way regardless of who uploaded it).

Not exposed via MCP โ€” abandoned-upload cleanup is a UI-driven affordance and the agent surface doesn't have a use case for it.

Authorizations:
BearerAuth
path Parameters
attachment_id
required
string <uuid>
Example: 11111111-aaaa-bbbb-cccc-dddddddddddd

Comment attachment id of the abandoned upload.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

current-device

Self-service on the Device proven by this request, never a user-wide most-recent Device

Disconnect this Device from its Vehicle

Requires a current human login, secondary Device proof and devices:vehicles:assign-self. Ends the exact observed association, including an explicitly released fixed association. A newer episode conflicts. Keeps human login, Tour assignments and retained location; no replacement source is selected. Plugin work guards apply.

Authorizations:
BearerAuth
header Parameters
X-Device-Authorization
required
string

Required Device bearer token alongside the human token. Missing: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Request Body schema: application/json
required
expected_vehicle_association_id
required
string <uuid>

Exact episode observed when this action began; never replace it on retry.

Responses

Request samples

Content type
application/json

observed

{
  • "expected_vehicle_association_id": "00000000-0000-4000-8000-000000000108"
}

Response samples

Content type
application/json

context

{
  • "device_id": "00000000-0000-4000-8000-000000000101"
}

Read the current human login

Proves this request Device with the secondary header. A missing or different current human login is concealed as 404.

Authorizations:
BearerAuth
header Parameters
X-Device-Authorization
required
string

Required Device bearer token alongside the human token. Missing: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Responses

Response samples

Content type
application/json

context

{
  • "id": "00000000-0000-4000-8000-000000000109",
  • "device_id": "00000000-0000-4000-8000-000000000101",
  • "user_id": "00000000-0000-4000-8000-000000000102",
  • "started_at": "2023-02-14T10:00:00Z"
}

Register a fresh human login

A human bearer token and secondary Device bearer token are required. Returns a fresh episode; capture its ID for logout. Registration is not a heartbeat and has no request replay key.

Authorizations:
BearerAuth
header Parameters
X-Device-Authorization
required
string

Required Device bearer token alongside the human token. Missing: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Responses

Response samples

Content type
application/json

context

{
  • "id": "00000000-0000-4000-8000-000000000109",
  • "device_id": "00000000-0000-4000-8000-000000000101",
  • "user_id": "00000000-0000-4000-8000-000000000102",
  • "started_at": "2023-02-14T10:00:00Z"
}

End the captured human login

Ends only the supplied login episode. A newer episode conflicts, including another login by the same person. Retains Device credentials, Vehicle assignment and other human sessions.

Authorizations:
BearerAuth
header Parameters
X-Device-Authorization
required
string

Required Device bearer token alongside the human token. Missing: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Request Body schema: application/json
required
expected_user_association_id
required
string <uuid>

Exact episode observed when this action began; never replace it on retry.

Responses

Request samples

Content type
application/json

observed

{
  • "expected_user_association_id": "00000000-0000-4000-8000-000000000109"
}

Response samples

Content type
application/json

context

{
  • "device_id": "00000000-0000-4000-8000-000000000101"
}

Log out this Device

Requires the Device as primary bearer actor. Both expected IDs are optional and nullable (omitted or null expects no active episode). Cleans up the observed context atomically; a newer episode conflicts. Retains enrollment and Tour assignments. Clear native Device credentials only after acknowledgment. Retry with the same expected IDs after an uncertain response.

Authorizations:
BearerAuth
Request Body schema: application/json
required
expected_vehicle_association_id
string or null <uuid>

Observed Vehicle episode, or omitted/null when none exists.

expected_user_association_id
string or null <uuid>

Observed human login episode, or omitted/null when none exists.

Responses

Request samples

Content type
application/json

observed

{
  • "expected_vehicle_association_id": null,
  • "expected_user_association_id": null
}

Response samples

Content type
application/json

context

{
  • "device_id": "00000000-0000-4000-8000-000000000101"
}

Read this Deviceโ€™s Vehicle context

Accepts human plus secondary Device proof, or the Device as primary actor for its own logout recovery. Returns own episode identity even without Vehicle read permission; never exposes another user profile. A foreign human login is concealed as 404. Empty context omits vehicle_association.

Authorizations:
BearerAuth
header Parameters
X-Device-Authorization
string

Required with a human primary bearer; omitted with a Device primary bearer. Missing: device_proof_missing; malformed or unusable: device_proof_invalid; wrong tenant: tenant_scope; non-Device principal: wrong_actor_type.

Responses

Response samples

Content type
application/json

context

{
  • "device_id": "00000000-0000-4000-8000-000000000101"
}

object-definitions

Object definition schemas and attributes

Get an object

Fetches one object by slug or id.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Update an object

Declaratively replaces an object's metadata and attribute set (optimistic-locked). An attribute sent with its existing id and a changed slug is renamed (the id anchors it); an id-less attribute with an existing slug keeps its identity, otherwise it is added; absent owned attributes are removed. Managed reverse relationship attributes materialized from another object are outside this replacement set: omit them here and update the declaring relationship on its owning object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id

Request Body schema: application/json
required
natural_id_key
string or null^[A-Z][A-Z0-9]{0,15}$

Optional natural ID prefix, unique across definitions when set. Null means numeric-only string IDs. Omission preserves the prefix on PATCH and means no prefix on creation or replacement. Use 1โ€“16 uppercase letters or digits, starting with a letter. Changing it changes displayed IDs without changing record identity or counters.

slug
required
string <= 63 characters ^[a-z][a-z0-9_]*$

Object slug. The plugin_ prefix is reserved for plugin-managed definitions; self and this are reserved words.

required
object

Entity noun per canonical language tag

display_template
string

Display template with {{slug}} placeholders

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon key from the client icon catalog, for example truck. Clients render a default icon for unknown keys. Omission means no icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Palette color of the definition icon. Omission or null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Attribute slugs shown, in order, under the record name and the clicked location in a map popup, for example ["plate_number", "color"]. Each attribute at most once; list-valued attributes (tags, skills, multi-value relationships) are not allowed. Renaming or deleting an attribute updates the list. Omission means none.

required
Array of any (AttributeInput)

The object's full attribute set

lock_version
integer <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

rename, add and remove in one declaration

{
  • "slug": "equipment",
  • "name": {
    },
  • "lock_version": 3,
  • "attributes": [
    ]
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Delete an object

Deletes an object (by slug or id) including its record table. An object targeted by a relationship attribute owned by another object cannot be deleted until that attribute is removed.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update Object definition metadata

Merge metadata without changing attributes. Names merge by language and noun form; null clears display_template, icon, color or map_marker_fields. Managed schemas are locked except for icon, color, map_marker_fields and, where records are numbered per definition, natural_id_key.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object definition UUID or slug

Request Body schema: application/merge-patch+json
required
natural_id_key
string or null^[A-Z][A-Z0-9]{0,15}$

Optional natural ID prefix, unique across definitions when set. Null means numeric-only string IDs. Omission preserves the prefix on PATCH and means no prefix on creation or replacement. Use 1โ€“16 uppercase letters or digits, starting with a letter. Changing it changes displayed IDs without changing record identity or counters.

slug
string <= 63 characters

Definition slug. Null is rejected.

object

Merge by language and noun form. Null language/form removes it. At least one localized name must remain; root null is rejected.

display_template
string or null [ 1 .. 2000 ] characters

Display template; null restores the default label. Blank strings are rejected.

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon catalog key. Omission preserves it; null restores the default icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Icon background palette color. Omission preserves it; null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Ordered popup field selection. Omission preserves it; null clears it to an empty list; an array replaces it. Lists and structured JSON fields are unsupported.

lock_version
integer or null <int64> >= 0

Optional version precondition; stale versions return 409.

Responses

Request samples

Content type
application/merge-patch+json
Example

clearTemplate

{
  • "display_template": null,
  • "lock_version": 0
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Replace the attribute order

Replaces the display order of all attributes atomically, the system attributes (id, created_at, updated_at, lock_version), natural_id and managed reverse relationships included. List every slug of the object's attributes exactly once; the response returns attributes in this order, which also drives record forms and the default list columns. Only the order changes. Until an order is saved, id comes first and created_at, updated_at and lock_version come last. Later attribute additions are appended.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

Request Body schema: application/json
required
attribute_slugs
required
Array of strings non-empty

Slug of every attribute of the object, each exactly once, in display order (first = topmost). This is the set of slugs in the object's attributes.

lock_version
integer <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

TimestampsAfterName

{
  • "attribute_slugs": [
    ],
  • "lock_version": 3
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

List objects

Lists the tenant's objects, paged in stable ascending slug order.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

EquipmentPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create an object

Creates an object with its full attribute set.

Authorizations:
BearerAuth
Request Body schema: application/json
required
natural_id_key
string or null^[A-Z][A-Z0-9]{0,15}$

Optional natural ID prefix, unique across definitions when set. Null means numeric-only string IDs. Omission preserves the prefix on PATCH and means no prefix on creation or replacement. Use 1โ€“16 uppercase letters or digits, starting with a letter. Changing it changes displayed IDs without changing record identity or counters.

slug
required
string <= 63 characters ^[a-z][a-z0-9_]*$

Object slug. The plugin_ prefix is reserved for plugin-managed definitions; self and this are reserved words.

required
object

Entity noun per language tag, e.g. {"en": {"singular": "Asset", "plural": "Assets"}}

display_template
string

Display template with {{slug}} placeholders

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon key from the client icon catalog, for example truck. Clients render a default icon for unknown keys. Omission means no icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Palette color of the definition icon. Omission or null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Attribute slugs shown, in order, under the record name and the clicked location in a map popup, for example ["plate_number", "color"]. Each attribute at most once; list-valued attributes (tags, skills, multi-value relationships) are not allowed. Renaming or deleting an attribute updates the list. Omission means none.

required
Array of any (AttributeInput)

The object's typed attributes

Responses

Request samples

Content type
application/json
Example

maintenance request

{
  • "slug": "maintenance_request",
  • "name": {
    },
  • "display_template": "{{title}}",
  • "attributes": [
    ]
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Add an attribute

Adds one attribute to an object (incremental). Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

Request Body schema: application/json
required
id
string <uuid>

Existing attribute id (omit on create; send to update/rename)

slug
required
string <= 200 characters ^[a-z][a-z0-9_]*$

Attribute slug; self, this and platform record fields are reserved.

type
required
string

Attribute type selecting this configuration.

object

Attribute label per language tag, e.g. {"en": "Purchase price"}

description
string

Optional attribute description

object (TextAttributeConfigInput)

Configuration for text attributes.

lock_version
integer <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

AddSerialNumber

{
  • "slug": "serial_number",
  • "type": "text",
  • "name": {
    },
  • "config": {
    },
  • "lock_version": 3
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Create a state

Adds one state to a state attribute. Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Attribute slug or stable id.

Request Body schema: application/json
required
value
required
string

Mutable state value/code

title
required
string

Display title for the state

color
required
string

Color code used to render the state

lock_version
integer <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

AddBlocked

{
  • "value": "blocked",
  • "title": "Blocked",
  • "color": "#FF0000"
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Create a select option

Adds one option to a select attribute. Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Attribute slug or stable id.

Request Body schema: application/json
required
value
required
string

Mutable option value/code

title
required
string

Display title for the option

lock_version
integer <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

AddLeased

{
  • "value": "leased",
  • "title": "Leased"
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Delete an attribute

Removes one owned attribute (by slug or id). Managed reverse relationships must be deleted from the declaring attribute on their owning object. Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Target attribute slug or id

Responses

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Update an attribute

Updates/renames one attribute (by slug or id). Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Target attribute slug or id

Request Body schema: application/merge-patch+json
required
id
string or null <uuid>

Optional identity assertion; must match the routed attribute.

type
string or null
Enum: "text" "license_plate" "vin" "number" "date" "date_time" "boolean" "select" "state" "capacity" "measure" "currency" "rating" "email" "phone" "tags" "required_skills" "provided_skills" "relationship" "location" "raw_json" "rich_text" "full_name" "links" null

Optional type assertion; cannot change the stored type.

slug
string <= 200 characters ^[a-z][a-z0-9_]*$

New slug. Omission preserves it; null cannot clear it.

object

Merge localized labels. Null at a language key removes that translation.

description
string or null

Null clears the description; blank text is rejected.

object or null

Merge type-specific configuration keys with the stored configuration. Null clears an optional setting; null config resets optional configuration. Required settings, immutable uniqueness, unknown keys and keys belonging to another type are validated after merging.

Array of objects (SelectOptionInput)

Select only: replaces choices; [] clears them. Existing choice IDs preserve stored values.

Array of objects (StateInput)

State only: replaces states; [] clears them. Existing state IDs preserve stored values.

lock_version
integer or null <int64> >= 0

Optional definition version precondition.

Responses

Request samples

Content type
application/merge-patch+json

RenameToMinStock

{
  • "id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  • "slug": "min_stock",
  • "type": "number",
  • "name": {
    },
  • "config": {
    }
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Delete a state

Removes one state (by value or id). Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Attribute slug or stable id.

state_ref
required
string

Target state value or id

Responses

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Update a state

Updates one state's mutable value, title, and/or color (found by value or id). Its stable id and record references stay unchanged. Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Attribute slug or stable id.

state_ref
required
string

Target state value or id

Request Body schema:
required
value
string

New mutable state value/code. Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” a state value cannot be cleared.

title
string

New display title. Omitted leaves the title unchanged. Explicit null is rejected (422) โ€” a state title cannot be cleared.

color
string

New color code. Omitted leaves the color unchanged. Explicit null is rejected (422) โ€” a state color cannot be cleared.

lock_version
integer or null <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type

RecolorOnly

{
  • "color": "#F59E0B"
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Delete a select option

Removes one select option (by value or id). Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Attribute slug or stable id.

option_ref
required
string

Target option value or id

Responses

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Update a select option

Updates one select option's mutable value and/or title (found by value or id). Its stable id and record references stay unchanged. Returns the updated object.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Object slug or UUID id.

attribute_ref
required
string

Attribute slug or stable id.

option_ref
required
string

Target option value or id

Request Body schema:
required
value
string

New mutable option value/code. Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” an option value cannot be cleared.

title
string

New display title. Omitted leaves the title unchanged. Explicit null is rejected (422) โ€” an option title cannot be cleared.

lock_version
integer or null <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
Example

RelabelOnly

{
  • "title": "Scheduled"
}

Response samples

Content type
application/json

Equipment

{
  • "id": "7f8e0d3a-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  • "slug": "equipment",
  • "name": {
    },
  • "display_template": "{{name}} ({{asset_tag}})",
  • "icon": "toolbox",
  • "color": "orange",
  • "map_marker_fields": [
    ],
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "is_readonly": false,
  • "attributes": [
    ],
  • "created_at": "2026-07-01T09:30:00Z",
  • "updated_at": "2026-07-02T14:00:00Z",
  • "lock_version": 3,
  • "resource_type": "object",
  • "is_relationship_target": true
}

Tour Item Order

Complete ordering and grouping of assigned Tasks and planned stops

Get the complete tour item order

Requires tour read access. Every assigned Task occurs once, either directly in the root sequence or inside a planned stop.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent Tour UUID

Responses

Response samples

Content type
application/json

OrderedItems

{
  • "items": [
    ],
  • "lock_version": 2
}

Replace the complete tour item order

Requires tours:update or own ad-hoc planning access. Changes root order, grouping and child order atomically without editing Tasks. Supply every assigned Task and standalone stop exactly once. Empty automatic stops disappear. An empty list is valid only when no assigned Tasks or standalone stops remain.

Authorizations:
BearerAuth
path Parameters
tour_id
required
string <uuid>

Parent Tour UUID

Request Body schema: application/json
required
required
Array of any (TourOrderItem) [ 0 .. 10000 ] items
lock_version
integer or null <int64> >= 0

Parent Tour version; omitted or null skips the precondition.

Responses

Request samples

Content type
application/json

Reorder

{
  • "items": [
    ],
  • "lock_version": 2
}

Response samples

Content type
application/json

OrderedItems

{
  • "items": [
    ],
  • "lock_version": 2
}

Webhook Delivery Failures

View recorded webhook failures and retry status

List webhook delivery failures

Retrieve a paginated list of webhook delivery failures for the current tenant.

A row represents the latest recorded failed attempt for one webhook message. The same row is updated when another retry fails, while the first and latest failure timestamps remain available. This endpoint is not a full delivery or per-attempt audit ledger: successful attempts and deliveries skipped before an HTTP request are not recorded. A successful retry after an earlier failure does not add a success record, so absence does not prove success and presence alone does not prove the message ultimately failed.

Use the filters to narrow down results by time range, endpoint, or event type.

Requires any of 'webhooks:read', 'webhooks:create', or 'webhooks:update' grant.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based). First page is 0.

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page. Maximum allowed is 100.

failed_from
string <date-time>
Example: failed_from=2024-01-01T00:00:00Z

Return failures whose first failed attempt occurred at or after this RFC 3339 timestamp (inclusive).

failed_to
string <date-time>
Example: failed_to=2025-01-01T00:00:00Z

Return failures whose first failed attempt occurred before this RFC 3339 timestamp (exclusive).

endpoint_id
string <uuid>
Example: endpoint_id=019bb29d-2458-722e-b21b-679e632ca96b

Filter by specific webhook endpoint ID.

event_type
string
Example: event_type=area.created

Filter by event type.

sort
string
Default: "first_attempt_failed_at:desc"
Example: sort=first_attempt_failed_at:desc

Single sorting criterion in property:direction format. Allowed properties: first_attempt_failed_at, attempt, event_type, endpoint_id. Allowed directions: asc, desc. Default is first_attempt_failed_at:desc.

Responses

Response samples

Content type
application/json

DeliveryFailuresResponse

{
  • "items": [
    ],
  • "page": {
    }
}

Billing Portal

Stripe Billing Portal and payment-method API

Re-check billing status against Stripe

Pulls the tenant's live subscription status from Stripe and updates the stored billing standing, then returns the refreshed decision. Acts as a fallback when a Stripe webhook has not yet arrived โ€” e.g. a user who just updated their payment method on the billing-locked screen and wants to unlock immediately. Reachable while the tenant is billing-locked.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

ActiveAlpineBilling

{
  • "allowed": true,
  • "status": "ACTIVE"
}

Open a Stripe Customer Portal session

Returns a one-time URL the client should redirect the user to so they can manage their payment method in Stripe's hosted Customer Portal. The tenant must already have a Stripe customer (paid plan).

Authorizations:
BearerAuth
Request Body schema: application/json
required
return_url
required
string [ 0 .. 2048 ] characters

Absolute URL the customer is redirected to after closing the Stripe Customer Portal. The origin must match the tenant's primary domain or one of its configured custom domains.

Responses

Request samples

Content type
application/json

CreateAlpineBillingPortalSession

Response samples

Content type
application/json

AlpineBillingPortalSession

Get the default payment method on file

Returns a summary (brand, last4, expiry) of the default payment method attached to the tenant's Stripe customer. The has_payment_method flag is false when no card is on file yet.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

AlpinePaymentMethod

{
  • "has_payment_method": true,
  • "brand": "visa",
  • "last4": "4242",
  • "exp_month": 12,
  • "exp_year": 2028
}

Tenant

Tenant API

Create a tenant logo upload intent

Creates a presigned upload form for a new tenant logo.

Authorizations:
BearerAuth
Request Body schema: application/json
required
original_file_name
required
string non-empty

Original filename

mime_type
required
string non-empty ^[iI][mM][aA][gG][eE]/([pP][nN][gG]|[jJ][pP][...

MIME type (image/png, image/jpeg or image/jpg, case-insensitive)

Responses

Request samples

Content type
application/json

CreateTenantLogoUpload

{
  • "original_file_name": "alpine-facility-services-logo.png",
  • "mime_type": "image/png"
}

Response samples

Content type
application/json

AlpineTenantLogoUpload

{}

Create a tenant favicon upload intent

Creates a presigned upload form for a new tenant favicon.

Authorizations:
BearerAuth
Request Body schema: application/json
required
original_file_name
required
string non-empty

Original filename

mime_type
required
string non-empty ^[iI][mM][aA][gG][eE]/([pP][nN][gG]|[jJ][pP][...

MIME type (image/png, image/jpeg or image/jpg, case-insensitive)

Responses

Request samples

Content type
application/json

CreateTenantFaviconUpload

{
  • "original_file_name": "alpine-favicon.png",
  • "mime_type": "image/png"
}

Response samples

Content type
application/json

AlpineTenantFaviconUpload

{}

Get tenant

Returns the tenant data for the authenticated account.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

AlpineTenant

{
  • "name": "Alpine Facility Services GmbH",
  • "language": "de",
  • "region": "AT",
  • "timezone": "Europe/Vienna",
  • "lock_version": 0
}

Update tenant

JSON Merge Patch (RFC 7386). Omitted fields remain unchanged. help_url is the only clearable field: send an explicit null to fall back to the platform default.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
name
string <= 255 characters

Tenant name. Omitted leaves the value unchanged; explicit null is rejected (422).

language
string <= 10 characters

Tenant content language tag. Legacy locale-style values such as en-US are accepted and normalized. Omitted leaves the value unchanged; explicit null is rejected (422).

region
string <= 2 characters

Tenant region as ISO 3166-1 alpha-2 country code. Omitted leaves the value unchanged; explicit null is rejected (422).

timezone
string <= 50 characters

Tenant timezone as IANA timezone identifier. Omitted leaves the value unchanged; explicit null is rejected (422).

help_url
string or null <= 2048 characters

Absolute http(s) URL opened by the Help entry in the workspace header menu. Omitted leaves the value unchanged; explicit null clears it so clients use the platform default.

lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check.

Responses

Request samples

Content type
application/merge-patch+json
Example

UpdateName

{
  • "name": "Alpine Facility Services GmbH",
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedAlpineTenant

{
  • "name": "Alpine Facility Services GmbH",
  • "language": "de",
  • "region": "AT",
  • "timezone": "Europe/Vienna",
  • "lock_version": 0
}

Get tenant logo upload status

Returns upload and application status for a tenant logo upload intent.

Authorizations:
BearerAuth
path Parameters
file_id
required
string <uuid>

UUID of the uploaded file.

Responses

Response samples

Content type
application/json

UploadedAlpineTenantLogo

{}

Get the tenant favicon

Returns the current tenant favicon URL when a favicon is configured.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

AlpineTenantFavicon

Delete the tenant favicon

Removes the current tenant favicon. Repeating the request is safe.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Get tenant favicon upload status

Returns upload and application status for a tenant favicon upload intent.

Authorizations:
BearerAuth
path Parameters
file_id
required
string <uuid>

UUID of the uploaded file.

Responses

Response samples

Content type
application/json

UploadedAlpineTenantFavicon

{}

AI Assistant Settings

Manage AI assistant settings for the tenant.

Get AI assistant settings

Returns the current AI assistant operating mode for this tenant.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

ReadOnlyAssistantSettings

{
  • "mode": "READ_ONLY",
  • "enabled": true,
  • "tool_mode": "READ_ONLY",
  • "tenant_id": "00000000-0000-4000-8000-000000000001"
}

Update AI assistant settings

Updates the AI assistant mode. OFF disables the assistant, READ_ONLY enables read-only tools, and READ_WRITE enables read and write-capable tools.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
mode
string
Enum: "OFF" "READ_ONLY" "READ_WRITE"

New assistant mode. OFF disables the assistant, READ_ONLY enables read-only tool access, READ_WRITE enables read and write-capable tool access. Omit to leave unchanged; explicit null is rejected (422).

Responses

Request samples

Content type
application/merge-patch+json

EnableReadOnlyAssistant

{
  • "mode": "READ_ONLY"
}

Response samples

Content type
application/json

UpdatedReadOnlyAssistantSettings

{
  • "mode": "READ_ONLY",
  • "enabled": true,
  • "tool_mode": "READ_ONLY",
  • "tenant_id": "00000000-0000-4000-8000-000000000001"
}

Devices

Device management API

List devices

Returns a paginated list of devices with their latest telemetry snapshot.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

sort
Array of strings
Example: sort=natural_id:asc

Repeated sorting criteria in field:direction format. Allowed fields: id, natural_id, created_at, updated_at, device_model, device_identity_id, kind, provisioning_state, last_received_at, last_reported_at. Default: created_at:desc.

search
string

Case-insensitive search in model, identity, phone number, or description; also matches an exact displayed natural ID such as MOB-12.

natural_id
string
Example: natural_id=MOB-12

Exact natural ID: the number shared across kinds (12) or its kind-prefixed form (MOB-12, GPS-12, TRK-12). A prefix of another kind matches nothing. Whitespace, lowercase prefixes, leading zeroes and non-positive numbers return 422.

model
string

Filter by device model (case-insensitive substring match).

kind
string
Enum: "TOURFOLD_APP" "THIRD_PARTY_OSMAND" "TRACKING_DEVICE"

Filter by device kind.

has_location
boolean

Filter to devices with or without a latest location.

updated_from
string <date-time>

Filter to devices updated at or after this timestamp.

updated_to
string <date-time>

Filter to devices updated before this timestamp.

include
Array of strings
Items Value: "current_state"
Example: include=current_state

Optional related resources to embed. Supported: current_state.

min_lat
number <double> [ -90 .. 90 ]

Latest-location bounding box: minimum latitude. All four bbox corners must be supplied together.

min_lon
number <double> [ -180 .. 180 ]

Latest-location bounding box: minimum longitude. All four bbox corners must be supplied together.

max_lat
number <double> [ -90 .. 90 ]

Latest-location bounding box: maximum latitude. All four bbox corners must be supplied together.

max_lon
number <double> [ -180 .. 180 ]

Latest-location bounding box: maximum longitude. All four bbox corners must be supplied together.

unassociated_only
boolean
Default: false

When true, only return devices without an active vehicle association.

Responses

Response samples

Content type
application/json

TechnicianDevicesPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create a device

Creates a device. Provisioning state is system-managed and is not accepted in this request.

Authorizations:
BearerAuth
Request Body schema: application/json
required
description
string [ 0 .. 2048 ] characters
device_identity_id
string [ 0 .. 255 ] characters

Required for tracking hardware; otherwise may be bound during setup.

device_model
string [ 0 .. 128 ] characters
kind
required
string
logout_device_with_user
boolean

When true, logging the human out also ends the device (telemetry) session. Defaults to false.

phone_number
string [ 0 .. 32 ] characters

International phone number with explicit country code; normalized to E.164.

platform
required
string
Enum: "IOS" "ANDROID"

Supported Tourfold app platforms

app_location_tracking_policy_override
string or null
Enum: "disabled" "during_work" "continuous" null

App GPS policy override. Omission or null inherits the workspace policy.

Responses

Request samples

Content type
application/json

CreateTechnicianDevice

{
  • "kind": "TOURFOLD_APP",
  • "device_model": "Pixel 9",
  • "device_identity_id": "jonas-pixel-9",
  • "phone_number": "+43 664 123 45 67",
  • "platform": "ANDROID",
  • "logout_device_with_user": false,
  • "description": "Jonas Leitner's service device"
}

Response samples

Content type
application/json

CreatedTechnicianDevice

{
  • "id": "00000000-0000-4000-8000-000000004001",
  • "created_at": "2026-08-20T08:00:00Z",
  • "updated_at": "2026-08-20T08:00:00Z",
  • "lock_version": 0,
  • "natural_id": "MOB-17",
  • "kind": "TOURFOLD_APP",
  • "effective_app_location_tracking_policy": "continuous",
  • "app_location_tracking_policy_source": "workspace",
  • "device_model": "Pixel 9",
  • "device_identity_id": "jonas-pixel-9",
  • "provisioning_state": "PROVISIONED",
  • "phone_number": "+436641234567",
  • "platform": "ANDROID",
  • "logout_device_with_user": false,
  • "self_enrolled": false,
  • "enrolled": true,
  • "description": "Jonas Leitner's service device"
}

Generate a device setup code

Generates a setup payload the client renders as a QR code. The payload is routed by device kind: a rotating Tourfold App enrollment link, the idempotent OsmAnd intake URL, or the tracking-device connection-profile endpoint. Secret-bearing material is only ever returned from this action, never from Device reads.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

TechnicianAppSetupCode

{}

Send a device setup SMS

Sends a Tourfold App setup link to the device's stored phone number. The link carries a one-time enrollment secret and is delivered only in the SMS โ€” the response never includes the URL or secret. Supported for Tourfold App devices only, and only while the workspace's device fleet is admin-managed.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

TechnicianSetupSmsScheduled

{
  • "device_id": "00000000-0000-4000-8000-000000004001",
  • "sent_to": "+4369917246437",
  • "expires_at": "2026-08-20T10:30:00Z"
}

Send a device setup email

Emails a Tourfold App setup link to the given address (for SIM-less devices where the SMS channel is unavailable). The link carries a one-time enrollment secret and is delivered only in the email โ€” the response never includes the URL or secret. Supported for Tourfold App devices only, and only while the workspace's device fleet is admin-managed.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Request Body schema: application/json
required
email
required
string <email> non-empty

Email address to deliver the setup link to (chosen by the admin โ€” a device has no mailbox of its own).

Responses

Request samples

Content type
application/json

SendSetupEmailToAdmin

{
  • "email": "jonas.leitner@example.com"
}

Response samples

Content type
application/json

TechnicianSetupEmailSent

{
  • "device_id": "00000000-0000-4000-8000-000000004001",
  • "sent_to": "jonas.leitner@example.com",
  • "expires_at": "2026-08-20T10:30:00Z"
}

Rotate a device intake secret

Rotates the device intake secret, invalidating the previous one. Returns no body โ€” the new usable configuration (URL + secret) is obtained via the setup-codes action, keeping a single rendering path and never exposing the secret in a cacheable response.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Reset a device's enrollment

Clears the device's registered credential so a reinstalled or replaced app can pair again under the same device id, with a setup link generated afterwards. The app currently installed on the device is signed out at once and stops reporting until it is set up again. Setup links generated before the reset stop working. The device keeps its vehicle connection, tours and history. Supported for Tourfold App devices only, and only while the workspace's device fleet is admin-managed.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

ResetTechnicianDeviceEnrollment

{
  • "device_id": "00000000-0000-4000-8000-000000004001",
  • "enrolled": false,
  • "connected_vehicle_id": "00000000-0000-4000-8000-000000005001",
  • "connected_vehicle_on_active_tour": true
}

Enroll (pair) a device

Redeems the device's pairing secret and registers its public key as a per-device Keycloak client. After this the device authenticates to Keycloak by signature (private_key_jwt). Authenticated by the pairing secret, not a user token. Pairing succeeds once per device: a device that is already enrolled returns 409. After an admin resets the enrollment (resetDeviceEnrollment), a setup link generated afterwards pairs the device again.

path Parameters
device_id
required
string <uuid>

UUID of the device.

header Parameters
X-Tenant-Id
required
string <uuid>

Workspace the device belongs to. Required because this operation is authenticated by the pairing secret in the body, not a bearer token, so no workspace context can be derived from a token.

Request Body schema: application/json
required
secret
required
string non-empty

The pairing secret delivered to the device (the enrollment token).

required
object non-empty

The device's public key as an EC P-256 JWK (kty=EC, crv=P-256, x, y). alg and use are forced to ES256/sig server-side.

challenge
string

The single-use nonce from POST /api/v2/devices/{device_id}/enroll/challenge. Required unless attestation is disabled for this environment.

object (DeviceAttestation)

Platform attestation bound to SHA256(challenge || public_key). Required unless attestation is disabled for this environment.

Responses

Request samples

Content type
application/json

EnrollIosDevice

{
  • "secret": "6b1f9a7c4d2e08b35fa17c9e3d4b8021",
  • "public_key": {
    },
  • "challenge": "0f2c7d51-8a34-4d6b-9c1e-2f5b7a904e13",
  • "attestation": {
    }
}

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Complete self-enrollment of the calling user's device

Uploads the device's public key and registers it as a per-device Keycloak client, authorized by the user's token plus a platform attestation bound to the key. Like the pairing path, enrollment succeeds once per device: an already-enrolled device returns 409 and its key is never rotated through this endpoint. An install that lost its key (app reinstall) self-enrolls again under a fresh device_identity_id.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Request Body schema: application/json
required
required
object non-empty

The device's public key as an EC P-256 JWK (kty=EC, crv=P-256, x, y). alg and use are forced to ES256/sig server-side.

challenge
string

The single-use nonce from POST /api/v2/devices/{device_id}/enroll/self/challenge. Required unless attestation is disabled for this environment.

object (DeviceAttestation)

Platform attestation bound to SHA256(challenge || public_key). Required unless attestation is disabled for this environment.

Responses

Request samples

Content type
application/json

CompleteSelfEnrollment

{
  • "public_key": {
    },
  • "challenge": "0f2c7d51-8a34-4d6b-9c1e-2f5b7a904e13",
  • "attestation": {
    }
}

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Get an attestation challenge for a self-enrolled device

Issues a single-use nonce for a self-enrolled device to attest over before completing enrollment. The device attests to SHA256(nonce || public_key), binding the platform's proof to the exact key it is about to register. Authenticated by the user's token. An already-enrolled device is refused.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

SelfEnrollmentChallenge

{
  • "nonce": "0f2c7d51-8a34-4d6b-9c1e-2f5b7a904e13",
  • "expires_at": "2026-08-20T08:05:00Z"
}

Migrate a legacy device to Keycloak

Background auto-migration for an already-logged-in legacy device: authenticated by the device's existing legacy token (not a pairing secret), it uploads its public key and is issued a per-device Keycloak client. The tenant and device are taken from the verified token; the path device id must match the token's device id. Enrollment succeeds once per device: a device that already holds a Keycloak identity returns 409.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Request Body schema: application/json
required
required
object non-empty

The device's public key as an EC P-256 JWK (kty=EC, crv=P-256, x, y). alg and use are forced to ES256/sig server-side.

challenge
string

The single-use nonce from POST /api/v2/devices/enroll/challenge. Required unless attestation is disabled for this environment.

object (DeviceAttestation)

Platform attestation bound to SHA256(challenge || public_key). Required unless attestation is disabled for this environment.

Responses

Request samples

Content type
application/json

MigrateAndroidDevice

{
  • "public_key": {
    },
  • "challenge": "0f2c7d51-8a34-4d6b-9c1e-2f5b7a904e13",
  • "attestation": {
    }
}

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Get an attestation challenge for device pairing

Issues a single-use nonce for a pairing device to attest over before redeeming its pairing secret at POST /api/v2/devices/{device_id}/enroll. The pairing device holds no token, so the pairing secret authorizes the issuance โ€” like /enroll itself, this endpoint is authenticated by the secret, not a user token. An already-enrolled device is refused.

path Parameters
device_id
required
string <uuid>

UUID of the device.

header Parameters
X-Tenant-Id
required
string <uuid>

Workspace the device belongs to. Required because this operation is authenticated by the pairing secret in the body, not a bearer token, so no workspace context can be derived from a token.

Request Body schema: application/json
required
secret
required
string non-empty

The pairing secret delivered to the device (the enrollment token).

Responses

Request samples

Content type
application/json

PairingChallengeRequest

{
  • "secret": "6b1f9a7c4d2e08b35fa17c9e3d4b8021"
}

Response samples

Content type
application/json

PairingChallenge

{
  • "nonce": "0f2c7d51-8a34-4d6b-9c1e-2f5b7a904e13",
  • "expires_at": "2026-08-20T08:05:00Z"
}

Deactivate a device

Marks a device as inactive while keeping telemetry history and intake data.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

DeactivatedTechnicianDevice

{
  • "id": "00000000-0000-4000-8000-000000004001",
  • "created_at": "2026-08-20T08:00:00Z",
  • "updated_at": "2026-08-20T10:00:00Z",
  • "lock_version": 2,
  • "natural_id": "MOB-17",
  • "kind": "TOURFOLD_APP",
  • "effective_app_location_tracking_policy": "continuous",
  • "app_location_tracking_policy_source": "workspace",
  • "device_model": "Pixel 9",
  • "device_identity_id": "jonas-pixel-9",
  • "provisioning_state": "DISABLED",
  • "phone_number": "+4369917246437",
  • "platform": "ANDROID",
  • "logout_device_with_user": false,
  • "self_enrolled": false,
  • "enrolled": true,
  • "description": "Jonas Leitner's service device"
}

Activate a device

Marks an inactive device as provisioned and usable again.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

ActivatedTechnicianDevice

{
  • "id": "00000000-0000-4000-8000-000000004001",
  • "created_at": "2026-08-20T08:00:00Z",
  • "updated_at": "2026-08-20T08:00:00Z",
  • "lock_version": 0,
  • "natural_id": "MOB-17",
  • "kind": "TOURFOLD_APP",
  • "effective_app_location_tracking_policy": "continuous",
  • "app_location_tracking_policy_source": "workspace",
  • "device_model": "Pixel 9",
  • "device_identity_id": "jonas-pixel-9",
  • "provisioning_state": "PROVISIONED",
  • "phone_number": "+436641234567",
  • "platform": "ANDROID",
  • "logout_device_with_user": false,
  • "self_enrolled": false,
  • "enrolled": true,
  • "description": "Jonas Leitner's service device"
}

Self-enroll the calling user's device

Registers the calling user's own device: creates the device row for this install, or returns the existing one โ€” idempotent on device_identity_id until enrollment completes; a colliding identity that already holds a key returns 409. Follow up with POST /api/v2/devices/{device_id}/enroll/self/challenge and POST /api/v2/devices/{device_id}/enroll/self to complete enrollment. Refused with 422 (devices/self-enrollment-not-allowed) on workspaces that provision devices through admin setup links.

Authorizations:
BearerAuth
Request Body schema: application/json
required
device_identity_id
required
string [ 0 .. 255 ] characters

Stable per-install identifier generated by the app. Stored alongside the device keypair, so an install that loses its key also loses this id and self-enrolls as a new device.

platform
string
Enum: "UNKNOWN" "IOS" "ANDROID"

Mobile platform of the device

device_model
string [ 0 .. 128 ] characters

Human-readable device model

description
string

Optional notes

Responses

Request samples

Content type
application/json

SelfEnrollIosDevice

{
  • "device_identity_id": "8f3a1c92-5d47-4e08-b6a1-0c7e2f4b93d5",
  • "platform": "IOS",
  • "device_model": "iPhone 15"
}

Response samples

Content type
application/json

ExistingSelfEnrolledDevice

{
  • "id": "00000000-0000-4000-8000-000000004002",
  • "created_at": "2026-08-20T08:00:00Z",
  • "updated_at": "2026-08-20T08:00:00Z",
  • "lock_version": 0,
  • "natural_id": "MOB-18",
  • "kind": "TOURFOLD_APP",
  • "effective_app_location_tracking_policy": "continuous",
  • "app_location_tracking_policy_source": "workspace",
  • "device_model": "iPhone 15",
  • "device_identity_id": "8f3a1c92-5d47-4e08-b6a1-0c7e2f4b93d5",
  • "provisioning_state": "NOT_PROVISIONED",
  • "platform": "IOS",
  • "logout_device_with_user": false,
  • "self_enrolled": true,
  • "enrolled": false
}

Get an attestation challenge

Issues a single-use nonce for the device to attest over before enrolling. The device attests to SHA256(nonce || public_key), binding the platform's proof to the exact key it is about to register. Authenticated by the device's existing legacy token; the device is taken from the verified token.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

MigrationChallenge

{
  • "nonce": "0f2c7d51-8a34-4d6b-9c1e-2f5b7a904e13",
  • "expires_at": "2026-08-20T08:05:00Z"
}

Get a device

Returns a device. Set include_deleted=true to read retained tracker history. Historical devices are read-only and have no current state.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

query Parameters
include
Array of strings
Items Value: "current_state"
Example: include=current_state

Optional related resources to embed. Supported: current_state.

include_deleted
boolean
Default: false

Include retained deleted tracker records. Requires the same workspace and read permission.

Responses

Response samples

Content type
application/json

TechnicianDevice

{
  • "id": "00000000-0000-4000-8000-000000004001",
  • "created_at": "2026-08-20T08:00:00Z",
  • "updated_at": "2026-08-20T08:00:00Z",
  • "lock_version": 0,
  • "natural_id": "MOB-17",
  • "kind": "TOURFOLD_APP",
  • "effective_app_location_tracking_policy": "continuous",
  • "app_location_tracking_policy_source": "workspace",
  • "device_model": "Pixel 9",
  • "device_identity_id": "jonas-pixel-9",
  • "provisioning_state": "PROVISIONED",
  • "phone_number": "+436641234567",
  • "platform": "ANDROID",
  • "logout_device_with_user": false,
  • "self_enrolled": false,
  • "enrolled": true,
  • "description": "Jonas Leitner's service device"
}

Delete a device

Deletes a device. Hardware trackers retain their telemetry and ended Vehicle assignments as read-only history and release their identifier after provider cleanup. End all current assignments first. A failed cleanup remains pending; retry DELETE. Repeating DELETE for a retained deleted tracker returns 204. App and OsmAnd devices are erased and cannot be deleted while they have assignment history.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a device

JSON Merge Patch (RFC 7386): omitted fields remain unchanged; a field set to null is cleared (phone_number and description). Provisioning state is system-managed and cannot be changed through this endpoint.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Request Body schema: application/merge-patch+json
required
lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check. Device telemetry does not advance it.

kind
string
Enum: "TOURFOLD_APP" "THIRD_PARTY_OSMAND" "TRACKING_DEVICE"

Device kind. Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” kind is required and cannot be cleared.

device_model
string or null

Human-readable model or tracker type. Omitted leaves the value unchanged; explicit null clears it.

device_identity_id
string or null

Stable device identifier. Omitted leaves the value unchanged; explicit null clears it except for tracking hardware. Once set it cannot be changed to a different value.

connection_profile
string or null

Provider connection profile selected for tracking hardware, for example OSMAND_HTTP_ONLY. Omitted leaves the value unchanged. Required and non-clearable for tracking hardware; not applicable to other kinds.

phone_number
string or null

International phone number. An explicit '+' country code is required; common formatting is accepted and normalized to canonical E.164. National numbers are rejected. Omitted leaves the value unchanged; explicit null clears it.

platform
string
Enum: "UNKNOWN" "IOS" "ANDROID"

Mobile platform. Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” platform is required and cannot be cleared.

description
string or null

Optional operator notes. Omitted leaves the value unchanged; explicit null clears it.

logout_device_with_user
boolean or null

When true, logging the human out also ends the device (telemetry) session. Omit to leave unchanged.

app_location_tracking_policy_override
string or null
Enum: "disabled" "during_work" "continuous" null

Tourfold app Devices only. Omit to preserve; null resumes inheritance; a value overrides the workspace policy.

Responses

Request samples

Content type
application/merge-patch+json
Example

UpdateTechnicianPhone

{
  • "lock_version": 0,
  • "phone_number": "+43 699 172 464 37"
}

Response samples

Content type
application/json

UpdatedTechnicianDevice

{
  • "id": "00000000-0000-4000-8000-000000004001",
  • "created_at": "2026-08-20T08:00:00Z",
  • "updated_at": "2026-08-20T09:30:00Z",
  • "lock_version": 1,
  • "natural_id": "MOB-17",
  • "kind": "TOURFOLD_APP",
  • "effective_app_location_tracking_policy": "continuous",
  • "app_location_tracking_policy_source": "workspace",
  • "device_model": "Pixel 9",
  • "device_identity_id": "jonas-pixel-9",
  • "provisioning_state": "PROVISIONED",
  • "phone_number": "+4369917246437",
  • "platform": "ANDROID",
  • "logout_device_with_user": false,
  • "self_enrolled": false,
  • "enrolled": true,
  • "description": "Jonas Leitner's service device"
}

Get a device's enrollment

Returns whether the device's app install holds a registered credential, and what an enrollment reset would interrupt: the vehicle the device is connected to and whether that vehicle is on an active tour.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

EnrolledTechnicianDevice

{
  • "device_id": "00000000-0000-4000-8000-000000004001",
  • "enrolled": true,
  • "connected_vehicle_id": "00000000-0000-4000-8000-000000005001",
  • "connected_vehicle_on_active_tour": true
}

Get a device's current state

Returns the latest materialized state (status, location, battery, app) for one device.

Authorizations:
BearerAuth
path Parameters
device_id
required
string <uuid>

UUID of the device.

Responses

Response samples

Content type
application/json

TechnicianDeviceCurrentState

{
  • "device_id": "00000000-0000-4000-8000-000000004001",
  • "last_seen_at": "2026-08-20T09:29:45Z",
  • "status": {
    }
}

List supported device types

Returns neutral supported device kinds and setup profiles. Provider internals and credentials are not exposed.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

SupportedTrackingDevice

{
  • "items": [
    ]
}

Bulk-read device current states

Returns the latest materialized state for the requested, tenant-visible devices, ordered by device UUID ascending. Duplicate ids are returned once; unknown or other-tenant ids are omitted. Requires 1โ€“100 ids, counting duplicates, supplied as repeated device_ids parameters.

Authorizations:
BearerAuth
query Parameters
device_ids
required
Array of strings <uuid> [ 1 .. 100 ] items [ items <uuid > ]

Required device UUIDs, from 1 to 100 values. Repeat the device_ids query parameter for each value; CSV and blank values are rejected.

Responses

Response samples

Content type
application/json

TechnicianDeviceCurrentStates

{
  • "items": [
    ]
}

task-definitions

Protected system Task bases and tenant custom definitions

Get a Task definition

Resolve a concrete Task definition by UUID or slug in the Task family.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Concrete Task definition UUID or slug

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

inspection

{
  • "id": "21d3f004-0000-4000-8000-000000000001",
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "is_extendable": false,
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "attributes": [
    ],
  • "resource_type": "task",
  • "is_readonly": false,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

Replace a Task definition

Atomically replace the full authored schema. Missing attributes are removed subject to usage guards. Execution type is immutable. Omitted or null natural_id_key clears the prefix; all Tasks retain their shared sequence. Stable IDs or unchanged slugs preserve attribute identity. System definitions are protected.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Concrete Task definition UUID or slug

Request Body schema: application/json
required
slug
required
string <= 63 characters ^[a-z][a-z0-9_]*$

Tenant Task definition slug; managed prefixes and reserved names are forbidden.

required
object

Localized singular/plural names.

execution_type
required
string
Enum: "simple" "workflow_single_choice_question" "workflow_free_text_question" "visit"

Immutable system execution type. Only simple and visit can be extended.

natural_id_key
string or null <= 16 characters ^[A-Z][A-Z0-9]{0,15}$

Optional workspace-unique presentation prefix. All Tasks share one numeric sequence regardless of definition. Omitted or null means no prefix.

required
Array of any (AttributeInput) <= 20 items

Authored custom fields only. Native fields cannot be overridden; Task targets and reverse fields are not supported.

lock_version
integer <int64> >= 0

Optional version precondition. Omitted or null skips the client version check; stale values return 409.

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon key from the client icon catalog, for example truck. Clients render a default icon for unknown keys. Omission means no icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Palette color of the definition icon. Omission or null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Attribute slugs shown, in order, under the record name and the clicked location in a map popup, for example ["plate_number", "color"]. Each attribute at most once; list-valued attributes (tags, skills, multi-value relationships) are not allowed. Renaming or deleting an attribute updates the list. Omission means none.

Responses

Request samples

Content type
application/json

inspection

{
  • "slug": "inspection",
  • "execution_type": "simple",
  • "natural_id_key": "INS",
  • "name": {
    },
  • "attributes": [ ],
  • "lock_version": 0
}

Response samples

Content type
application/json

inspection

{
  • "id": "21d3f004-0000-4000-8000-000000000001",
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "is_extendable": false,
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "attributes": [
    ],
  • "resource_type": "task",
  • "is_readonly": false,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

Delete an unused Task definition

Delete a tenant definition only when no Task or persisted configuration dependency uses it. Completed Tasks also block deletion. System definitions are protected.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Concrete Task definition UUID or slug

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update Task definition metadata

Merge localized names, rename a tenant definition or change its optional natural_id_key prefix. Omitted prefix is preserved; null clears it. Renaming is blocked while used; labels and prefixes remain editable. System definitions allow prefix-only updates. Null slug or root name is invalid.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Concrete Task definition UUID or slug

Request Body schema: application/merge-patch+json
required
slug
string <= 63 characters

New slug; null is rejected. UUID stays stable. Rename is blocked once the definition is used.

object

Merge by language and noun form. A null language removes its translation. Empty maps preserve values. At least one localized name must remain; root null is rejected.

natural_id_key
string or null <= 16 characters ^[A-Z][A-Z0-9]{0,15}$

Workspace-unique presentation prefix. Omission preserves it; null removes it. May change on system or in-use definitions without renumbering Tasks.

lock_version
integer or null <int64> >= 0

Optional version precondition; stale versions return 409. Omitted or null skips the client check.

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon catalog key. Omission preserves it; null restores the default icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Icon background palette color. Omission preserves it; null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Ordered popup field selection. Omission preserves it; null clears it to an empty list; an array replaces it. Lists and structured JSON fields are unsupported.

Responses

Request samples

Content type
application/merge-patch+json

inspection

{
  • "name": {
    },
  • "lock_version": 0
}

Response samples

Content type
application/json

inspection

{
  • "id": "21d3f004-0000-4000-8000-000000000001",
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "is_extendable": false,
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "attributes": [
    ],
  • "resource_type": "task",
  • "is_readonly": false,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

List Task definitions

Search slug and localized names before pagination. Fixed order: system Simple, Visit, single-choice question, free-text question; then custom slug and UUID. The Task family root is excluded.

Authorizations:
BearerAuth
query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

search
string [ 1 .. 256 ] characters

Case-insensitive slug or localized-name substring; blank is rejected

header Parameters
If-None-Match
string

Optional ETag for conditional revalidation

Responses

Response samples

Content type
application/json

inspection

{
  • "items": [
    ],
  • "page": {
    }
}

Create a Task definition

Create an extension of system Simple or Visit. Workflow question bases and custom definitions cannot be extended. Native fields cannot be overridden.

Authorizations:
BearerAuth
Request Body schema: application/json
required
slug
required
string <= 63 characters ^[a-z][a-z0-9_]*$

Tenant Task definition slug; managed prefixes and reserved names are forbidden.

required
object

Localized singular/plural names.

execution_type
required
string
Enum: "simple" "workflow_single_choice_question" "workflow_free_text_question" "visit"

Immutable system execution type. Only simple and visit can be extended.

natural_id_key
string or null <= 16 characters ^[A-Z][A-Z0-9]{0,15}$

Optional workspace-unique presentation prefix. All Tasks share one numeric sequence regardless of definition. Omitted or null means no prefix.

Array of any (AttributeInput) <= 20 items

Authored custom fields only. Native fields cannot be overridden; Task targets and reverse fields are not supported.

icon
string or null <= 64 characters ^[a-z0-9]+(-[a-z0-9]+)*$

Icon key from the client icon catalog, for example truck. Clients render a default icon for unknown keys. Omission means no icon.

color
string or null
Enum: "gray" "red" "orange" "amber" "green" "teal" "blue" "indigo" "violet" "pink" null

Palette color of the definition icon. Omission or null means transparent.

map_marker_fields
Array of strings or null <= 100 items

Attribute slugs shown, in order, under the record name and the clicked location in a map popup, for example ["plate_number", "color"]. Each attribute at most once; list-valued attributes (tags, skills, multi-value relationships) are not allowed. Renaming or deleting an attribute updates the list. Omission means none.

Responses

Request samples

Content type
application/json

inspection

{
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "attributes": [ ]
}

Response samples

Content type
application/json

inspection

{
  • "id": "21d3f004-0000-4000-8000-000000000001",
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "is_extendable": false,
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 0,
  • "attributes": [
    ],
  • "resource_type": "task",
  • "is_readonly": false,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

Add a Task attribute

Add a custom attribute. While the definition is used, only optional fields without new uniqueness/indexing obligations are allowed. Defaults apply to future creation only. Returns the updated definition.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Concrete Task definition UUID or slug

Request Body schema: application/json
required
id
string <uuid>

Existing attribute id (omit on create; send to update/rename)

slug
required
string <= 200 characters ^[a-z][a-z0-9_]*$

Attribute slug; self, this and platform record fields are reserved.

type
required
string

Attribute type selecting this configuration.

object

Attribute label per language tag, e.g. {"en": "Purchase price"}

description
string

Optional attribute description

object (TextAttributeConfigInput)

Configuration for text attributes.

lock_version
integer <int64>

Optimistic-locking version: validated against the stored version when provided (409 on mismatch); omitting it skips the concurrency check

Responses

Request samples

Content type
application/json

inspection

{
  • "slug": "notes",
  • "type": "text",
  • "name": {
    }
}

Response samples

Content type
application/json

inspection

{
  • "id": "21d3f004-0000-4000-8000-000000000001",
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "is_extendable": false,
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 1,
  • "attributes": [
    ],
  • "resource_type": "task",
  • "is_readonly": false,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

Delete a Task attribute

Remove an authored attribute and its storage only when the definition is unused. Returns the complete updated definition. System definitions are protected.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Concrete Task definition UUID or slug

attribute_ref
required
string

Authored attribute UUID or slug

Responses

Response samples

Content type
application/json

inspection

{
  • "id": "21d3f004-0000-4000-8000-000000000001",
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "is_extendable": false,
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 2,
  • "attributes": [
    ],
  • "resource_type": "task",
  • "is_readonly": false,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

Update a Task attribute

Merge an authored attribute by UUID or slug. Omitted fields stay unchanged; choice arrays replace their set. While used, only labels, descriptions and presentation order may change. Type, uniqueness, cardinality and target changes are unsupported even when unused.

Authorizations:
BearerAuth
path Parameters
definition_ref
required
string

Concrete Task definition UUID or slug

attribute_ref
required
string

Authored attribute UUID or slug

Request Body schema: application/merge-patch+json
required
id
string or null <uuid>

Optional identity assertion; must match the routed attribute.

type
string or null
Enum: "text" "license_plate" "vin" "number" "date" "date_time" "boolean" "select" "state" "capacity" "measure" "currency" "rating" "email" "phone" "tags" "required_skills" "provided_skills" "relationship" "location" "raw_json" "rich_text" "full_name" "links" null

Optional type assertion; cannot change the stored type.

slug
string <= 200 characters ^[a-z][a-z0-9_]*$

New slug. Omission preserves it; null cannot clear it.

object

Merge localized labels. Null at a language key removes that translation.

description
string or null

Null clears the description; blank text is rejected.

object or null

Merge type-specific configuration keys with the stored configuration. Null clears an optional setting; null config resets optional configuration. Required settings, immutable uniqueness, unknown keys and keys belonging to another type are validated after merging.

Array of objects (SelectOptionInput)

Select only: replaces choices; [] clears them. Existing choice IDs preserve stored values.

Array of objects (StateInput)

State only: replaces states; [] clears them. Existing state IDs preserve stored values.

lock_version
integer or null <int64> >= 0

Optional definition version precondition.

Responses

Request samples

Content type
application/merge-patch+json

inspection

{
  • "name": {
    },
  • "lock_version": 1
}

Response samples

Content type
application/json

inspection

{
  • "id": "21d3f004-0000-4000-8000-000000000001",
  • "slug": "inspection",
  • "natural_id_key": "INS",
  • "execution_type": "simple",
  • "name": {
    },
  • "is_extendable": false,
  • "managed_by": "tenant",
  • "schema_policy": "editable",
  • "created_at": "2023-02-14T10:00:00Z",
  • "updated_at": "2023-02-14T10:00:00Z",
  • "lock_version": 2,
  • "attributes": [
    ],
  • "resource_type": "task",
  • "is_readonly": false,
  • "is_relationship_target": false,
  • "map_marker_fields": [ ]
}

MCP Server

Manage MCP server settings for the tenant. Controls whether MCP is enabled and which operations are allowed.

Get MCP server settings

Returns the current MCP server operating mode and connection URL for this tenant.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

ReadOnlyMcpSettings

{}

Update MCP server settings

Partially updates the MCP server settings. Omit a field to leave it unchanged. Set mode to OFF to disable MCP entirely, READ_ONLY to allow read operations only, or READ_WRITE to allow all operations.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
mode
string
Enum: "OFF" "READ_ONLY" "READ_WRITE"

New operating mode. Omit to leave unchanged; explicit null is rejected (422).

Responses

Request samples

Content type
application/merge-patch+json

EnableReadOnlyMcp

{
  • "mode": "READ_ONLY"
}

Response samples

Content type
application/json

UpdatedReadOnlyMcpSettings

{}

Workflow runs

Customer workflow execution history. Requires workflows:manage, including access to captured inputs.

List runs for a workflow

Requires workflows:manage. Lists stored runs for one workflow without decrypting inputs. Includes retained runs after workflow deletion.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Owning workflow UUID, including retained deleted workflows

query Parameters
status
string
Enum: "queued" "running" "succeeded" "failed" "timed_out" "cancelled" "terminated"

Exact stored run status; omitted includes all statuses

created_from
string <date-time>

Inclusive lower bound on created_at, RFC 3339 with explicit offset

created_to
string <date-time>

Exclusive upper bound on created_at, RFC 3339 with explicit offset; must be later than created_from

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

sort
string
Default: "created_at:desc"
Enum: "created_at" "created_at:asc" "created_at:desc" "id" "id:asc" "id:desc"

One field[:direction] criterion: created_at or id, asc/desc. Omitted direction means asc; default created_at:desc with stable id tie-breaker.

object_id
string <uuid>

Exact triggering object UUID captured at admission. Combined with other filters before count and pagination; does not decrypt inputs or require the object to still exist.

record_id
string <uuid>

Exact triggering record UUID captured at admission. Combined with object_id when supplied; includes retained runs after record deletion and does not decrypt inputs.

version_id
string <uuid>

Exact pinned workflow version UUID belonging to this workflow

Responses

Response samples

Content type
application/json

QueuedRuns

{
  • "items": [
    ],
  • "page": {
    }
}

Run a published workflow for a record

Admits an enabled manual_record publication for an accessible current record. Requires workflows:manage and objects:records:read; Script/Agent workflows also require workflows:code:execute. The reviewed version_id must still be current. Execution is asynchronous through the ordinary durable outbox. Repeating the same request_id, publication, record and actor returns the same run without new effects, even if the workflow was subsequently edited or disabled. Use a new request_id only for a deliberate new run, which may repeat effects.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID in the current tenant

Request Body schema: application/json
required
request_id
required
string <uuid>

Client-generated UUID for one intended run. Reuse on retry; generate another for a deliberate new run.

version_id
required
string <uuid>

Exact reviewed workflow publication UUID; must be the current enabled manual-record publication for a new request.

record_id
required
string <uuid>

Accessible current record UUID belonging to the publication's trigger object.

object

Values for every declared start input in the reviewed publication. Exact names and scalar types, at most 16 and 16 KiB. Omission is an empty object; null and undeclared names are rejected. Preserve these values across retries.

Responses

Request samples

Content type
application/json

ReviewedRecordRun

{
  • "request_id": "00000000-0000-4000-8000-000000000901",
  • "version_id": "00000000-0000-4000-8000-000000000902",
  • "record_id": "00000000-0000-4000-8000-000000000903"
}

Response samples

Content type
application/json

AdmittedRun

{
  • "id": "10000000-1111-2222-3333-000000000001",
  • "workflow_id": "20000000-1111-2222-3333-000000000001",
  • "version_id": "30000000-1111-2222-3333-000000000001",
  • "trigger_id": "40000000-1111-2222-3333-000000000001",
  • "source_event_id": "50000000-1111-2222-3333-000000000001",
  • "status": "queued",
  • "created_at": "2026-09-05T10:00:00Z",
  • "trigger_input": {
    },
  • "steps": [
    ]
}

Cancel a workflow run

Requires workflows:manage. Atomically records cancellation and prevents new workflow effects, closes pending question Tasks, then delivers cancellation asynchronously to the exact execution. Previously committed effects remain. Repeating a pending request returns 202 without creating another request; an already observed terminal run returns 200 unchanged. Inspect cancellation_requested_at and status: a concurrent completion may win. No request body is required.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Owning workflow UUID, including retained deleted workflows

run_id
required
string <uuid>

Tourfold run UUID in this tenant, captured at admission

Responses

Response samples

Content type
application/json

AlreadyCompleted

{
  • "id": "10000000-1111-2222-3333-000000000001",
  • "workflow_id": "20000000-1111-2222-3333-000000000001",
  • "version_id": "30000000-1111-2222-3333-000000000001",
  • "trigger_id": "40000000-1111-2222-3333-000000000001",
  • "source_event_id": "50000000-1111-2222-3333-000000000001",
  • "status": "succeeded",
  • "created_at": "2026-09-05T10:00:00Z",
  • "completed_at": "2026-09-05T10:00:02Z",
  • "trigger_input": {
    },
  • "steps": [
    ]
}

Get a workflow run

Requires workflows:manage. Returns immutable trigger input, ordered logical steps, committed Task and record links, sanitized errors and confirmed usage. include=version expands the pinned publication one level, including after workflow deletion. Captured data uses workflow authority; ordinary Task/record links retain their own access checks.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Owning workflow UUID, including retained deleted workflows

run_id
required
string <uuid>

Tourfold run UUID in this tenant, captured at admission

query Parameters
include
Array of strings <= 1 items unique
Items Value: "version"

One-level inline expansion; only version is supported. Repeat include for multiple values; CSV is unsupported.

Responses

Response samples

Content type
application/json

QueuedRun

{
  • "id": "10000000-1111-2222-3333-000000000001",
  • "workflow_id": "20000000-1111-2222-3333-000000000001",
  • "version_id": "30000000-1111-2222-3333-000000000001",
  • "trigger_id": "40000000-1111-2222-3333-000000000001",
  • "source_event_id": "50000000-1111-2222-3333-000000000001",
  • "status": "queued",
  • "created_at": "2026-09-05T10:00:00Z",
  • "trigger_input": {
    },
  • "steps": [
    ]
}

List steps for a workflow run

Requires workflows:manage. Returns all ordered logical executions in the bounded graph, including pinned inputs, committed outcomes, sanitized errors and usage. Retained after workflow deletion.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Owning workflow UUID, including retained deleted workflows

run_id
required
string <uuid>

Run UUID belonging to this workflow

Responses

Response samples

Content type
application/json

RunSteps

{
  • "items": [
    ]
}

Get a workflow run step

Requires workflows:manage. Resolves the logical execution identity within the pinned run before loading retained content. node_id identifies the authored graph node. Includes committed results independently of the paginated event collection.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Owning workflow UUID, including retained deleted workflows

run_id
required
string <uuid>

Run UUID belonging to this workflow

step_execution_id
required
string <uuid>

Logical step execution UUID from run inspection; distinct from node_id

Responses

Response samples

Content type
application/json

PendingStep

{
  • "id": "90000000-1111-2222-3333-000000000001",
  • "node_id": "80000000-1111-2222-3333-000000000001",
  • "status": "pending",
  • "action_type": "end",
  • "interactions": [ ]
}

List visible workflow step events

Requires workflows:manage. Returns bounded customer Agent messages, permitted tool proposals, native web activity and committed READ outcomes in stable execution order. Verifies every parent before decrypting only the requested page. Non-Agent steps currently return an empty list. Retained deleted-workflow runs remain readable. Partial events explicitly mark pending/malformed/missing content; expired events omit all conversational content and links. Private instructions, internal reasoning, provider identifiers and raw envelopes are never returned. Does not contact external providers. Usage and accepted final output remain available in step inspection independently of event retention.

Authorizations:
BearerAuth
path Parameters
workflow_id
required
string <uuid>

Workflow UUID owning the retained run

run_id
required
string <uuid>

Run UUID belonging to this workflow

step_execution_id
required
string <uuid>

Opaque step execution UUID belonging to this run; distinct from node_id

query Parameters
page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Events per page

Responses

Response samples

Content type
application/json

RetainedWebActivity

{
  • "items": [
    ],
  • "page": {
    }
}

List workflow runs

Requires workflows:manage. Reads metadata without decrypting inputs. Includes retained runs of deleted workflows.

Authorizations:
BearerAuth
query Parameters
workflow_id
string <uuid>

Exact workflow UUID; omitted includes all workflows

status
string
Enum: "queued" "running" "succeeded" "failed" "timed_out" "cancelled" "terminated"

Exact stored run status; omitted includes all statuses

created_from
string <date-time>

Inclusive lower bound on created_at, RFC 3339 with explicit offset

created_to
string <date-time>

Exclusive upper bound on created_at, RFC 3339 with explicit offset; must be later than created_from

page
integer <int32> >= 0
Default: 0

Zero-based page

size
integer <int32> [ 1 .. 100 ]
Default: 20

Items per page

sort
string
Default: "created_at:desc"
Enum: "created_at" "created_at:asc" "created_at:desc" "id" "id:asc" "id:desc"

One field[:direction] criterion: created_at or id, asc/desc. Omitted direction means asc; default created_at:desc with stable id tie-breaker.

object_id
string <uuid>

Exact triggering object UUID captured at admission. Combined with other filters before count and pagination; does not decrypt inputs or require the object to still exist.

record_id
string <uuid>

Exact triggering record UUID captured at admission. Combined with object_id when supplied; includes retained runs after record deletion and does not decrypt inputs.

version_id
string <uuid>

Exact pinned workflow version UUID; when workflow_id is supplied the version must belong to it

Responses

Response samples

Content type
application/json

QueuedRuns

{
  • "items": [
    ],
  • "page": {
    }
}

vehicle-provider-connection-phone-fix

Phone-fix predictions a provider computes for a reported breakdown symptom, from the data it holds for the vehicle.

List a provider connection's phone-fix predictions

Newest first, then by id; case-reported and operator-asked alike. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

query Parameters
page
integer <int32> >= 0
Default: 0
size
integer <int32> [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json

example

{
  • "items": [
    ],
  • "page": {
    }
}

Ask how likely a breakdown is to be fixed over the phone

Queues the prediction and answers 202 with it; the worker asks the provider, which computes it from the data it already holds, and the prediction is read at Location. Nothing is read from the vehicle and nothing is billed. Repeating a request_id with the same symptom returns the same prediction in its current state. Needs vehicles:read and connected-vehicles:data-operations:write, and the connected-vehicles entitlement.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

Request Body schema: application/json
required
request_id
required
string <uuid>

Your key for this request. Repeating it with the same symptom returns the same prediction; with another symptom it conflicts.

symptom
required
string (VehiclePhoneFixSymptom)
Enum: "accelerator_throttle_issue" "accident_damage_theft" "adblue_fault_warning" "adblue_refill_message" "airbag_warning" "alternator_belt" "alternator_issue" "amber_warning_light" "battery_assistance_needed" "battery_flat" "battery_warning_light" "bodywork_issue" "bonnet_boot_door_issue" "brake_pad_wear" "brake_system" "central_locking" "climate_control_issue" "coolant_level_warning" "cooling_fan_issue" "cooling_system" "cv_joint_issue" "dashboard_info_message" "dashboard_warning_light" "door_jammed" "dpf_warning" "electrical_system_reset" "electronic_systems" "engine_cutting_out" "engine_mechanical" "engine_misfire_running_rough" "engine_mount" "engine_noise" "exhaust_smoke" "fluid_leak" "fluid_loss_warning" "fuel_cap_jammed" "fuel_issue" "fuel_leak_smell" "fuel_starvation" "fuel_system" "fuse_issue" "glow_plug_warning" "hybrid_warning_light" "ignition_key_stuck" "ignition_key_wont_turn" "indicator_hazard_lights" "information_request" "key_issue" "key_lost_stolen" "keyless_entry_issue" "loss_of_power" "no_issue_specified" "noise_from_vehicle" "oil_leak_loss" "oil_level_warning" "oil_pressure_warning" "oil_sump_issue" "other_issue" "overheating" "puncture_issue" "recovery_diagnosis_needed" "red_warning_light" "running_rough" "seat_adjustment" "security_system" "steering_locked" "steering_power_steering" "suspension_vibration" "technical_advice_request" "transmission" "turbo_hose_issue" "tyre_pressure_warning" "vehicle_stuck" "vehicle_stuck_stranded" "warning_light_other" "wheel_noise" "wheel_tyre_issue" "windows_wipers" "wont_start"

The symptom the driver reported, in the provider's vocabulary.

Responses

Request samples

Content type
application/json

wont_start

{
  • "request_id": "6a2c1d4e-9f0b-4c3a-8e7d-5b6a7c8d9e0f",
  • "symptom": "wont_start"
}

Response samples

Content type
application/json
Example

queued

{
  • "id": "00000000-0000-4000-8000-000000000071",
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "symptom": "wont_start",
  • "status": "queued",
  • "requested_at": "2023-02-14T10:00:00Z",
  • "attempts": 0
}

Read a phone-fix prediction

Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

prediction_id
required
string <uuid>

UUID of the prediction

Responses

Response samples

Content type
application/json

answered

{
  • "id": "00000000-0000-4000-8000-000000000071",
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "symptom": "wont_start",
  • "status": "succeeded",
  • "requested_at": "2023-02-14T10:00:00Z",
  • "started_at": "2023-02-14T10:00:03Z",
  • "finished_at": "2023-02-14T10:00:04Z",
  • "attempts": 1,
  • "probability": 0.019,
  • "baseline_probability": 0.018,
  • "provider_vehicle_id": "7f3a",
  • "reporting_case": {
    }
}

Read the provider's answer behind a prediction

The provider's body and the HTTP exchanges, credentials redacted. Needs vehicles:read and connected-vehicles:raw-data:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

prediction_id
required
string <uuid>

UUID of the prediction

Responses

Response samples

Content type
application/json

answered

{}

Document Management

Document management API.

List a folder's access-control entries

Returns the entries stored directly on the folder (one per principal: everyone / role / user), for rendering the permissions editor. For a top-level folder with no entries of its own, the tenant-wide default matrix it effectively resolves to is returned instead, flagged via from_tenant_default. An empty list on a non-root folder means it inherits its parent. Requires the documents:read grant to reach the feature and, per folder, either the documents:edit_permissions grant or ownership โ€” otherwise 403.

Authorizations:
BearerAuth
path Parameters
folder_id
required
string <uuid>

UUID of the folder.

Responses

Response samples

Content type
application/json

EquipmentManualPermissions

{
  • "folder_id": "00000000-0000-4000-8000-000000007001",
  • "entries": [
    ],
  • "inherited": false
}

Update a folder's access-control entries

Stores the supplied entries as the folder's complete set (a replace, not a merge); an empty list clears them so the folder inherits. everyone may coexist with role/user entries. Requires the documents:read grant plus, per folder, the documents:edit_permissions grant or ownership. Returns the saved entries.

Authorizations:
BearerAuth
path Parameters
folder_id
required
string <uuid>

UUID of the folder.

Request Body schema: application/json
required
required
Array of objects (PermissionEntryInput)

The complete list of entries the folder should have after this call.

Array
principal_type
required
string
Enum: "everyone" "role" "user"
role_name
string

Required when principal_type is role.

user_id
string <uuid>

Required when principal_type is user.

level
required
string
Enum: "read" "write"

Access level to grant.

Responses

Request samples

Content type
application/json
Example

ReplaceEquipmentManualPermissions

{
  • "entries": [
    ]
}

Response samples

Content type
application/json

ReplacedEquipmentManualPermissions

{
  • "folder_id": "00000000-0000-4000-8000-000000007001",
  • "entries": [
    ],
  • "inherited": false
}

List a document's own access-control entries

Returns the entries stored directly on the document (one per principal: everyone / role / user), for rendering the permissions editor. An empty list means the document has no override and inherits its folder. Requires the documents:read grant to reach the feature and, per document, permission-management rights (the document's creator, the owning folder's manager, or the documents:edit_permissions grant) โ€” otherwise 403.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/json

ServiceManualPermissions

{
  • "document_id": "00000000-0000-4000-8000-000000007101",
  • "entries": [
    ],
  • "inherited": false
}

Update a document's own access-control entries

Stores the supplied entries as the document's complete override set (a replace, not a merge); an empty list clears the override so the document inherits its folder again. everyone may coexist with role/user entries. Requires the documents:read grant plus, per document, permission-management rights (the document's creator, the owning folder's manager, or the documents:edit_permissions grant). Returns the saved entries.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Request Body schema: application/json
required
required
Array of objects (PermissionEntryInput)

The complete list of entries the document should have after this call.

Array
principal_type
required
string
Enum: "everyone" "role" "user"
role_name
string

Required when principal_type is role.

user_id
string <uuid>

Required when principal_type is user.

level
required
string
Enum: "read" "write"

Access level to grant.

Responses

Request samples

Content type
application/json
Example

ReplaceServiceManualPermissions

{
  • "entries": [
    ]
}

Response samples

Content type
application/json

ReplacedServiceManualPermissions

{
  • "document_id": "00000000-0000-4000-8000-000000007101",
  • "entries": [
    ],
  • "inherited": false
}

List folders (paginated)

Returns folders that are direct children of parent_id (or root folders when parent_id is omitted), paginated in ascending name order. Default page size is 20, capped at 100. Folders of kind = managed_branch whose namespace is owned by a registered managed-folder provider are auto-expanded: the response surfaces one folder per managed subject at this depth, lazy-creating any missing rows. The provider's order is authoritative for managed pages. Requires the documents:read grant.

Authorizations:
BearerAuth
query Parameters
parent_id
string <uuid>

Parent folder id; omit for root listing.

page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

AlpineRootFolders

{
  • "items": [
    ],
  • "page": {
    }
}

Create a folder

Creates a folder under the given parent (or at the root if no parent is supplied). Requires the documents:create grant.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string

Display name of the folder. Validated server-side: NFC-normalized, max 255 codepoints, no path separators / control chars / Windows-reserved characters, not a reserved name.

parent_id
string <uuid>

Parent folder id. Omit for a top-level folder.

Responses

Request samples

Content type
application/json

CreateEquipmentManualsFolder

{
  • "name": "Equipment manuals"
}

Response samples

Content type
application/json

CreatedEquipmentManualsFolder

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "lock_version": 0,
  • "name": "Equipment manuals",
  • "display_name": "Equipment manuals",
  • "kind": "user",
  • "created_at": "2026-08-20T08:15:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "access_level": "manage",
  • "tags": [
    ]
}

Star a folder for the calling user

Idempotent: re-starring a folder is a no-op and returns the same detail response with starred=true. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
folder_id
required
string <uuid>

UUID of the folder.

Responses

Response samples

Content type
application/json

StarredEquipmentManualsFolder

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "lock_version": 0,
  • "name": "Equipment manuals",
  • "display_name": "Equipment manuals",
  • "kind": "user",
  • "created_at": "2026-08-20T08:15:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "starred": true,
  • "access_level": "manage",
  • "tags": [
    ]
}

Unstar a folder for the calling user

Idempotent: un-starring a folder that was not starred is a no-op. Returns the folder detail with starred=false. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
folder_id
required
string <uuid>

UUID of the folder.

Responses

Response samples

Content type
application/json

UnstarredEquipmentManualsFolder

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "lock_version": 0,
  • "name": "Equipment manuals",
  • "display_name": "Equipment manuals",
  • "kind": "user",
  • "created_at": "2026-08-20T08:15:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "starred": false,
  • "access_level": "manage",
  • "tags": [
    ]
}

Submit a document version for AI extraction

Asynchronously extracts structured fields from the version. The call returns immediately with a document-management extraction id. Clients should listen for events.documents SSE lifecycle events and may poll GET /documents/extractions/{extraction_id} as a fallback until the status reaches a terminal state. Each call appends a new extraction (re-analysis is supported by submitting again). Terminal payloads are copied into document-management before the analyzer job is acked. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

version_id
required
string <uuid>

UUID of the document version.

Responses

Response samples

Content type
application/json

Rtu17AnalysisAccepted

{
  • "extraction_id": "00000000-0000-4000-8000-000000008005",
  • "status": "pending"
}

Start a new version upload (replace) on an existing document

Creates a new draft [DocumentVersion] with version_number = max + 1, returns a presigned upload form. The current version pointer does NOT change until POST /documents/{document_id}/finalize is called. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Request Body schema: application/json
required
mime_type
required
string non-empty

MIME type of the file being uploaded. Must equal the document's current MIME type โ€” uploading a different content type creates a different document, not a new version. Mismatches are rejected with document-management/version-mime-mismatch.

original_file_name
string

Filename of the file being uploaded (e.g. Invoice-2026-Q2-revised.pdf). Stored on the version row so the UI can list uploads with their actual filenames. Falls back to the document's name when omitted.

change_note
string

Optional free-form note describing what's new in this version. Stored on the version row.

Responses

Request samples

Content type
application/json

UploadRtu17ManualRevision

{
  • "mime_type": "application/pdf",
  • "original_file_name": "RTU-17-service-manual-rev-2.pdf",
  • "change_note": "Added the revised filter replacement schedule."
}

Response samples

Content type
application/json

Rtu17ManualRevisionUploadIntent

{
  • "document_id": "00000000-0000-4000-8000-000000008002",
  • "version_id": "00000000-0000-4000-8000-000000008004",
  • "upload": {
    }
}

Star a document for the calling user

Idempotent: re-starring a document is a no-op and returns the same detail response with starred=true. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/json

StarredRtu17ServiceManual

{
  • "id": "00000000-0000-4000-8000-000000008002",
  • "lock_version": 1,
  • "folder_id": "00000000-0000-4000-8000-000000008001",
  • "name": "RTU-17 service manual.pdf",
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "current_version_id": "00000000-0000-4000-8000-000000008004",
  • "size": 248320,
  • "mime_type": "application/pdf",
  • "created_at": "2026-08-20T08:30:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "starred": true,
  • "preview_available": true,
  • "access_level": "manage",
  • "tags": [
    ]
}

Unstar a document for the calling user

Idempotent: un-starring a document that was not starred is a no-op. Returns the document detail with starred=false. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/json

UnstarredRtu17ServiceManual

{
  • "id": "00000000-0000-4000-8000-000000008002",
  • "lock_version": 1,
  • "folder_id": "00000000-0000-4000-8000-000000008001",
  • "name": "RTU-17 service manual.pdf",
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "current_version_id": "00000000-0000-4000-8000-000000008004",
  • "size": 248320,
  • "mime_type": "application/pdf",
  • "created_at": "2026-08-20T08:30:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "starred": false,
  • "preview_available": true,
  • "access_level": "manage",
  • "tags": [
    ]
}

Soft-delete a document (move to Trash)

Soft-deletes the document โ€” the row is moved to the user's Trash and can be restored later. The captured original_path text is recorded so the restore flow can put the document back where it came from. Idempotent. Hard-delete (permanent removal) is DELETE /documents/{document_id} and is only allowed on rows that have already been soft-deleted. Requires the documents:delete grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/json

TrashedRtu17ServiceManual

{
  • "id": "00000000-0000-4000-8000-000000008002",
  • "lock_version": 2,
  • "name": "RTU-17 service manual.pdf",
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "current_version_id": "00000000-0000-4000-8000-000000008004",
  • "size": 248320,
  • "mime_type": "application/pdf",
  • "created_at": "2026-08-20T08:30:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "soft_deleted_at": "2026-08-20T10:00:00Z",
  • "soft_deleted_by": "00000000-0000-4000-8000-000000000102",
  • "original_path": "/Equipment manuals/",
  • "access_level": "manage",
  • "tags": [
    ]
}

Restore a soft-deleted document

Restores a soft-deleted document from the Trash. The optional request body lets the caller pick the destination and the conflict-resolution strategy. Target folder: when target_folder_id is supplied, the document is restored into that folder (must exist and be user or managed). When omitted, the captured original_path is walked through the live tree and any missing folders are auto-created as user folders so the document reappears at its original location. Conflict resolution (when a live sibling already has the same name): rename uses the supplied new_name for the restored document; new_version appends the restored document's current version as a new version of the existing live sibling and hard-deletes the soft-deleted row (the MIME types must match โ€” otherwise 422 version-mime-mismatch). When conflict_resolution is omitted and a name collision exists, the call rejects with 409 name-taken. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Request Body schema: application/json
target_folder_id
string <uuid>

Folder to restore into. Omit to use the document's captured original_path (auto-creates missing folders).

conflict_resolution
string
Enum: "rename" "new_version"

How to handle a name collision in the target folder. Allowed: rename (uses new_name), new_version (appends as new version of the live sibling). Omit to fail with 409 on collision.

new_name
string

Replacement name. Required when conflict_resolution = "rename"; ignored otherwise.

Responses

Request samples

Content type
application/json
Example

RestoreToEquipmentManuals

{
  • "target_folder_id": "00000000-0000-4000-8000-000000008001"
}

Response samples

Content type
application/json

RestoredRtu17ServiceManual

{
  • "id": "00000000-0000-4000-8000-000000008002",
  • "lock_version": 1,
  • "folder_id": "00000000-0000-4000-8000-000000008001",
  • "name": "RTU-17 service manual.pdf",
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "current_version_id": "00000000-0000-4000-8000-000000008004",
  • "size": 248320,
  • "mime_type": "application/pdf",
  • "created_at": "2026-08-20T08:30:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "access_level": "manage",
  • "tags": [
    ]
}

Finalize a document upload

Completes the latest pending upload for the given document, populates the version's size and MIME type from the filestore rendition, and points current_version_id at it. Idempotent only when called more than once for the same upload โ€” for replacing an existing version, use POST /documents/{document_id}/versions/initiate-upload (slice 3b-ii). Requires the documents:create grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/json

FinalizedRtu17ServiceManual

{
  • "id": "00000000-0000-4000-8000-000000008002",
  • "lock_version": 1,
  • "folder_id": "00000000-0000-4000-8000-000000008001",
  • "name": "RTU-17 service manual.pdf",
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "current_version_id": "00000000-0000-4000-8000-000000008004",
  • "size": 248320,
  • "mime_type": "application/pdf",
  • "created_at": "2026-08-20T08:30:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "access_level": "manage",
  • "tags": [
    ]
}

Start a new document upload

Creates a draft document and a draft version, then returns a presigned upload form. The client POSTs the binary content to the form URL, then calls POST /documents/{document_id}/finalize to complete the upload. Until finalize succeeds, the document's current_version_id is null. Requires the documents:create grant.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string

Display name of the document. Validated server-side: NFC-normalized, max 255 codepoints, no path separators / control chars / Windows-reserved characters, not a reserved name.

folder_id
required
string <uuid>

Folder this document will live in.

mime_type
required
string

MIME type of the file being uploaded.

Responses

Request samples

Content type
application/json

UploadRtu17ServiceManual

{
  • "name": "RTU-17 service manual.pdf",
  • "folder_id": "00000000-0000-4000-8000-000000008001",
  • "mime_type": "application/pdf"
}

Response samples

Content type
application/json

Rtu17ManualUploadIntent

{
  • "document_id": "00000000-0000-4000-8000-000000008002",
  • "version_id": "00000000-0000-4000-8000-000000008003",
  • "upload": {
    }
}

Read tenant-scoped document-management settings

Returns the active document-management settings for the calling tenant. Currently the only setting is auto_hard_delete_after_days, which drives the daily auto-hard-delete cron. Requires the documents:read or the documents:settings:update grant, so a settings editor can read the values they edit.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

AlpineDocumentRetention

{
  • "auto_hard_delete_after_days": 45
}

Update tenant-scoped document-management settings (JSON merge patch)

JSON merge patch semantics: a field present in the body is applied; an absent field is left unchanged. auto_hard_delete_after_days must be an integer in the inclusive range 1..180. Out-of-range values produce 422 with document-management/invalid-retention-days. Requires the documents:settings:update grant.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
auto_hard_delete_after_days
integer <int32> [ 1 .. 180 ]

Number of days after which a soft-deleted document is permanently removed. Must be in the inclusive range 1..180. Field omitted leaves the value unchanged; explicit null is rejected (the field is required and cannot be cleared).

Responses

Request samples

Content type
application/merge-patch+json

SetDocumentRetention

{
  • "auto_hard_delete_after_days": 45
}

Response samples

Content type
application/json

UpdatedAlpineDocumentRetention

{
  • "auto_hard_delete_after_days": 45
}

Get a folder by id

Returns the folder with the given id. Requires the documents:read grant.

Authorizations:
BearerAuth
path Parameters
folder_id
required
string <uuid>

UUID of the folder.

Responses

Response samples

Content type
application/json

EquipmentManualsFolder

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "lock_version": 0,
  • "name": "Equipment manuals",
  • "display_name": "Equipment manuals",
  • "kind": "user",
  • "created_at": "2026-08-20T08:15:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "starred": true,
  • "access_level": "manage",
  • "tags": [
    ]
}

Delete a folder and soft-delete every contained document

Hard-deletes the folder and any subfolders. Every contained document is soft-deleted as part of the same operation โ€” its original_path (the human-readable folder path text it lived at) is captured so the user can restore it individually later from the Trash. Folders themselves are NEVER soft-deleted: they are simply removed from the live tree. Managed (managed/managed_branch) folders cannot be deleted directly. Requires the documents:delete grant.

Authorizations:
BearerAuth
path Parameters
folder_id
required
string <uuid>

UUID of the folder.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Rename and/or move a folder (JSON merge patch)

JSON merge patch semantics: a field present in the body is applied; an absent field is left unchanged. To move a folder under a new parent, send parent_id as a UUID. To move it to the root, send parent_id: null explicitly. Cycles (moving into self or a descendant) are rejected; descendant paths are rebuilt in the same transaction. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
folder_id
required
string <uuid>

UUID of the folder.

Request Body schema: application/merge-patch+json
required
lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check

name
string

New folder name. Validation rules: trimmed, NFC-normalized, 1..255 codepoints, no slashes/backslashes/control characters, not a Windows reserved name. Omitted leaves the value unchanged; explicit null is rejected (422) โ€” name is required and cannot be cleared.

parent_id
string or null <uuid>

New parent folder id, or null to move to root. Omit to leave the parent unchanged. Cannot move into the folder itself or any of its descendants. Cannot move a managed folder.

tag_ids
Array of strings or null <uuid> unique [ items <uuid > ]

Replacement set of tag ids. Field omitted leaves tags unchanged; [] or null clears all tags; a non-empty array replaces the current set (server diffs against existing associations). All ids must reference existing tags. Rejected on managed folders.

Responses

Request samples

Content type
application/merge-patch+json
Example

RenameAndTagFolder

{
  • "lock_version": 0,
  • "name": "Equipment manuals",
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json

UpdatedEquipmentManualsFolder

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "lock_version": 0,
  • "name": "Equipment manuals",
  • "display_name": "Equipment manuals",
  • "kind": "user",
  • "created_at": "2026-08-20T08:15:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "access_level": "manage",
  • "tags": [
    ]
}

Get a document by id

Returns the document with the given id (soft-deleted documents are returned with soft_deleted_at set). Requires the documents:read grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/json

Rtu17ServiceManualDetail

{
  • "id": "00000000-0000-4000-8000-000000008002",
  • "lock_version": 1,
  • "folder_id": "00000000-0000-4000-8000-000000008001",
  • "name": "RTU-17 service manual.pdf",
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "current_version_id": "00000000-0000-4000-8000-000000008004",
  • "size": 248320,
  • "mime_type": "application/pdf",
  • "created_at": "2026-08-20T08:30:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "starred": true,
  • "preview_available": true,
  • "access_level": "manage",
  • "tags": [
    ]
}

Permanently delete a soft-deleted document (hard-delete)

Hard-deletes a soft-deleted document and all its versions. Cannot be called on a live row โ€” soft-delete it first via POST /documents/{document_id}/soft-delete. Filestore blob cleanup is wired up in a later slice. Requires the documents:delete grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Rename, move, and/or update the description of a document (JSON merge patch)

JSON merge patch semantics: a field present in the body is applied; an absent field is left unchanged. Send description: null explicitly to clear the description. Send folder_id to move the document into another folder atomically โ€” the target must be live and have kind = user or kind = managed (managed leaf); managed_branch is rejected. Name collision is checked against the target folder's siblings when a move is requested. Requires the documents:update grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Request Body schema: application/merge-patch+json
required
lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check

name
string

New document name. Validation rules match folder names (1..255 codepoints, no slashes/backslashes/control characters, not a Windows reserved name). Omitted leaves the value unchanged; explicit null is rejected (422) โ€” name is required and cannot be cleared.

description
string or null

Free-form description. Send null to clear; omit to leave unchanged.

folder_id
string <uuid>

Move the document into the folder with this id. Target must be live and have kind = user or kind = managed (managed leaf). managed_branch targets are rejected. Targeting a managed leaf that has not been materialised yet lazy-creates it. Omit to leave the folder unchanged; explicit null is rejected (422).

tag_ids
Array of strings or null <uuid> unique [ items <uuid > ]

Replacement set of tag ids. Field omitted leaves tags unchanged; [] or null clears all tags; a non-empty array replaces the current set (server diffs against existing associations). All ids must reference existing tags.

Responses

Request samples

Content type
application/merge-patch+json
Example

DescribeAndTagRtu17Manual

{
  • "lock_version": 0,
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json

UpdatedRtu17ServiceManual

{
  • "id": "00000000-0000-4000-8000-000000008002",
  • "lock_version": 1,
  • "folder_id": "00000000-0000-4000-8000-000000008001",
  • "name": "RTU-17 service manual.pdf",
  • "description": "Manufacturer service manual for rooftop unit RTU-17.",
  • "current_version_id": "00000000-0000-4000-8000-000000008004",
  • "size": 248320,
  • "mime_type": "application/pdf",
  • "created_at": "2026-08-20T08:30:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "access_level": "manage",
  • "tags": [
    ]
}

Read document-management usage snapshot

Returns a lightweight usage snapshot for the calling tenant: live and soft-deleted document counts. Available even when the document-management feature flag is off; used by the gated-tenant upgrade page. Usage and quotas live under the generic usage endpoints. Requires the documents:read grant.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

AlpineDocumentUsage

{
  • "document_count": 24,
  • "soft_deleted_document_count": 2
}

List the calling user's starred folders and documents (paginated)

Returns a single mixed list sorted by starred_at desc, paginated. Each entry's kind field is "folder" or "document"; the corresponding folder or document field is populated. Soft-deleted items are excluded โ€” see GET /soft-deleted for the user's Trash listing. Default page size is 20, capped at 100. Requires the documents:read grant.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

AlpineStarredDocuments

{
  • "items": [
    ],
  • "page": {
    }
}

List the tenant's soft-deleted documents (paginated)

Returns soft-deleted documents (the user's Trash) sorted by soft_deleted_at desc, paginated. Each entry's kind field is always "document" (folders are never soft-deleted in the new model). The corresponding document field is populated and includes the captured original_path text. Default page size is 20, capped at 100. Tenant-wide and gated by the grant only: a soft-deleted document has no live folder (its folder_id is severed on delete), so per-folder ACL filtering cannot apply here. Requires the documents:read grant.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

AlpineDocumentTrash

{
  • "items": [
    ],
  • "page": {
    }
}

Look up a folder by its display path

Walks the tree from the root, matching slash-separated name segments (NFC and case-insensitive). Returns 404 if any segment doesn't match a folder. Requires the documents:read grant.

Authorizations:
BearerAuth
query Parameters
path
required
string

Slash-separated display path, e.g. /Inspection reports/2024.

Responses

Response samples

Content type
application/json

EquipmentManualsFolderByPath

{
  • "id": "00000000-0000-4000-8000-000000008001",
  • "lock_version": 0,
  • "name": "Equipment manuals",
  • "display_name": "Equipment manuals",
  • "kind": "user",
  • "created_at": "2026-08-20T08:15:00Z",
  • "created_by": "00000000-0000-4000-8000-000000000102",
  • "created_by_name": "Jonas Leitner",
  • "starred": true,
  • "access_level": "manage",
  • "tags": [
    ]
}

List documents in a folder (paginated)

Returns documents directly in the given folder (not the subtree), paginated. Soft-deleted documents are never returned here โ€” they live under the dedicated /soft-deleted endpoint. Sortable fields: name, createdAt, updatedAt, size. Default sort is name:asc; default page size is 20, capped at 100. Requires the documents:read grant.

Authorizations:
BearerAuth
query Parameters
folder_id
required
string <uuid>

Folder id.

page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

sort
Array of strings
Example: sort=updated_at:desc

Repeated sorting criteria in field:direction format. Allowed fields: name, created_at, updated_at, size. Default: name:asc.

Responses

Response samples

Content type
application/json

EquipmentManualDocuments

{
  • "items": [
    ],
  • "page": {
    }
}

List all versions of a document

Returns every version, newest first. Pending (not-yet-finalized) versions have finalized_at = null. Requires the documents:read grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

Responses

Response samples

Content type
application/json

Rtu17ManualVersions

{
  • "items": [
    ]
}

List extractions for a document version

Returns up to 50 extractions for the version, newest first. Requires the documents:read grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

version_id
required
string <uuid>

UUID of the document version.

Responses

Response samples

Content type
application/json

Rtu17ExtractionHistory

{
  • "items": [
    ]
}

Get the most recent succeeded extraction for a document version

Convenience endpoint: returns the latest extraction whose status is succeeded. Returns 404 (slug extraction-not-found) when no extraction has succeeded yet for this version. Requires the documents:read grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

version_id
required
string <uuid>

UUID of the document version.

Responses

Response samples

Content type
application/json

LatestRtu17Extraction

{
  • "id": "00000000-0000-4000-8000-000000008005",
  • "document_id": "00000000-0000-4000-8000-000000008002",
  • "version_id": "00000000-0000-4000-8000-000000008004",
  • "status": "succeeded",
  • "created_at": "2026-08-20T09:35:00Z",
  • "started_at": "2026-08-20T09:35:02Z",
  • "finished_at": "2026-08-20T09:35:08Z",
  • "schema": {
    },
  • "schema_inferred": true,
  • "extracted_fields": {
    }
}

Get a document version URL through the released native compatibility route Deprecated

Use GET /api/v2/document-management/documents/{document_id}/versions/{version_id}/download-url. This alias retains identical rendition, download, authorization and expiry behavior for supported native bundles.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

version_id
required
string <uuid>

UUID of the document version.

query Parameters
rendition
string
Default: "original"
Enum: "original" "preview"

Rendition alias to serve.

download
boolean
Default: false

Force attachment download; defaults to safe inline handling.

Responses

Response samples

Content type
application/json

DocumentVersionUrl

Get a presigned download URL for a document version

Returns a short-lived presigned URL the client can GET to download the binary content. The URL is signed by the storage backend and expires after a few minutes. The optional rendition query parameter selects which filestore rendition to serve: original (default, the bytes the user uploaded) or preview (a JPEG inline preview, only available for image/PDF uploads when preview_available is true on the version). Set download=true to sign an attachment response with the stored filename. Omitted/false retains safe inline handling; rendition selection is independent of download intent. Requires the documents:read grant.

Authorizations:
BearerAuth
path Parameters
document_id
required
string <uuid>

UUID of the document.

version_id
required
string <uuid>

UUID of the document version.

query Parameters
rendition
string
Default: "original"
Enum: "original" "preview"

Rendition alias to serve. Defaults to original.

download
boolean
Default: false

Force attachment download; defaults to safe inline handling.

Responses

Response samples

Content type
application/json

Rtu17ManualDownload

List recently uploaded documents

Returns finalized, live documents sorted by their current version's uploaded_at descending. With folder_id the result is scoped to that folder's subtree (folder + descendants); without folder_id the listing is tenant-wide. Requires the documents:read grant.

Authorizations:
BearerAuth
query Parameters
folder_id
string <uuid>

Optional folder scope; when supplied, results are limited to the folder's subtree.

limit
integer [ 1 .. 100 ]
Default: 25

Maximum number of rows to return.

uploaded_after
string <date-time>

Strict RFC 3339 cutoff for the current version's uploaded_at; only documents uploaded after this instant are returned.

Responses

Response samples

Content type
application/json

RecentEquipmentDocuments

{
  • "items": [
    ]
}

Get an extraction by id

Returns the current durable document-management extraction state. Clients use this for an initial load, SSE-triggered refreshes, and polling fallback while an extraction is still running. Requires the documents:read grant.

Authorizations:
BearerAuth
path Parameters
extraction_id
required
string <uuid>

UUID of the document extraction.

Responses

Response samples

Content type
application/json

Rtu17Extraction

{
  • "id": "00000000-0000-4000-8000-000000008005",
  • "document_id": "00000000-0000-4000-8000-000000008002",
  • "version_id": "00000000-0000-4000-8000-000000008004",
  • "status": "succeeded",
  • "created_at": "2026-08-20T09:35:00Z",
  • "started_at": "2026-08-20T09:35:02Z",
  • "finished_at": "2026-08-20T09:35:08Z",
  • "schema": {
    },
  • "schema_inferred": true,
  • "extracted_fields": {
    }
}

vehicle-provider-connection-data

Durable data requests to a provider connection, the observations they stored and the newest value of each signal.

List a provider connection's data requests

Newest first, then by id. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

query Parameters
page
integer <int32> >= 0
Default: 0
size
integer <int32> [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json

example

{
  • "items": [
    ],
  • "page": {
    }
}

Request a Vehicle's data from its provider

Queues durable work and answers 202 with it; the worker then reads the provider and stores what it delivered as observations, and the operation's status is read at Location. refresh first asks the vehicle for fresh data โ€” billed by the provider and possibly waking the vehicle โ€” and is sent at most once. Repeating a request_id with the same content returns the same operation in its current state. Needs vehicles:read and connected-vehicles:data-operations:write, and the connected-vehicles entitlement.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

Request Body schema: application/json
required
request_id
required
string <uuid>

Your key for this request. Repeating it with the same content returns the same operation; with other content it conflicts.

contents
Array of strings non-empty unique
Items Enum: "status" "diagnostics"

Documents to read, each named once. Defaults to the status.

refresh
boolean
Default: false

First ask the vehicle for fresh data. Billed by the provider and it can wake the vehicle; the request then waits before reading again. Only for providers and connections that support it.

Responses

Request samples

Content type
application/json
Example

status

{
  • "request_id": "8d3b6f2e-4a1c-4b7e-9e1f-2c6d8a0b5f14"
}

Response samples

Content type
application/json
Example

queued

{
  • "id": "00000000-0000-4000-8000-000000000051",
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "contents": [
    ],
  • "refresh": false,
  • "status": "queued",
  • "requested_at": "2023-02-14T10:00:00Z",
  • "attempts": 0,
  • "observation_ids": [ ]
}

List what a provider connection delivered

Newest received first, then by id. Reading never contacts the provider. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

query Parameters
page
integer <int32> >= 0
Default: 0
size
integer <int32> [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json

example

{
  • "items": [
    ],
  • "page": {
    }
}

Read one observation

Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

observation_id
required
string <uuid>

UUID of the observation

Responses

Response samples

Content type
application/json

status

{
  • "id": "00000000-0000-4000-8000-000000000061",
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "data_operation_id": "00000000-0000-4000-8000-000000000051",
  • "kind": "status",
  • "received_at": "2023-02-14T10:00:04Z",
  • "observed_at": "2023-02-14T09:58:41Z",
  • "measurements": {
    }
}

Read an observation's raw provider answer

The provider's body verbatim and every exchange, credentials redacted. Needs vehicles:read and connected-vehicles:raw-data:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

observation_id
required
string <uuid>

UUID of the observation

Responses

Response samples

Content type
application/json

status

{}

Read each signal's newest known value

Across the connection's 100 most recent observations, the value the vehicle measured last for each signal, with the observation it came from. Within them, an answer lacking a signal does not hide an earlier value of it; an undated value shows only when no dated one exists. Never contacts the provider. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

Responses

Response samples

Content type
application/json

latest

{
  • "location": {
    },
  • "fault_codes": {
    }
}

Read one data request

Progress, outcome and the observations it stored. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

data_operation_id
required
string <uuid>

UUID of the data request

Responses

Response samples

Content type
application/json
Example

succeeded

{
  • "id": "00000000-0000-4000-8000-000000000051",
  • "connection_id": "00000000-0000-4000-8000-000000000012",
  • "contents": [
    ],
  • "refresh": false,
  • "status": "succeeded",
  • "requested_at": "2023-02-14T10:00:00Z",
  • "started_at": "2023-02-14T10:00:03Z",
  • "finished_at": "2023-02-14T10:00:04Z",
  • "attempts": 1,
  • "observation_ids": [
    ]
}

Read why a data request failed

The provider's answer to the last failed attempt and every exchange, credentials redacted. Needs vehicles:read and connected-vehicles:raw-data:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

data_operation_id
required
string <uuid>

UUID of the data request

Responses

Response samples

Content type
application/json

refused

{}

Service accounts

Integration identities that authenticate with a client id and secret (client_credentials) and receive grants from their roles. Managing them requires the 'service-accounts:manage' grant.

List service accounts

Returns the workspace's service accounts, newest first. Regular users are never listed.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

search
string

Case-insensitive substring match on the service account's name.

Responses

Response samples

Content type
application/json

ServiceAccounts

{
  • "items": [
    ],
  • "page": {
    }
}

Create a service account

Creates the account with the given roles and returns its client secret, exactly once. The integration obtains 5-minute access tokens from token_endpoint with the client_credentials grant, authenticating with client_id and client_secret (HTTP Basic). A lost secret can only be rotated.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Display name, shown as the actor of the account's changes

description
string [ 1 .. 1000 ] characters

Optional description. Omit it to leave it unset; a blank value is rejected.

role_ids
required
Array of strings <uuid> non-empty unique [ items <uuid > ]

Roles whose grants the account receives; at least one

Responses

Request samples

Content type
application/json

CreateErpImport

{
  • "name": "Alpine ERP import",
  • "description": "Nightly order import from the Alpine ERP",
  • "role_ids": [
    ]
}

Response samples

Content type
application/json

CreatedServiceAccount

{
  • "id": "0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "name": "Alpine ERP import",
  • "description": "Nightly order import from the Alpine ERP",
  • "client_id": "tf-sa-0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "roles": [
    ],
  • "grants": [
    ],
  • "created_by_user_id": "aaaaaaaa-1111-1111-1111-aaaaaaaaaaaa",
  • "created_at": "2026-09-30T08:00:00Z",
  • "updated_at": "2026-09-30T08:00:00Z",
  • "lock_version": 0,
  • "status": "ACTIVE",
  • "client_secret": "example_client_secret_not_a_real_secret"
}

Rotate a service account's secret

Replaces the client secret and returns the new one, exactly once. The previous secret stops working at once, and tokens obtained before the rotation stop working within 30 seconds. The operation takes no request body.

Authorizations:
BearerAuth
path Parameters
service_account_id
required
string <uuid>

Service account id

Responses

Response samples

Content type
application/json

RotatedServiceAccountSecret

{
  • "id": "0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "name": "Alpine ERP import",
  • "description": "Nightly order import from the Alpine ERP",
  • "client_id": "tf-sa-0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "status": "ACTIVE",
  • "roles": [
    ],
  • "grants": [
    ],
  • "created_by_user_id": "aaaaaaaa-1111-1111-1111-aaaaaaaaaaaa",
  • "created_at": "2026-09-30T08:00:00Z",
  • "updated_at": "2027-03-01T09:30:00Z",
  • "lock_version": 1,
  • "client_secret": "rotated_example_client_secret_not_a_real_secret"
}

Deactivate a service account

Stops the integration from obtaining tokens; tokens it already holds stop working within 30 seconds. A service account cannot deactivate itself.

Authorizations:
BearerAuth
path Parameters
service_account_id
required
string <uuid>

Service account id

Responses

Response samples

Content type
application/json

DeactivatedServiceAccount

{
  • "id": "0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "name": "Alpine ERP import",
  • "description": "Nightly order import from the Alpine ERP",
  • "client_id": "tf-sa-0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "roles": [
    ],
  • "grants": [
    ],
  • "created_by_user_id": "aaaaaaaa-1111-1111-1111-aaaaaaaaaaaa",
  • "created_at": "2026-09-30T08:00:00Z",
  • "updated_at": "2026-09-30T08:00:00Z",
  • "lock_version": 0,
  • "status": "INACTIVE"
}

Activate a service account

Lets the integration obtain tokens again.

Authorizations:
BearerAuth
path Parameters
service_account_id
required
string <uuid>

Service account id

Responses

Response samples

Content type
application/json

ActivatedServiceAccount

{
  • "id": "0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "name": "Alpine ERP import",
  • "description": "Nightly order import from the Alpine ERP",
  • "client_id": "tf-sa-0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "roles": [
    ],
  • "grants": [
    ],
  • "created_by_user_id": "aaaaaaaa-1111-1111-1111-aaaaaaaaaaaa",
  • "created_at": "2026-09-30T08:00:00Z",
  • "updated_at": "2026-09-30T08:00:00Z",
  • "lock_version": 0,
  • "status": "ACTIVE"
}

Get a service account

Returns the service account with its client id, token endpoint, roles and grants. The client secret is never returned.

Authorizations:
BearerAuth
path Parameters
service_account_id
required
string <uuid>

Service account id

Responses

Response samples

Content type
application/json

ServiceAccount

{
  • "id": "0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "name": "Alpine ERP import",
  • "description": "Nightly order import from the Alpine ERP",
  • "client_id": "tf-sa-0192f7a0-3b1c-7d2e-9f40-5a6b7c8d9e0f",
  • "roles": [
    ],
  • "grants": [
    ],
  • "created_by_user_id": "aaaaaaaa-1111-1111-1111-aaaaaaaaaaaa",
  • "created_at": "2026-09-30T08:00:00Z",
  • "updated_at": "2026-09-30T08:00:00Z",
  • "lock_version": 0,
  • "status": "ACTIVE"
}

Delete a service account

Deletes the account and its client; tokens it already holds stop working within 30 seconds. A service account cannot delete itself.

Authorizations:
BearerAuth
path Parameters
service_account_id
required
string <uuid>

Service account id

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a service account

Partially updates the name, description or roles (JSON Merge Patch). The secret changes only through rotate-secret.

Authorizations:
BearerAuth
path Parameters
service_account_id
required
string <uuid>

Service account id

Request Body schema: application/merge-patch+json
required
name
string [ 1 .. 255 ] characters

Display name. Cannot be cleared.

description
string or null [ 1 .. 1000 ] characters

Description; explicit null clears it, a blank value is rejected.

role_ids
Array of strings <uuid> non-empty unique [ items <uuid > ]

Replaces the assigned roles; at least one. Explicit null is rejected.

lock_version
integer or null <int64>

Optimistic locking version; validated when provided (409 on mismatch), omitting it skips the check

Responses

Request samples

Content type
application/merge-patch+json

ClearDescription

{
  • "name": "Alpine ERP order import",
  • "description": null
}

Response samples

Content type
application/json

UpdatedServiceAccount

{}

vehicle-provider-connections

Vehicles served through connected-car provider accounts, and their history.

List provider connections and their history

Fixed ordering: started_at descending, then id ascending. By default only active connections are returned. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
query Parameters
vehicle_id
string <uuid>

Only connections of this Vehicle

lifecycle
string
Default: "current"
Enum: "current" "all"

current (default) or all, including ended connections

page
integer <int32> >= 0
Default: 0
size
integer <int32> [ 1 .. 100 ]
Default: 20

Responses

Response samples

Content type
application/json

example

{
  • "items": [
    ],
  • "page": {
    }
}

Serve a Vehicle's VIN through a provider account

Binds the Vehicle's current VIN, which must be set, to an enabled workspace provider account. Connecting does not contact the provider. Repeating an active connection returns it with 200. The same account serving the VIN on another Vehicle, or this Vehicle with another brand or data source, conflicts. While the connection is active the Vehicle's VIN cannot change. Needs vehicles:update and connected-vehicles:create, and the connected-vehicles entitlement.

Authorizations:
BearerAuth
Request Body schema: application/json
required
vehicle_id
required
string <uuid>
provider_account_id
required
string <uuid>

Enabled workspace provider account that serves the Vehicle.

brand
string [ 0 .. 64 ] characters

Brand as the provider names it, e.g. bmw for DRVN or sandbox for a High Mobility simulator. High Mobility clears a VIN for one brand, so a High Mobility connection requires it. Omit it rather than sending a blank string.

data_source
string [ 0 .. 128 ] characters

DRVN product for this Vehicle, as letters, digits, '.', '_' or '-', including a letter or digit; the account's default applies when omitted. Only DRVN connections have one. A blank string is rejected.

Responses

Request samples

Content type
application/json

drvn

{
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "provider_account_id": "00000000-0000-4000-8000-000000000031",
  • "brand": "bmw",
  • "data_source": "bmw_b2c_reactive_car_data"
}

Response samples

Content type
application/json

active

{
  • "id": "00000000-0000-4000-8000-000000000012",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "provider_account_id": "00000000-0000-4000-8000-000000000031",
  • "provider": "DRVN",
  • "vin": "WBATA610809M97092",
  • "brand": "bmw",
  • "data_source": "bmw_b2c_reactive_car_data",
  • "started_at": "2023-02-14T10:00:00Z",
  • "is_location_source": false,
  • "lock_version": 0
}

End a provider connection

Ends the connection immediately, releases it as location source and queues the revocation of its upstream access; the authorization's revocation_status follows it. History and the Vehicle's last-known position are kept. Repeating end changes nothing. Needs vehicles:update and connected-vehicles:delete.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

Responses

Response samples

Content type
application/json

ended

{
  • "id": "00000000-0000-4000-8000-000000000012",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "provider_account_id": "00000000-0000-4000-8000-000000000031",
  • "provider": "DRVN",
  • "vin": "WBATA610809M97092",
  • "brand": "bmw",
  • "data_source": "bmw_b2c_reactive_car_data",
  • "started_at": "2023-02-14T10:00:00Z",
  • "ended_at": "2023-02-14T11:00:00Z",
  • "is_location_source": false,
  • "lock_version": 1
}

Read a provider connection

Ended connections remain addressable. Needs vehicles:read and connected-vehicles:read.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection, including ended ones

Responses

Response samples

Content type
application/json

active

{
  • "id": "00000000-0000-4000-8000-000000000012",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "provider_account_id": "00000000-0000-4000-8000-000000000031",
  • "provider": "DRVN",
  • "vin": "WBATA610809M97092",
  • "brand": "bmw",
  • "data_source": "bmw_b2c_reactive_car_data",
  • "started_at": "2023-02-14T10:00:00Z",
  • "is_location_source": false,
  • "lock_version": 0
}

Select or release a provider connection as location source

Selecting makes the connection the Vehicle's location source in place of any device association and adopts the newest position it already delivered; it never asks the provider. Fixes it delivers later move the Vehicle when they are newer. Releasing leaves the Vehicle without a source and keeps its last-known position. Only an active connection can be selected, and not while a plugin's operational Device supplies the location. Every source change advances lock_version of the connections and Device associations it selects or displaces. Needs vehicles:update and connected-vehicles:update.

Authorizations:
BearerAuth
path Parameters
connection_id
required
string <uuid>

UUID of the provider connection

Request Body schema: application/merge-patch+json
required
is_location_source
boolean

Select this connection as the Vehicle's location source, or release it. Selecting adopts the newest position it already delivered and never asks the provider.

lock_version
integer or null <int64> >= 0

Optional version precondition; a stale version returns 409.

Responses

Request samples

Content type
application/merge-patch+json

select

{
  • "is_location_source": true,
  • "lock_version": 0
}

Response samples

Content type
application/json

selected

{
  • "id": "00000000-0000-4000-8000-000000000012",
  • "vehicle_id": "00000000-0000-4000-8000-000000000001",
  • "provider_account_id": "00000000-0000-4000-8000-000000000031",
  • "provider": "DRVN",
  • "vin": "WBATA610809M97092",
  • "brand": "bmw",
  • "data_source": "bmw_b2c_reactive_car_data",
  • "started_at": "2023-02-14T10:00:00Z",
  • "is_location_source": true,
  • "lock_version": 1
}

Areas

Geographic areas defined by polygons and optional zip ranges

List all areas

Returns a paginated list of areas. Requires the 'areas:read' grant.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20
Example: size=20

Number of items per page (max 100).

Responses

Response samples

Content type
application/json

ServiceAreasPage

{
  • "items": [
    ],
  • "page": {
    }
}

Create an area

Requires the 'areas:create' grant.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 32 ] characters

Non-blank display name of the area; empty or whitespace-only values are rejected.

description
string <= 255 characters

Optional description

color
string

Hex color used to render the area overlay on maps

geo_json
required
any

GeoJSON Feature / FeatureCollection containing exactly one Polygon or MultiPolygon

Array of objects (ZipRange)

Optional postal-code ranges that fall inside this area

Responses

Request samples

Content type
application/json

CreateViennaNorthArea

{
  • "name": "Vienna North",
  • "description": "Alpine Facility Services coverage north of the Danube",
  • "color": "#1570EF",
  • "geo_json": {
    },
  • "zip_ranges": [
    ]
}

Response samples

Content type
application/json

CreatedViennaNorthArea

{
  • "id": "00000000-0000-4000-8000-000000002001",
  • "name": "Vienna North",
  • "description": "Alpine Facility Services coverage north of the Danube",
  • "color": "#1570EF",
  • "geo_json": {
    },
  • "zip_ranges": [
    ],
  • "created_at": "2026-08-20T08:30:00Z",
  • "updated_at": "2026-08-20T08:30:00Z",
  • "lock_version": 0
}

Get an area

Requires the 'areas:read' grant.

Authorizations:
BearerAuth
path Parameters
area_id
required
string <uuid>

UUID of the area.

Responses

Response samples

Content type
application/json

ViennaNorthArea

{
  • "id": "00000000-0000-4000-8000-000000002001",
  • "name": "Vienna North",
  • "description": "Alpine Facility Services coverage north of the Danube",
  • "color": "#1570EF",
  • "geo_json": {
    },
  • "zip_ranges": [
    ],
  • "created_at": "2026-08-20T08:30:00Z",
  • "updated_at": "2026-08-20T08:30:00Z",
  • "lock_version": 0
}

Delete an area

Requires the 'areas:delete' grant.

Authorizations:
BearerAuth
path Parameters
area_id
required
string <uuid>

UUID of the area.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update an area

JSON Merge Patch (RFC 7386): omitted fields remain unchanged; a field set to null is cleared (description and color). Requires the 'areas:update' grant.

Authorizations:
BearerAuth
path Parameters
area_id
required
string <uuid>

UUID of the area.

Request Body schema: application/merge-patch+json
required
name
string [ 1 .. 32 ] characters

Display name of the area. Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” name is required and cannot be cleared.

description
string or null <= 255 characters

Optional description. Omitted leaves the value unchanged; explicit null clears it.

color
string or null

Hex color used to render the area overlay on maps. Omitted leaves the value unchanged; explicit null clears it.

geo_json
any

GeoJSON Feature / FeatureCollection containing exactly one Polygon or MultiPolygon. Omitted or null leaves the value unchanged.

Array of objects or null (ZipRange)

Optional postal-code ranges that fall inside this area. Omitted or null leaves the value unchanged; a provided list replaces the stored ranges.

lock_version
integer or null <int64>

Optimistic lock version returned by the previous read

Responses

Request samples

Content type
application/merge-patch+json
Example

RenameViennaNorthArea

{
  • "name": "Vienna North Operations",
  • "lock_version": 0
}

Response samples

Content type
application/json

UpdatedViennaNorthArea

{
  • "id": "00000000-0000-4000-8000-000000002001",
  • "name": "Vienna North Operations",
  • "description": "Alpine Facility Services coverage north of the Danube",
  • "color": "#1570EF",
  • "geo_json": {
    },
  • "zip_ranges": [
    ],
  • "created_at": "2026-08-20T08:30:00Z",
  • "updated_at": "2026-08-20T09:30:00Z",
  • "lock_version": 1
}

Brands

Brands management API

List brands

Returns a paginated list of brands.

Authorizations:
BearerAuth
query Parameters
page
integer >= 0
Default: 0

Page number (0-based).

size
integer [ 1 .. 100 ]
Default: 20

Number of items per page (max 100).

sort
Array of strings
Example: sort=name:asc

Repeated sorting criteria in field:direction format. Allowed fields: id, name, email, phone_number, created_at, updated_at. Default: created_at:desc.

search
string

Search term for brand name, email, or phone number.

Responses

Response samples

Content type
application/json

BrandsListResponse

{}

Create a brand

Creates a brand. Logo updates should use the presigned upload intent endpoints under /api/v2/brands/{brand_id}/logo/uploads.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 0 .. 255 ] characters

Brand name

email
string <email> [ 0 .. 255 ] characters

Brand contact email

phone_number
string [ 0 .. 255 ] characters

International contact number. An explicit '+' country code is required; common formatting is accepted and normalized to canonical E.164. National numbers are rejected.

theme_id
string <uuid>

Optional custom theme linked to this brand

Responses

Request samples

Content type
application/json

CreateBrandRequest

{
  • "name": "Alpine Facility Services GmbH",
  • "email": "dispatch@example.invalid",
  • "phone_number": "+43 1 234 56 789"
}

Response samples

Content type
application/json

CreateBrandResponse

{}

Create brand logo upload intent

Creates a presigned upload URL for brand logo uploads (PNG/JPEG only).

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

Request Body schema: application/json
required
original_file_name
required
string non-empty

Original filename for the brand logo upload.

mime_type
required
string non-empty ^[iI][mM][aA][gG][eE]/([pP][nN][gG]|[jJ][pP][...

MIME type of the brand logo upload (image/png or image/jpeg).

Responses

Request samples

Content type
application/json

CreateBrandLogoUpload

{
  • "original_file_name": "alpine-brand-logo.png",
  • "mime_type": "image/png"
}

Response samples

Content type
application/json

AlpineBrandLogoUpload

{
  • "file_id": "00000000-0000-4000-8000-000000000811",
  • "upload_fields": {
    },
  • "upload_url_expires_at": "2026-08-20T10:20:00Z"
}

Create brand favicon upload intent

Creates a presigned upload URL for brand favicon uploads (PNG only).

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

Request Body schema: application/json
required
original_file_name
required
string non-empty

Original filename for the brand favicon upload.

mime_type
required
string non-empty ^[iI][mM][aA][gG][eE]/[pP][nN][gG]$

MIME type of the brand favicon upload (image/png only).

Responses

Request samples

Content type
application/json

CreateBrandFaviconUpload

{
  • "original_file_name": "alpine-brand-favicon.png",
  • "mime_type": "image/png"
}

Response samples

Content type
application/json

AlpineBrandFaviconUpload

{}

Link a verified custom domain to this brand

Idempotent: re-linking the same pair is a no-op. Returns 422 if the domain is not in VERIFIED status, or 409 if it is already linked to a different brand.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

custom_domain_id
required
string <uuid>

UUID of the custom-domain link.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Remove the link between this brand and a custom domain

Idempotent: unlinking a pair that is not linked returns 204. The custom domain row itself is untouched.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

custom_domain_id
required
string <uuid>

UUID of the custom-domain link.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Get brand by ID

Returns one brand by its UUID.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

Responses

Response samples

Content type
application/json

BrandResponse

{}

Delete a brand

Permanently removes the brand and its linked branding assets.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Update a brand

JSON Merge Patch (RFC 7386). Fields omitted remain unchanged; fields set to null are cleared (for nullable fields).

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

Request Body schema: application/merge-patch+json
required
lock_version
integer or null <int64>

Optimistic-locking version: validated when provided (409 on mismatch); omitting it skips the concurrency check

name
string

Brand name. Omitted leaves the value unchanged. Explicit null is rejected (422) โ€” name is required and cannot be cleared.

email
string or null

Brand contact email. Omitted leaves the value unchanged; explicit null clears it.

phone_number
string or null

International contact number. An explicit '+' country code is required; common formatting is accepted and normalized to canonical E.164. National numbers are rejected. Omitted leaves the value unchanged; explicit null clears it.

theme_id
string or null <uuid>

Optional custom theme linked to this brand. Omitted leaves the value unchanged; explicit null clears it.

Responses

Request samples

Content type
application/merge-patch+json

UpdateBrandNull

{
  • "lock_version": 2,
  • "email": null,
  • "phone_number": "+43 1 234 56 789"
}

Response samples

Content type
application/json

BrandResponse

{}

Get brand logo upload status

Returns upload lifecycle status for a brand logo upload session.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

file_id
required
string <uuid>

UUID of the uploaded file.

Responses

Response samples

Content type
application/json

UploadedAlpineBrandLogo

{}

Get brand favicon metadata

Returns the public proxy URL for the current brand favicon.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

Responses

Response samples

Content type
application/json

AlpineBrandFavicon

Delete brand favicon

Removes the current brand favicon.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Validation failed",
  • "status": 422,
  • "detail": "One or more fields failed validation",
  • "instance": "string",
  • "errors": [
    ],
  • "data": {
    }
}

Get brand favicon upload status

Returns upload lifecycle status for a brand favicon upload session.

Authorizations:
BearerAuth
path Parameters
brand_id
required
string <uuid>

UUID of the brand.

file_id
required
string <uuid>

UUID of the uploaded file.

Responses

Response samples

Content type
application/json

UploadedAlpineBrandFavicon

{}

Geocoding Settings

Geocoding settings API

Get geocoding settings

Returns the default country and default focus point used by geocoding flows.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json

ViennaGeocodingSettings

{
  • "default_country": "AT",
  • "default_focus_point": {
    },
  • "map": {
    }
}

Update geocoding settings

JSON Merge Patch (RFC 7386). Omitted fields remain unchanged; null resets a field to the default value. Inside map, omitted sub-fields also remain unchanged, so a patch may name a single zoom level. The whole patch is applied atomically: if any field fails validation, none is stored.

Authorizations:
BearerAuth
Request Body schema: application/merge-patch+json
required
default_country
string or null

Default country as ISO 3166-1 alpha-2 code. Omit to leave unchanged; null resets to the default (DE).

GeocodingFocusPoint (object) or null

Default focus point used to bias forward geocoding results. Omit to leave unchanged; null resets to the default (Berlin).

UpdateGeocodingMapDefaults (object) or null

Map defaults. Omit to leave unchanged; include only the sub-fields you want to change; null resets the whole block to the defaults (zoom 11, overview zoom 5.5, STREETS).

Responses

Request samples

Content type
application/merge-patch+json
Example

UpdateDefaultCountryOnly

{
  • "default_country": "AT"
}

Response samples

Content type
application/json

UpdatedViennaGeocodingSettings

{
  • "default_country": "AT",
  • "default_focus_point": {
    },
  • "map": {
    }
}

Webhooks

Tag: tag.created Webhook

Delivered when tag is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tag.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TagCreatedEventData)

Resource and previous values carried by TagCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tag.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tag: tag.updated Webhook

Delivered when tag is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tag.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TagUpdatedEventData)

Resource and previous values carried by TagUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tag.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tag: tag.deleted Webhook

Delivered when tag is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tag.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TagDeletedEventData)

Resource and previous values carried by TagDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tag.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

SMS gateway: sms_gateway.created Webhook

Delivered when sms gateway is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "sms_gateway.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (SmsGatewayCreatedEventData)

Resource and previous values carried by SmsGatewayCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "sms_gateway.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

SMS gateway: sms_gateway.updated Webhook

Delivered when sms gateway is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "sms_gateway.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (SmsGatewayUpdatedEventData)

Resource and previous values carried by SmsGatewayUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "sms_gateway.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

SMS gateway: sms_gateway.deleted Webhook

Delivered when sms gateway is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "sms_gateway.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (SmsGatewayDeletedEventData)

Resource and previous values carried by SmsGatewayDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "sms_gateway.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Task definition: task_definition.deleted Webhook

Delivered when task definition is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "task_definition.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TaskDefinitionDeletedEventData)

Resource and previous values carried by TaskDefinitionDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "task_definition.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Task definition: task_definition.created Webhook

Delivered when task definition is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "task_definition.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TaskDefinitionCreatedEventData)

Resource and previous values carried by TaskDefinitionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "task_definition.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Task definition: task_definition.updated Webhook

Delivered when task definition is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "task_definition.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TaskDefinitionUpdatedEventData)

Resource and previous values carried by TaskDefinitionUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "task_definition.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Task: task.created Webhook

Delivered when task is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "task.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TaskCreatedEventData)

Resource and previous values carried by TaskCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "task.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Task: task.updated Webhook

Delivered when task is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "task.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TaskUpdatedEventData)

Resource and previous values carried by TaskUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "task.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Task: task.deleted Webhook

Delivered when task is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "task.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TaskDeletedEventData)

Resource and previous values carried by TaskDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "task.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour settings: tour_settings.updated Webhook

Delivered when tour settings is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_settings.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourSettingsUpdatedEventData)

Resource and previous values carried by TourSettingsUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_settings.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour stop: tour.stop.created Webhook

Delivered when tour stop is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour.stop.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourStopCreatedEventData)

Resource and previous values carried by TourStopCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour.stop.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour stop: tour.stop.updated Webhook

Delivered when tour stop is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour.stop.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourStopUpdatedEventData)

Resource and previous values carried by TourStopUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour.stop.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour stop: tour.stop.deleted Webhook

Delivered when tour stop is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour.stop.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourStopDeletedEventData)

Resource and previous values carried by TourStopDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour.stop.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour Task assignment: tour_task_assignment.created Webhook

Delivered when tour task assignment is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_task_assignment.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourTaskAssignmentCreatedEventData)

Resource and previous values carried by TourTaskAssignmentCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_task_assignment.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour Task assignment: tour_task_assignment.updated Webhook

Delivered when tour task assignment is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_task_assignment.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourTaskAssignmentUpdatedEventData)

Resource and previous values carried by TourTaskAssignmentUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_task_assignment.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour Task assignment: tour_task_assignment.deleted Webhook

Delivered when tour task assignment is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_task_assignment.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourTaskAssignmentDeletedEventData)

Resource and previous values carried by TourTaskAssignmentDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_task_assignment.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour template: tour_template.created Webhook

Delivered when tour template is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_template.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourTemplateCreatedEventData)

Resource and previous values carried by TourTemplateCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_template.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour template: tour_template.updated Webhook

Delivered when tour template is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_template.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourTemplateUpdatedEventData)

Resource and previous values carried by TourTemplateUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_template.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour template: tour_template.deleted Webhook

Delivered when tour template is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_template.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourTemplateDeletedEventData)

Resource and previous values carried by TourTemplateDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_template.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour Vehicle assignment: tour_vehicle_assignment.created Webhook

Delivered when tour vehicle assignment is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_vehicle_assignment.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourVehicleAssignmentCreatedEventData)

Resource and previous values carried by TourVehicleAssignmentCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_vehicle_assignment.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour Vehicle assignment: tour_vehicle_assignment.updated Webhook

Delivered when tour vehicle assignment is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_vehicle_assignment.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourVehicleAssignmentUpdatedEventData)

Resource and previous values carried by TourVehicleAssignmentUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_vehicle_assignment.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour Vehicle assignment: tour_vehicle_assignment.deleted Webhook

Delivered when tour vehicle assignment is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour_vehicle_assignment.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourVehicleAssignmentDeletedEventData)

Resource and previous values carried by TourVehicleAssignmentDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour_vehicle_assignment.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour: tour.created Webhook

Delivered when tour is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourCreatedEventData)

Resource and previous values carried by TourCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour: tour.updated Webhook

Delivered when tour is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourUpdatedEventData)

Resource and previous values carried by TourUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Tour: tour.deleted Webhook

Delivered when tour is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "tour.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (TourDeletedEventData)

Resource and previous values carried by TourDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "tour.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Brand: brand.created Webhook

Delivered when brand is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "brand.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (BrandCreatedEventData)

Resource and previous values carried by BrandCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "brand.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Brand: brand.updated Webhook

Delivered when brand is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "brand.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (BrandUpdatedEventData)

Resource and previous values carried by BrandUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "brand.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Brand: brand.deleted Webhook

Delivered when brand is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "brand.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (BrandDeletedEventData)

Resource and previous values carried by BrandDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "brand.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Skill: skill.created Webhook

Delivered when skill is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "skill.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (SkillCreatedEventData)

Resource and previous values carried by SkillCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "skill.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Skill: skill.updated Webhook

Delivered when skill is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "skill.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (SkillUpdatedEventData)

Resource and previous values carried by SkillUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "skill.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Skill: skill.deleted Webhook

Delivered when skill is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "skill.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (SkillDeletedEventData)

Resource and previous values carried by SkillDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "skill.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Area: area.created Webhook

Delivered when area is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "area.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (AreaCreatedEventData)

Resource and previous values carried by AreaCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "area.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Area: area.updated Webhook

Delivered when area is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "area.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (AreaUpdatedEventData)

Resource and previous values carried by AreaUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "area.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Area: area.deleted Webhook

Delivered when area is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "area.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (AreaDeletedEventData)

Resource and previous values carried by AreaDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "area.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Measure unit: measure_unit.created Webhook

Delivered when measure unit is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "measure_unit.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (MeasureUnitCreatedEventData)

Resource and previous values carried by MeasureUnitCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "measure_unit.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Measure unit: measure_unit.updated Webhook

Delivered when measure unit is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "measure_unit.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (MeasureUnitUpdatedEventData)

Resource and previous values carried by MeasureUnitUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "measure_unit.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Measure unit: measure_unit.deleted Webhook

Delivered when measure unit is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "measure_unit.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (MeasureUnitDeletedEventData)

Resource and previous values carried by MeasureUnitDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "measure_unit.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Role: role.updated Webhook

Delivered when role is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "role.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (RoleUpdatedEventData)

Resource and previous values carried by RoleUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "role.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

User: user.created Webhook

Delivered when user is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "user.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (UserCreatedEventData)

Resource and previous values carried by UserCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "user.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

User: user.updated Webhook

Delivered when user is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "user.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (UserUpdatedEventData)

Resource and previous values carried by UserUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "user.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

User: user.deleted Webhook

Delivered when user is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "user.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (UserDeletedEventData)

Resource and previous values carried by UserDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "user.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Theme: theme.created Webhook

Delivered when theme is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "theme.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ThemeCreatedEventData)

Resource and previous values carried by ThemeCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "theme.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Theme: theme.updated Webhook

Delivered when theme is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "theme.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ThemeUpdatedEventData)

Resource and previous values carried by ThemeUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "theme.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Theme: theme.deleted Webhook

Delivered when theme is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "theme.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ThemeDeletedEventData)

Resource and previous values carried by ThemeDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "theme.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

File: file.created Webhook

Delivered when file is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "file.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (FileCreatedEventData)

Resource and previous values carried by FileCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "file.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

File: file.updated Webhook

Delivered when file is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "file.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (FileUpdatedEventData)

Resource and previous values carried by FileUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "file.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

File: file.deleted Webhook

Delivered when file is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "file.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (FileDeletedEventData)

Resource and previous values carried by FileDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "file.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Document: document.created Webhook

Delivered when document is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "document.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DocumentCreatedEventData)

Resource and previous values carried by DocumentCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "document.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Document: document.updated Webhook

Delivered when document is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "document.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DocumentUpdatedEventData)

Resource and previous values carried by DocumentUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "document.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Document: document.deleted Webhook

Delivered when document is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "document.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DocumentDeletedEventData)

Resource and previous values carried by DocumentDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "document.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Document version: document.version.created Webhook

Delivered when document version is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "document.version.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DocumentVersionCreatedEventData)

Resource and previous values carried by DocumentVersionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "document.version.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Document permissions: document.permissions.updated Webhook

Delivered when document permissions is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "document.permissions.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DocumentPermissionsUpdatedEventData)

Resource and previous values carried by DocumentPermissionsUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "document.permissions.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Folder: folder.created Webhook

Delivered when folder is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "folder.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (FolderCreatedEventData)

Resource and previous values carried by FolderCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "folder.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Folder: folder.updated Webhook

Delivered when folder is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "folder.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (FolderUpdatedEventData)

Resource and previous values carried by FolderUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "folder.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Folder: folder.deleted Webhook

Delivered when folder is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "folder.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (FolderDeletedEventData)

Resource and previous values carried by FolderDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "folder.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Folder permissions: folder.permissions.updated Webhook

Delivered when folder permissions is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "folder.permissions.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (FolderPermissionsUpdatedEventData)

Resource and previous values carried by FolderPermissionsUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "folder.permissions.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Comment: comment.created Webhook

Delivered when comment is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "comment.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (CommentCreatedEventData)

Resource and previous values carried by CommentCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "comment.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Comment: comment.updated Webhook

Delivered when comment is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "comment.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (CommentUpdatedEventData)

Resource and previous values carried by CommentUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "comment.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Comment reaction: comment.reaction.created Webhook

Delivered when comment reaction is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "comment.reaction.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (CommentReactionCreatedEventData)

Resource and previous values carried by CommentReactionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "comment.reaction.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Comment reaction: comment.reaction.deleted Webhook

Delivered when comment reaction is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "comment.reaction.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (CommentReactionDeletedEventData)

Resource and previous values carried by CommentReactionDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "comment.reaction.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Record: object.example.created Webhook

Delivered when record is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent. The example segment stands for the object's actual definition slug.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string^object\.[^.]+\.created$

Event name with the actual object definition slug; example is illustrative only.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ObjectRecordCreatedEventData)

Resource and previous values carried by ObjectRecordCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "object.example.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Record: object.example.updated Webhook

Delivered when record is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent. The example segment stands for the object's actual definition slug.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string^object\.[^.]+\.updated$

Event name with the actual object definition slug; example is illustrative only.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ObjectRecordUpdatedEventData)

Resource and previous values carried by ObjectRecordUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "object.example.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Record: object.example.deleted Webhook

Delivered when record is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent. The example segment stands for the object's actual definition slug.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string^object\.[^.]+\.deleted$

Event name with the actual object definition slug; example is illustrative only.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ObjectRecordDeletedEventData)

Resource and previous values carried by ObjectRecordDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "object.example.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Object permissions: object.example.permissions.updated Webhook

Delivered when object permissions is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent. The example segment stands for the object's actual definition slug.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string^object\.[^.]+\.permissions\.updated$

Event name with the actual object definition slug; example is illustrative only.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ObjectRecordPermissionsUpdatedEventData)

Resource and previous values carried by ObjectRecordPermissionsUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "object.example.permissions.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Object definition: object_definition.created Webhook

Delivered when object definition is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "object_definition.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ObjectDefinitionCreatedEventData)

Resource and previous values carried by ObjectDefinitionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "object_definition.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Object definition: object_definition.updated Webhook

Delivered when object definition is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "object_definition.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ObjectDefinitionUpdatedEventData)

Resource and previous values carried by ObjectDefinitionUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "object_definition.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Object definition: object_definition.deleted Webhook

Delivered when object definition is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "object_definition.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ObjectDefinitionDeletedEventData)

Resource and previous values carried by ObjectDefinitionDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "object_definition.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Device: device.created Webhook

Delivered when device is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "device.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DeviceCreatedEventData)

Resource and previous values carried by DeviceCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "device.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Device: device.updated Webhook

Delivered when device is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "device.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DeviceUpdatedEventData)

Resource and previous values carried by DeviceUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "device.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Device: device.deleted Webhook

Delivered when device is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "device.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DeviceDeletedEventData)

Resource and previous values carried by DeviceDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "device.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Workspace Device settings: device_settings.updated Webhook

Delivered when workspace device settings is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "device_settings.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (DeviceSettingsUpdatedEventData)

Resource and previous values carried by DeviceSettingsUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "device_settings.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle definition: vehicle_definition.deleted Webhook

Delivered when vehicle definition is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_definition.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleDefinitionDeletedEventData)

Resource and previous values carried by VehicleDefinitionDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_definition.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle definition: vehicle_definition.created Webhook

Delivered when vehicle definition is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_definition.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleDefinitionCreatedEventData)

Resource and previous values carried by VehicleDefinitionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_definition.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle definition: vehicle_definition.updated Webhook

Delivered when vehicle definition is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_definition.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleDefinitionUpdatedEventData)

Resource and previous values carried by VehicleDefinitionUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_definition.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicleโ€“Device association: vehicle_device_association.created Webhook

Delivered when vehicleโ€“device association is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_device_association.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleDeviceAssociationCreatedEventData)

Resource and previous values carried by VehicleDeviceAssociationCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_device_association.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicleโ€“Device association: vehicle_device_association.updated Webhook

Delivered when vehicleโ€“device association is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_device_association.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleDeviceAssociationUpdatedEventData)

Resource and previous values carried by VehicleDeviceAssociationUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_device_association.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle location source: vehicle.location_source.updated Webhook

Delivered when vehicle location source is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle.location_source.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleLocationSourceUpdatedEventData)

Resource and previous values carried by VehicleLocationSourceUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle.location_source.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle: vehicle.deleted Webhook

Delivered when vehicle is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleDeletedEventData)

Resource and previous values carried by VehicleDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle: vehicle.created Webhook

Delivered when vehicle is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleCreatedEventData)

Resource and previous values carried by VehicleCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle: vehicle.updated Webhook

Delivered when vehicle is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleUpdatedEventData)

Resource and previous values carried by VehicleUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Connected-vehicle provider account: connected_vehicle_provider.created Webhook

Delivered when connected-vehicle provider account is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "connected_vehicle_provider.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ConnectedVehicleProviderCreatedEventData)

Resource and previous values carried by ConnectedVehicleProviderCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "connected_vehicle_provider.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Connected-vehicle provider account: connected_vehicle_provider.updated Webhook

Delivered when connected-vehicle provider account is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "connected_vehicle_provider.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ConnectedVehicleProviderUpdatedEventData)

Resource and previous values carried by ConnectedVehicleProviderUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "connected_vehicle_provider.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Connected-vehicle provider account: connected_vehicle_provider.deleted Webhook

Delivered when connected-vehicle provider account is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "connected_vehicle_provider.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (ConnectedVehicleProviderDeletedEventData)

Resource and previous values carried by ConnectedVehicleProviderDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "connected_vehicle_provider.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection authorization operation: vehicle_provider_connection.authorization_operation.created Webhook

Delivered when vehicle provider connection authorization operation is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.authorization_operation.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionAuthorizationOperationCreatedEventData)

Resource and previous values carried by VehicleProviderConnectionAuthorizationOperationCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.authorization_operation.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection authorization operation: vehicle_provider_connection.authorization_operation.updated Webhook

Delivered when vehicle provider connection authorization operation is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.authorization_operation.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionAuthorizationOperationUpdatedEventData)

Resource and previous values carried by VehicleProviderConnectionAuthorizationOperationUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.authorization_operation.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection data operation: vehicle_provider_connection.data_operation.created Webhook

Delivered when vehicle provider connection data operation is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.data_operation.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionDataOperationCreatedEventData)

Resource and previous values carried by VehicleProviderConnectionDataOperationCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.data_operation.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection data operation: vehicle_provider_connection.data_operation.updated Webhook

Delivered when vehicle provider connection data operation is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.data_operation.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionDataOperationUpdatedEventData)

Resource and previous values carried by VehicleProviderConnectionDataOperationUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.data_operation.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection phone-fix prediction: vehicle_provider_connection.phone_fix_prediction.created Webhook

Delivered when vehicle provider connection phone-fix prediction is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.phone_fix_prediction.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionPhoneFixPredictionCreatedEventData)

Resource and previous values carried by VehicleProviderConnectionPhoneFixPredictionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.phone_fix_prediction.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection phone-fix prediction: vehicle_provider_connection.phone_fix_prediction.updated Webhook

Delivered when vehicle provider connection phone-fix prediction is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.phone_fix_prediction.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionPhoneFixPredictionUpdatedEventData)

Resource and previous values carried by VehicleProviderConnectionPhoneFixPredictionUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.phone_fix_prediction.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection: vehicle_provider_connection.created Webhook

Delivered when vehicle provider connection is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionCreatedEventData)

Resource and previous values carried by VehicleProviderConnectionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Vehicle provider connection: vehicle_provider_connection.updated Webhook

Delivered when vehicle provider connection is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "vehicle_provider_connection.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (VehicleProviderConnectionUpdatedEventData)

Resource and previous values carried by VehicleProviderConnectionUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "vehicle_provider_connection.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Workflow: workflow.created Webhook

Delivered when workflow is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "workflow.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (WorkflowCreatedEventData)

Resource and previous values carried by WorkflowCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "workflow.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Workflow: workflow.updated Webhook

Delivered when workflow is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "workflow.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (WorkflowUpdatedEventData)

Resource and previous values carried by WorkflowUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "workflow.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Workflow: workflow.deleted Webhook

Delivered when workflow is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "workflow.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (WorkflowDeletedEventData)

Resource and previous values carried by WorkflowDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "workflow.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Workflow version: workflow.version.created Webhook

Delivered when workflow version is created. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "workflow.version.created"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (WorkflowVersionCreatedEventData)

Resource and previous values carried by WorkflowVersionCreatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "workflow.version.created",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Workflow version: workflow.version.updated Webhook

Delivered when workflow version is updated. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "workflow.version.updated"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (WorkflowVersionUpdatedEventData)

Resource and previous values carried by WorkflowVersionUpdatedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "workflow.version.updated",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}

Workflow version: workflow.version.deleted Webhook

Delivered when workflow version is deleted. Verify the Standard Webhooks signature against the raw request body; no bearer token is sent.

header Parameters
webhook-id
required
string <uuid>

Unique message id (UUID). Stable across retries of the same event โ€” use it as an idempotency key.

webhook-timestamp
required
string^[0-9]+$
Example: 1787565600

Unix timestamp in seconds at which this delivery attempt was signed. Reject deliveries outside your tolerance window.

webhook-signature
required
string
Example: v1,dGVzdC1zaWduYXR1cmU=

Standard Webhooks signature: v1, + base64 HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw_body}.

Request Body schema: application/json
required
type
required
string
Value: "workflow.version.deleted"

Event name identifying this delivery.

id
required
string <uuid>

Delivery id, identical to the webhook-id header. Unique per endpoint and stable across retries โ€” use it as this endpoint's idempotency key.

event_id
required
string <uuid>

Id of the underlying event. Identical across every endpoint and every retry that delivers it โ€” use it to deduplicate when more than one endpoint feeds one consumer.

timestamp
required
string <date-time>

When the event occurred (ISO 8601, UTC). Not the time this attempt was signed โ€” that is the webhook-timestamp header, and the two differ on a retry.

payload_version
required
integer <int32> [ 1 .. 1 ]

Webhook payload contract version.

tenant_id
required
string <uuid>

Workspace the event belongs to.

object (WebhookActor)

The principal that caused the event.

object (WebhookRequestContext)

Tracing handles for the API request that caused this event.

required
object (WorkflowVersionDeletedEventData)

Resource and previous values carried by WorkflowVersionDeletedEvent.

Responses

Request samples

Content type
application/json
{
  • "type": "workflow.version.deleted",
  • "id": "00000000-0000-4000-8000-000000009001",
  • "event_id": "00000000-0000-4000-8000-000000009002",
  • "timestamp": "2026-09-24T10:00:00Z",
  • "payload_version": 1,
  • "tenant_id": "00000000-0000-4000-8000-000000000001",
  • "actor": {
    },
  • "request": {
    },
  • "data": {
    }
}