Trimble Hierarchies API

Operations for querying Hierarchies.

GitHub OpenAPI

Operations 2

GET /models/{modelId}/hierarchies Lists hierarchy relations #
GET /models/{modelId}/hierarchies/{type} Lists hierarchy relations belonging to a given type #

Documentation

Specifications

Schemas & Data

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/trimble:trimble-hierarchies-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

trimble-hierarchies-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Trimble Connect Model Hierarchies API
  description: '# Overview

    The Trimble Connect Model Service allows you to execute queries over Building Information Models (BIM). Documentation for this service is available on the Trimble Developer site. # Getting started

    **You must agree to the Terms of Service to use Connect services.**


    You need to complete the steps in the Getting started guide to be able to call the API. # Concepts

    Please see Common Concepts in the Connect Platform overview. ## Files and Models


    Models are files in the project that are recognized by the system as 2D or 3D models and have TrimBIM representation attached. The "modelId" equals to the "fileId" and represent the same identifier in in the context of the Model APIs or File APIs respectively. Typically models are discovered by selecting a project from a list of projects available to user, then listing files in a project and selecting a file that represents are model. The Project and File APIs are part of the Trimble Connect API surface. ## Model Entity Identifiers

    Entities can be referred to by their external (source) Id, as well as by their internal (runtime) Id. The external (source) Id is assigned to each entity by the authoring application and can take the form of

    a GUID, a string or even a number. The internal (runtime) Id is the numeric index of the entity within the model, ranging from 0 to N-1, where N is the

    number of entities in the model. Some authoring applications do not use external (source) Ids, in which case they will not be available. Internal (runtime) Ids can always be used. In cases when external (source) identifier is missing a so called "not persistent" identifier can be generated by the service from the entity geometry. The "not persistent" identifier is not guaranteed to be constant, but in most cases it is until entity geometry changes. Such identifiers (external if it exists or generated if external is missing) are referred to as "connect" identifiers. When passing an entity identifier to an endpoint, it

    can be prefixed with `id:` to explicitly specify that it is an external (source)

    Id, or with the `idx:` prefix to specify that it is an internal (runtime) Id

    (index). The `idc:` prefix can be used to specify that it is a "connect" identifier (meaning that it might be generated if proper source identifier is missing). Some endpoints also allow passing an index explicitly (which should

    always be the internal/runtime Id and needs no prefix). The entity Id prefixes

    can be useful to resolve the ambiguity between the two type of entity identifiers

    in the case when both the external (source) Ids and internal (runtime) Ids are

    numbers. If a prefix is not given, the service will attempt to determine the

    type of the Id. If this cannot be done based on the value of the Id (eg. when

    it is a number), the service will assume that it''s an external (source) Id. Examples:

    * an entity identifier with the value `id:123` will be considered an external (source) Id. * an entity identifier with the value `idx:123` will be considered an internal (runtime) Id. * an entity identifier with the value `idc:ABC123` will be considered an "connect" identifier that might be equal to external id or generated from geometry. * an entity identifier with the value `123` will be primarily considered an "connect" identifier, but if the service

    determines that there are no entities with such "connect" identifiers exist, then it will attempt to use it as an internal (runtime) Id (index). ## Eventual Read Consistency

    The service does not perform any write operations and therefore has no database of its own. The API responses are eventually consistent with the file operations performed with Trimble Connect

    File APIs and file processing. When you read data from the service, the response might not reflect the results of the most recently completed write operation in FileService

    and file processing. The response might include some stale data due to caching

    in place.'
  version: v1
  contact:
    name: Trimble Connect Support
    url: https://connect.trimble.com
    email: connect-support@trimble.com
  license:
    name: Trimble Connect SDK Internal Use License
    url: https://developer.trimble.com/docs/connect/terms/SDK-IU-license-agreement
  termsOfService: https://developer.trimble.com/docs/connect/terms
servers:
- url: https://model-api11.connect.trimble.com
  description: PROD NA
- url: https://model-api21.connect.trimble.com
  description: PROD EU
- url: https://model-api22.connect.trimble.com
  description: PROD UK
- url: https://model-api31.connect.trimble.com
  description: PROD AP
- url: https://model-api32.connect.trimble.com
  description: PROD AU
security:
- Bearer: []
tags:
- name: Hierarchies
  description: Operations for querying Hierarchies.
paths:
  /models/{modelId}/hierarchies:
    get:
      tags:
      - Hierarchies
      summary: Lists hierarchy relations
      operationId: ListHierarchies
      description: Lists all hierarchy relations in the model.
      parameters:
      - name: modelId
        in: path
        description: The model Id.
        required: true
        schema:
          type: string
          minLength: 1
      - name: versionId
        in: query
        description: The file version identifier, if not specified the latest version of the file is assumed.
        schema:
          type: string
          minLength: 1
      - name: top
        in: query
        description: The maximum number of items returned in a single response.
        schema:
          type: integer
          minimum: 1
          maximum: 30000
          default: 30000
      - name: offset
        in: query
        description: The initial value to be fetched from the total result.
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: parentId
        in: query
        description: 'If specified, only immediate children of a given parentId are returned. If not specified, all hierarchy relations are returned. If special value `root` is passed then only root hierarchy relations will be returned.

          ParentId could be either external Id (prefixed by `id:`), internal Id (prefixed by `idx:`), ''connect'' id (prefixed with ''idc:'') or could have value `root`. If a value is passed without a prefix then it is evaluated based on the following precedence : connect Id, internal Id.'
        schema:
          type: string
      - name: parentIdx
        in: query
        deprecated: true
        description: If specified, only immediate children of a given parentIdx are returned. If not specified, all hierarchy relations are returned. It accepts only internal identifiers which are generally integer values with no prefix.
        schema:
          type: integer
      - name: childId
        in: query
        description: 'If specified, only immediate parents of a given childId are returned. If not specified, all hierarchy relations are returned. ChildId could be either external Id (prefixed by `id:`), runtime internal Id (prefixed by `idx:`) or connect identifier (prefixed with ''idc:''). If a value is passed without a prefix then it is evaluated based on the following precedence : connect Id, internal Id.'
        schema:
          type: string
      - name: childIdx
        in: query
        deprecated: true
        description: If specified, only immediate parents of a given childIdx are returned. If not specified, all hierarchy relations are returned.r It accepts only internal identifiers which are generally integer values with no prefix.
        schema:
          type: integer
      - name: type
        in: query
        description: If specified, only relations that belong to the given hierarchy are returned. If not specified all relations are returned. If hierarchy is prefixed with `!` sign then relations that are NOT involved in the given hierarchy are returned. The hierarchy type string is matched using exact case sensitive comparison.
        schema:
          type: string
      - name: include
        in: query
        description: 'The identifier(external or internal) to be returned in the response.

          By default response will contain external Id (include=id format). If include=idx then internal Ids are returned and external Ids are omitted. If include=idx,id then both internal and external format identifiers will be returned.'
        schema:
          type: array
          items:
            type: string
            enum:
            - id
            - idx
            - idc
        explode: false
      responses:
        '200':
          description: Success
          headers:
            X-ModelVersionId:
              schema:
                type: string
              description: The actual model version identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HierarchyRelationsResponse'
        '401':
          description: Authorization information is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: 'Input validation Error: value is missing/null/invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: User has no permissions to execute this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The specified modelId/versionId was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Session is invalid/Gateway timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /models/{modelId}/hierarchies/{type}:
    get:
      tags:
      - Hierarchies
      summary: Lists hierarchy relations belonging to a given type
      operationId: GetHierarchyByType
      description: Lists all hierarchy relations belonging to a given type in the model.
      parameters:
      - name: modelId
        in: path
        description: The model Id.
        required: true
        schema:
          type: string
          minLength: 1
      - name: type
        in: path
        description: The hierarchy type. The possible hierarchy types that exist in the model can be discovered using GetModelInfo endpoint.
        required: true
        schema:
          type: string
          minLength: 1
      - name: versionId
        in: query
        description: The file version identifier, if not specified the latest version of the file is assumed.
        schema:
          type: string
          minLength: 1
      - name: top
        in: query
        description: The maximum number of items returned in a single response.
        schema:
          type: integer
          minimum: 1
          maximum: 30000
          default: 30000
      - name: offset
        in: query
        description: The initial value to be fetched from the total result.
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: parentId
        in: query
        description: 'If specified, only immediate children of a given parentId are returned. If not specified, all hierarchy relations are returned. If `root` is passed then only root hierarchy relations will be returned.

          ParentId could be either external Id (prefixed by `id:`), internal Id (prefixed by `idx:`) or could have value `root`. If a value is passed without a prefix then it is evaluated based on the precedence: external Id, internal Id.'
        schema:
          type: string
      - name: parentIdx
        in: query
        description: If specified, only immediate children of a given parentIdx are returned. If not specified, all hierarchy relations are returned. It accepts only internal identifiers which are generally integer values with no prefix.
        schema:
          type: integer
      - name: childId
        in: query
        description: 'If specified, only immediate parents of a given childId are returned. If not specified, all hierarchy relations are returned. ChildId could be either external Id (prefixed by `id:`), runtime internal Id (prefixed by `idx:`). If a value is passed without a prefix then it is evaluated based on the following precedence : external Id, internal Id.'
        schema:
          type: string
      - name: childIdx
        in: query
        description: If specified, only immediate parents of a given childIdx are returned. If not specified, all hierarchy relations are returned. It accepts only internal identifiers which are generally integer values with no prefix.
        schema:
          type: integer
      - name: include
        in: query
        description: The identifier(external or internal) to be returned in the response. By default response will contain external Id (include=id format). If include=idx then internal Ids are returned and external Ids are omitted. If include=idx,id then both internal and external format identifiers will be returned.
        schema:
          type: array
          items:
            type: string
            enum:
            - id
            - idx
            - idc
        explode: false
      responses:
        '200':
          description: Success
          headers:
            X-ModelVersionId:
              schema:
                type: string
              description: The actual model version identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HierarchyRelationsResponse'
        '401':
          description: Authorization information is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: 'Input validation Error: value is missing/null/invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: User has no permissions to execute this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The specified modelId/versionId/type was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Session is invalid/Gateway timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    HierarchyRelationsResponse:
      type: object
      required:
      - items
      - total
      - count
      - offset
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/HierarchyRelation'
          description: The Collection of HierarchyRelation items.
        offset:
          type: integer
          description: The offset of the first item returned in this page.
        offsetNext:
          type: integer
          description: The first item of the next page. If null, then this is the last page in the result set. If not null, then this value must be passed in the `offset` query parameter to fetch the next page.
        total:
          type: integer
          description: The total number of items in the result set.
        count:
          type: integer
          description: The number of items on the current page.
      description: A response containing a collection of hierarchy relations.
    HierarchyRelation:
      type: object
      properties:
        parentId:
          type: string
          description: The Parent Id (external identifier) in the hierarchy structure. In case of the root hierarchy relations the value is `root`.
        childId:
          type: string
          description: The Child Id (external identifier) in the hierarchy structure.
        parentIdc:
          type: string
          description: The connect Parent Id in the hierarchy structure. In case of the root hierarchy relations the value is `root`.
        childIdc:
          type: string
          description: The connect Child Id in the hierarchy structure.
        parentIdx:
          type: integer
          description: The Parent Id (internal identifier) in the hierarchy structure. In case of the root hierarchy relations the value is `-1`.
        childIdx:
          type: integer
          description: The Child Id (internal identifier) in the hierarchy structure.
        type:
          type: string
          description: The hierarchy type it belongs to.
      description: A hierarchy relation of a given type between two model entities.
    ErrorResponse:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          minLength: 1
          description: The textual error code.
        message:
          type: string
          description: The error message.
      description: The error response body. Defines a standard for reporting errors to the client.
  securitySchemes:
    Bearer:
      type: http
      description: The Trimble ID access token.
      scheme: bearer
      bearerFormat: JWT