API docs by Redocly

Trendspek - External API (1.0.1)

Download OpenAPI specification:

Complete Trendspek API endpoints including core data types for annotations, datasets, assets, and upload workflows.

Authentication

This uses current security best practice, implementing what is known as the Client Credentials Workflow.

Authentication will require a client secret and a client key.

Please refer to the Trendspek Support for help in obtaining these.

Get Access Token

Access to the API, requires exchanging Client ID and Secret for an API Token.

The Expiry Time will be set to at most 1 hour. This short-lived API token is best practice, and will reduce the damage if the API token is intercepted.

Authorizations:
BearerToken
Request Body schema: application/json

Authenticate client id and secret and returns an access token

client_id
string <integer>
client_secret
string <password>

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "pa$$word"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 3600,
  • "token_type": "string"
}

Uploads

API Endpoints to facilitate the Upload of datasets for processing and visualisation in Trendspek.

Create An Upload

Actions:

  • Create a new Pending Dataset, for a new or existing Asset.
  • Create new Upload Project.
  • Generate Storage Location and Signed URLs for upload to AWS S3 or Azure Storage.
Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

Request Body schema: application/json

Create Dataset request

asset_uuid
string or null <uuid>

UUID of existing asset (optional for new assets)

type
string
Value: ["photogrammetry","preprocessed_metashape","preprocessed_contextcapture","preprocessed_reality_capture","preprocessed_dji_terra"]

Processing type for the dataset

name
string <= 255 characters

Dataset name (required when asset_uuid is not provided, ignored when asset_uuid is provided)

description
string

Dataset description

capture_date
string <date>

The date when the dataset was captured

comments
string or null

Uploader comments (optional)

metadata
object or null

Optional metadata for the dataset (for future use)

Array of objects non-empty

Array of files to upload (minimum 1 file required)

Responses

Request samples

Content type
application/json
{
  • "asset_uuid": "76807d23-a41c-4ee1-a173-773f47fc22c8",
  • "type": "photogrammetry",
  • "name": "string",
  • "description": "string",
  • "capture_date": "2019-08-24",
  • "comments": "string",
  • "metadata": { },
  • "upload_files": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create a Second Upload Project

Actions:

  • Create a new Upload Project, attached to existing Pending Dataset.
  • Generate Storage Location and Signed URLs for upload to AWS S3 or Azure Storage.
Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

pending_dataset
required
string <uuid>

Pending Dataset UUID from the create endpoint.

Request Body schema: application/json

Create Upload Project request

Array of objects non-empty

Array of files to upload (minimum 1 file required)

Responses

Request samples

Content type
application/json
{
  • "upload_files": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Cancel upload

Actions:

  • Cancel upload project and pending dataset.
  • Delete uploaded files from Trendspek Storage.
Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

pending_dataset
required
string <uuid>

Pending Dataset UUID from the create endpoint.

Request Body schema: application/json

Cancel upload request

cancel_reason
string

A short summary for cancelling upload

Responses

Request samples

Content type
application/json
{
  • "cancel_reason": "string"
}

Response samples

Content type
application/json
{
  • "error": "Unauthorized"
}

Upload Status

Returns the current status of the upload project (e.g.: uploading, processing, processed, failed, cancelled).

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

pending_dataset
required
string <uuid>

Pending Dataset UUID from the create endpoint.

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "status": "string",
  • "processor_comments": "string",
  • "fail_reason": "string",
  • "relationships": {
    }
}

Complete upload

Signals that all dataset files have been uploaded and that processing can begin.

Actions:

  • Mark upload project as complete
  • Verify file uploads
  • Queue for processing
Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

pending_dataset
required
string <uuid>

Pending Dataset UUID from the create endpoint.

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "status": "string",
  • "processor_comments": "string",
  • "fail_reason": "string",
  • "relationships": {
    }
}

List Uploads

List the uploads for the company.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Company UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Data

Data endpoints typically come in two varieties: a list view and a show view.

List views show a reduced dataset and typically use cursor-based pagination for efficient handling of large sets of data. They can also be used for searching objects matching a certain criteria.

The Show views contains more data, and can optionally include related information.

Data: Billing Company

Billing Companies contain one or more companies. Use these endpoints to review key contact details.

Show Billing Company

Retrieve the current billing company associated with the API token.

Details are for the primary contact for this Billing Company.

NB: This is the only singular endpoint, as only one billing company will ever be accessible at a time.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Data: Companies

Companies are the primary organisational unit within Trendspek.

Companies belong to Billing Companies.

Companies have Assets.

Users have a Role within a Company that gives them access to that Company.

Users must have an asset role assigned for each company asset they need access to.

List Companies

This will return a list of accessible companies within the billing company.

You can filter the results by company name (partial match).

This endpoint uses cursor-based pagination for efficient handling of large sets of data.

Authorizations:
BearerToken
query Parameters
cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNSAxNDozMDowMCIsImlkIjoxMjN9

Cursor token for pagination. Use the next_cursor from the previous response to get the next page.

per_page
integer [ 1 .. 100 ]
Default: 15
Example: per_page=25

Number of items per page (maximum: 100, default: 15)

filter[company]
string
Example: filter[company]=Acme Corp

Filter companies by name (partial match)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Show Company

Show a specific company's details.

You can include related resources using the 'include' parameter.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Company UUID

query Parameters
include
string
Example: include=billingCompany

Comma-separated list of relationships to include (billingCompany)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Data: Assets

An Asset is a real-world object of interest—usually a building or built object.

An Asset will have one or more Datasets.

List Assets

Retrieve a paginated collection of assets for the specified company.

You can filter the results by name, dataset, or annotation UUID.

This endpoint uses cursor-based pagination for efficient handling of large sets of data.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Company UUID

query Parameters
cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNSAxNDozMDowMCIsImlkIjoxMjN9

Cursor token for pagination. Use the next_cursor from the previous response to get the next page.

per_page
integer [ 1 .. 100 ]
Default: 15
Example: per_page=25

Number of items per page (maximum: 100, default: 15)

filter[name]
string
Example: filter[name]=Building A

Filter assets by name (partial match)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Show Asset

Retrieve a specific asset with its company relationship.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

asset
required
string <uuid>

Asset UUID

query Parameters
include
string
Example: include=company

Comma-separated list of relationships to include (company)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Data: Datasets

A Dataset is a representation of an Asset in 3D, captured at a point in time.

Datasets can have different types: e.g. photogrammetry, lidar, thermal.

Datasets can be captured over different points in time to see changes in an asset over time.

List Datasets

Retrieve a paginated collection of datasets for the specified company.

You can filter the results by name, asset, or annotation UUID.

This endpoint uses cursor-based pagination for efficient handling of large sets of data.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Company UUID

query Parameters
cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNSAxNDozMDowMCIsImlkIjoxMjN9

Cursor token for pagination. Use the next_cursor from the previous response to get the next page.

per_page
integer [ 1 .. 100 ]
Default: 15
Example: per_page=25

Number of items per page (maximum: 100, default: 15)

filter[name]
string
Example: filter[name]=Dataset 2024-01

Filter datasets by name (partial match)

filter[asset]
string <uuid>
Example: filter[asset]=550e8400-e29b-41d4-a716-446655440001

Filter datasets by asset UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Show Dataset

Retrieve a specific dataset with its asset and company relationships.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

dataset
required
string <uuid>

Dataset UUID

query Parameters
include
string
Example: include=asset

Comma-separated list of relationships to include (asset)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Data: Annotations

An Annotation is a data point in 3D space. Annotations belong to Assets, and are associated with a Dataset.

List Annotations

Retrieve a paginated collection of annotations that belong to the specified company.

You can filter the results by asset, dataset, folder, or template UUID.

You can also include related resources using the 'include' parameter.

This endpoint uses cursor-based pagination for efficient handling of large sets of data.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Company UUID

query Parameters
cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNSAxNDozMDowMCIsImlkIjoxMjN9

Cursor token for pagination. Use the next_cursor from the previous response to get the next page.

per_page
integer [ 1 .. 100 ]
Default: 15
Example: per_page=25

Number of items per page (maximum: 100, default: 15)

filter[asset]
string <uuid>
Example: filter[asset]=550e8400-e29b-41d4-a716-446655440000

Filter annotations by asset UUID

filter[dataset]
string <uuid>
Example: filter[dataset]=550e8400-e29b-41d4-a716-446655440001

Filter annotations by dataset UUID

filter[folder]
string <uuid>
Example: filter[folder]=550e8400-e29b-41d4-a716-446655440002

Filter annotations by annotation folder UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Show Annotation

Retrieve a specific annotation by its UUID, ensuring it belongs to the specified company. An annotation will come with related template and photo data.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

annotation
required
string <uuid>

Annotation UUID

query Parameters
include
string
Example: include=asset,dataset,drawing,featuredImage

Comma-separated list of relationships to include (asset, dataset, folder, drawing, featuredImage, supportingImage)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List Images

Retrieve a paginated collection of annotation images that belong to the specified annotation.

This endpoint uses cursor-based pagination for efficient handling of large datasets.

You can filter the results by asset or dataset UUID.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

Company UUID

annotation
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440001

Annotation UUID

query Parameters
cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNSAxNDozMDowMCIsImlkIjoxMjN9

Cursor token for pagination. Use the next_cursor from the previous response to get the next page.

per_page
integer [ 1 .. 100 ]
Default: 15
Example: per_page=25

Number of items per page (maximum: 100, default: 15)

filter[asset]
string <uuid>
Example: filter[asset]=550e8400-e29b-41d4-a716-446655440000

Filter photos by asset UUID

filter[dataset]
string <uuid>
Example: filter[dataset]=550e8400-e29b-41d4-a716-446655440001

Filter photos by dataset UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Template Data

Retrieve template data associated with a specific annotation. This endpoint returns the template form data that has been filled out for the annotation. Returns null if no template data exists for the annotation.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

annotation
required
string <uuid>

Annotation UUID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Data: Drawings

Drawings are the visual representation of an Annotation on a 3D model.

Get Drawing

Retrieve a specific drawing by its UUID, ensuring it belongs to the specified company. You can include the related annotation using the 'include' parameter.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

annotation
required
string <uuid>

Annotation UUID

drawing
required
string <uuid>

Drawing UUID

query Parameters
include
string
Example: include=annotation

Comma-separated list of related resources to include (annotation)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Data: Templates

Annotation Templates contain user-specified data, in user-defined fields.

List Templates

Retrieve a paginated collection of templates that belong to the specified company.

This endpoint uses cursor-based pagination for efficient handling of large datasets.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

query Parameters
per_page
integer [ 1 .. 100 ]
Example: per_page=15

Number of templates per page (max 100)

cursor
string

Cursor for pagination (provided in previous response)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Get Template

Retrieve a specific template.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

template
required
string <uuid>

Template UUID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Custom Fields

Retrieve custom fields associated with the specified template.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

template
required
string <uuid>

Template UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Data: Users

Users represent people who have access to Trendspek. Users have a Role within a Company. The Role governs what they are able to do within Trendspek.

List Users

Retrieve a paginated collection of users within the billing company.

You can filter the results by fuzzy search (searches email, first_name, last_name), first_name, last_name, email, or company UUID.

This endpoint uses cursor-based pagination for efficient handling of large sets of data.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

query Parameters
cursor
string
Example: cursor=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNSAxNDozMDowMCIsImlkIjoxMjN9

Cursor token for pagination. Use the next_cursor from the previous response to get the next page.

per_page
integer [ 1 .. 100 ]
Default: 15
Example: per_page=25

Number of items per page (maximum: 100, default: 15)

filter[fuzzy-search]
string
Example: filter[fuzzy-search]=John

Fuzzy search across email, first_name, and last_name fields

filter[first_name]
string
Example: filter[first_name]=John

Filter users by first name (partial match)

filter[last_name]
string
Example: filter[last_name]=Doe

Filter users by last name (partial match)

filter[email]
string
Example: filter[email]=john@example.com

Filter users by email (partial match)

filter[company]
string <uuid>
Example: filter[company]=550e8400-e29b-41d4-a716-446655440000

Filter users by company UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Data: Photos

List Photos

Retrieve a paginated collection of photos that belong to assets within the specified company.

This endpoint uses cursor-based pagination for efficient handling of large datasets.

You can filter the results by asset or dataset UUID.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

query Parameters
per_page
integer <= 100
Default: 15

Number of photos per page (max 100)

cursor
string

Cursor for pagination

filter[asset]
string <uuid>

Filter photos by asset UUID

filter[dataset]
string <uuid>

Filter photos by dataset UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Show Photo

Retrieve a specific photo by its UUID, ensuring it belongs to an asset within the specified company.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

photo
required
string <uuid>

Photo UUID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Data: Asset Files

List Asset Files

Retrieve a paginated collection of asset files that belong to assets within the specified company.

This endpoint uses cursor-based pagination for efficient handling of large datasets.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

query Parameters
per_page
integer [ 1 .. 100 ]
Default: 15

Number of items to return per page (1-100)

cursor
string

Cursor for pagination

filter[asset]
string <uuid>
Example: filter[asset]=550e8400-e29b-41d4-a716-446655440002

Filter asset file by asset UUID

filter[annotation]
string <uuid>
Example: filter[annotation]=550e8400-e29b-41d4-a716-446655440002

Filter asset file by annotation UUID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Show Asset File

Retrieve a specific asset file by its UUID, ensuring it belongs to an asset within the specified company.

Authorizations:
BearerToken
path Parameters
company
required
string <uuid>

Company UUID

asset_file
required
string <uuid>

Asset File UUID

query Parameters
include
string
Example: include=asset

Comma-separated list of relationships to include (asset)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}