Trimble Issues API

openapi: 3.2.0
info:
  title: Issue Management Service Issues 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:


# --- truncated at 32 KB (77 KB total) ---
# Full source: https://artifacts.apis.io/trimble/openapi/trimble-issues-api-openapi.yml