Trimble Issues Configuration API

The Issues Configuration API from Trimble — 5 operation(s) for issues configuration.

GitHub OpenAPI

Operations 7

GET /context/{contextId}/issues/configuration Get Issue configuration for the context #
PUT /context/{contextId}/issues/configuration Update Issue configuration for the context #
GET /context/{contextId}/issues/icons List custom icons within a specified context #
POST /context/{contextId}/issues/icons Create custom icon for a context #
GET /issues/icons/defaults List default icons #
GET /issues/configuration/defaults Get default issue configuration #
DELETE /context/{contextId}/issues/icons/{iconId} Delete an icon for a context #

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-issues-configuration-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-issues-configuration-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Issue Management Service Issues Configuration API
  description: '# Issue Management Service (IMS)


    REST API for creating, reading, updating, and deleting issues attached to a Trimble Connect context (project or file). Issues support rich access-control, capability discovery via `_actions`, and sync primitives (snapshot / changes feed).


    ## Context Types


    Every request targets a **context** identified by a TRN string passed as `{contextId}`. Two context types are supported and they have different ACL behaviours:


    | Context type | TRN pattern | ACL model |

    |---|---|---|

    | **Project** | `trn:2:tc:{region}:projects:{projectId}` | Full viewer model — ADMIN, creator, assignee, and explicit ACL holders. Plain project members without an explicit ACL grant have no automatic access. |

    | **File** | `trn:2:tc:{region}:projects:{projectId}:files:{fileId}` | Open access — any user who can access the file receives all issue actions **except** `issue:UpdatePermissions`. The `/permissions` endpoints return `404` for file contexts. |


    ## Capability Discovery — `_actions`


    All issue endpoints accept an optional `?fields=_actions` query parameter. When requested, the response includes a `_actions` array listing the wire-format action strings the authenticated caller is **currently authorised** to perform on that issue. Clients **must** check `_actions` before showing mutation controls rather than hard-coding role assumptions.


    Available action values:


    | Wire value | Meaning |

    |---|---|

    | `issue:Read` | View issue details |

    | `issue:Update` | Edit issue fields |

    | `issue:Delete` | Delete the issue |

    | `issue:AddLinks` | Create links on this issue |

    | `issue:DeleteLinks` | Remove links from this issue |

    | `issue:ReadLinks` | List links attached to this issue |

    | `issue:UpdatePermissions` | Call `PATCH /permissions` on this issue (project context only) |


    ## ACL Buckets


    Issue permissions are stored as ACL buckets. The API surface exposes **two** buckets only (`"full"` is internal and rejected on PATCH):


    | Bucket key | Actions granted | Notes |

    |---|---|---|

    | `"edit"` | `issue:Read`, `issue:Update`, `issue:AddLinks`, `issue:DeleteLinks`, `issue:ReadLinks`, `issue:UpdatePermissions` | Does **not** include `issue:Delete` |

    | `"view"` | `issue:Read`, `issue:ReadLinks` | Read-only access |


    The inherited ACL floor is: **creator → edit**, **assignees → edit**. Effective access = `max(inherited floor, explicit grant)` — explicit ACL can only **elevate**, never reduce, an actor''s access.


    ## ACL Permission Model (Project Context)


    - Project ADMIN → all 7 actions

    - Issue creator → all 7 actions

    - Issue assignee → `edit` bucket (no `issue:Delete`)

    - `tc-groups:*` in `acl.view` → VIEW bucket for all project members

    - Actors with explicit `"edit"` ACL entry → `edit` bucket

    - Actors with explicit `"view"` ACL entry → `view` bucket

    - No match → **empty actions** (denied; endpoints return 403)

    - Effective = `max(inherited floor, explicit grant)` — cannot downgrade


    When a new project is created, `shareNewIssuesWithAllProjectMembers` defaults to `true`, causing `tc-groups:*` to be auto-added to the `view` bucket of every newly created issue. Disabling this flag makes issues **private by default** (visible only to ADMIN, creator, and assignees).


    ## Identity Formats


    ACL identity strings must match `^(users:|tc-groups:).+$`:


    | Format | Example | Meaning |

    |---|---|---|

    | `users:{tiduuid}` | `users:abc123` | Specific Trimble Identity user |

    | `tc-groups:{groupId}` | `tc-groups:grp456` | Specific Connect project group |

    | `tc-groups:*` | `tc-groups:*` | All project members (wildcard) |


    A maximum of **100 identities** across all buckets combined is enforced on PATCH.'
  contact:
    name: Trimble Connect Platform Team
  version: v1
servers:
- url: https://app.connect.trimble.com/v1/issues
  description: Prod US1 (primary)
- url: https://app21.connect.trimble.com/v1/issues
  description: Prod EU1
- url: https://app22.connect.trimble.com/v1/issues
  description: Prod UK1
- url: https://app31.connect.trimble.com/v1/issues
  description: Prod AP1
- url: https://app32.connect.trimble.com/v1/issues
  description: Prod AP2
security:
- bearerAuth: []
tags:
- name: Issues Configuration
paths:
  /context/{contextId}/issues/configuration:
    get:
      tags:
      - Issues Configuration
      summary: Get Issue configuration for the context
      description: Retrieve the configuration settings for a specified context. API will return default configuration if no configuration is set for the context.
      operationId: getConfiguration
      parameters:
      - name: contextId
        in: path
        description: The unique identifier of the context in TRN format (trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId} for project context or trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId}:files:{fileId} for file context).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Issue configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
    put:
      tags:
      - Issues Configuration
      summary: Update Issue configuration for the context
      description: Update the configuration settings for a specified context. Note that custom icons must be stored separately using the storeIcon API and referred here via iconId.
      operationId: updateConfiguration
      parameters:
      - name: contextId
        in: path
        description: The unique identifier of the context in TRN format (trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId} for project context or trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId}:files:{fileId} for file context).
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationRequest'
        required: true
      responses:
        '200':
          description: Issue configuration updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigurationResponse'
  /context/{contextId}/issues/icons:
    get:
      tags:
      - Issues Configuration
      summary: List custom icons within a specified context
      description: Retrieve a list of custom icons for a specified context. Maximum page size limit is 200.
      operationId: listIcons
      parameters:
      - name: contextId
        in: path
        description: The unique identifier of the context in TRN format (trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId} for project context or trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId}:files:{fileId} for file context).
        required: true
        schema:
          type: string
      - name: pageSize
        in: query
        description: The maximum number of icons to return (between 1 and 200)
        required: false
        schema:
          type: integer
          format: int32
          default: 200
        example: 10
      - name: skipToken
        in: query
        description: Token for retrieving the next page of results. A cursor pointing to the last known change of the objects. `skipToken` format is implementation detail of the service and must not be used or modified by client. The client should only pass the skipToken as it is received in Response.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Icons listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResponse'
    post:
      tags:
      - Issues Configuration
      summary: Create custom icon for a context
      description: Create a new custom icon for a specified context. Maximum of only 200 icons can be stored per context.
      operationId: createIcon
      parameters:
      - name: contextId
        in: path
        description: The unique identifier of the context in TRN format (trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId} for project context or trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId}:files:{fileId} for file context).
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IconRequest'
        required: true
      responses:
        '201':
          description: Icon stored successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IconsResponse'
  /issues/icons/defaults:
    get:
      tags:
      - Issues Configuration
      summary: List default icons
      description: Retrieve a list of default icons supported by the service. These icons cannot be deleted or modified. Pagination is not implemented as the default icon set is small.
      operationId: getDefaultIcons
      responses:
        '200':
          description: A list of default icons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultIconsResponse'
  /issues/configuration/defaults:
    get:
      tags:
      - Issues Configuration
      summary: Get default issue configuration
      description: Retrieve the default configuration settings
      operationId: getDefaultConfiguration
      responses:
        '200':
          description: Default issue configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultConfigurationResponse'
  /context/{contextId}/issues/icons/{iconId}:
    delete:
      tags:
      - Issues Configuration
      summary: Delete an icon for a context
      description: Delete a specific icon from the given context.
      operationId: deleteIconById
      parameters:
      - name: contextId
        in: path
        description: The unique identifier of the context in TRN format (trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId} for project context or trn:2:tc:{us|eu|eu-gb|ap|ap-au}:projects:{projectId}:files:{fileId} for file context).
        required: true
        schema:
          type: string
      - name: iconId
        in: path
        description: The unique identifier of the icon
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Icon deleted successfully
components:
  schemas:
    PageReference:
      type: object
      properties:
        href:
          type: string
    DefaultIconsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/IconsDetails'
    IconsResponse:
      type: object
      properties:
        id:
          type: string
        contextId:
          type: string
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedBy:
          type: string
        updatedAt:
          type: string
          format: date-time
        iconContent:
          type: string
      required:
      - contextId
      - createdAt
      - createdBy
      - iconContent
      - id
      - updatedAt
      - updatedBy
    PageLink:
      type: object
      properties:
        first:
          $ref: '#/components/schemas/PageReference'
        self:
          $ref: '#/components/schemas/PageReference'
        next:
          $ref: '#/components/schemas/PageReference'
    ConfigurationResponse:
      type: object
      properties:
        contextId:
          type: string
        type:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        status:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        priority:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        stage:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        snippetType:
          type: array
          description: snippet types supported by this configuration, no effect added for bcf compatibility
          items:
            type: string
        serverAssignedIdPrefix:
          type: string
        updatedBy:
          type: string
        updatedAt:
          type: string
          format: date-time
        shareNewIssuesWithAllProjectMembers:
          type: boolean
          description: When true, new issues created in this project context automatically grant view access to all project members via the ACL. Defaults to true for project contexts. Always false for file contexts.
        _actions:
          type: array
          items:
            type: string
            enum:
            - issue-config:read
            - issue-config:update
            - icon:create
            - icon:read
            - icon:delete
            - issue:create
      required:
      - contextId
    DefaultConfigurationResponse:
      type: object
      properties:
        type:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        status:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        priority:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        stage:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        snippetType:
          type: array
          description: snippet types supported by this configuration, no effect added for bcf compatibility
          items:
            type: string
        serverAssignedIdPrefix:
          type: string
        updatedBy:
          type: string
        updatedAt:
          type: string
          format: date-time
        shareNewIssuesWithAllProjectMembers:
          type: boolean
          description: When true, new issues created in this project context automatically grant view access to all project members via the ACL. Defaults to true for project contexts. Always false for file contexts.
    ConfigurationRequest:
      type: object
      properties:
        type:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        status:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        priority:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        stage:
          type: array
          items:
            $ref: '#/components/schemas/ConfigurationDetails'
        serverAssignedIdPrefix:
          type: string
          description: Prefix for server assigned IDs, exactly 5 characters containing only letters and underscores, e.g., 'ISSUE'.
          pattern: ^[\p{L}_]{5}$
        shareNewIssuesWithAllProjectMembers:
          type: boolean
          description: When true, new issues created in this project context will automatically grant view access to all project members via the ACL. Default is true for project contexts. Always false for file contexts — setting this field has no effect for file contexts.
      required:
      - serverAssignedIdPrefix
    ConfigurationDetails:
      type: object
      properties:
        name:
          type: string
        color:
          type: string
        iconId:
          type: string
        visible:
          type: boolean
        default:
          type: boolean
    PagedResponse:
      type: object
      properties:
        items:
          type: array
          items: {}
        links:
          $ref: '#/components/schemas/PageLink'
    IconRequest:
      type: object
      properties:
        iconContent:
          type: string
          description: 'Base64-encoded image string representing the icon content. Expected format: ''data:image/png;base64,iVBORw0KG...'''
      required:
      - iconContent
    IconsDetails:
      type: object
      properties:
        id:
          type: string
        iconContent:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      description: 'Trimble Identity JWT bearer token. Pass as ''Authorization: Bearer {token}''.'
      scheme: bearer
      bearerFormat: JWT