Retrieves a list of issues for the iTwin or project with the given ID. If the Prefer header is omitted, or set to "return=minimal", this only returns basic info about each issue--its ID, display name, type, subject, and whether it is in an Open, Closed, or Draft state. Setting the Prefer header to "return=representation" will return more data. Use the "Get Issue Details" endpoint to see full information about a particular issue.
Note that the 'iTwinId' query string parameter is required. It must be a valid project GUID to get issues from. Existing clients can continue to use the 'projectId' paramater as an alias for 'iTwinId'.
Permissions
To use this endpoint, the user is required to have the Forms View permission (Forms_ViewAccess) for the iTwin, or for some issues' associated form definitions if form definition security is specified. (Having any other level of Forms permission for an issue automatically grants the View permission as well for that issue. If a user does not have permission to view a particular issue, it will be silently excluded from the list.)
Authentication
Requires Authorization header with valid Bearer token for scope itwin-platform.
For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.
Request parameters
The type of issue data to get. Omit to get all types.
The number of issues to get in each page. Max 50, which is also the default if this parameter is not included.
Parameter that enables continuing to the next page of the previous paged query. This must be passed exactly as it is in the response body's _links.next property. If this is specified and $top is omitted, the next page will be the same size as the previous page.
Required. The GUID of the iTwin or project to get issues for. (Note: projectId is also accepted as an alias for this parameter.)
If set, will only retrieve issues in the specified workflow state (Open, Closed, or Draft)
Request headers
Gets whether to return only a summary of each item (return=minimal) or full properties of each item (return=representation). Default is return=minimal
OAuth access token with itwin-platform scope
Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.
Response 200 OK
OK
{ "issues": [{ "id": "00000000-0000-0000-0000-0000000000000", "displayName": "CLA-00001", "type": "Clash", "state": "Closed", "subject": "Colliding beams" }, { "id": "00000000-0000-0000-0000-0000000000001", "displayName": "RFI-00001", "type": "RFI", "state": "Open", "subject": "Which Material?" } ], "_links": { "self": { "href": "https://api.bentley.com/issues/?projectId=30273027-1111-2222-3333-3d7d6b02dc46&$top=2" }, "next": { "href": "https://api.bentley.com/issues/?projectId=30273027-1111-2222-3333-3d7d6b02dc46&continuationToken=eyJ0b3A999990" } } }
Response 401 Unauthorized
This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.
{ "error": { "code": "HeaderNotFound", "message": "Header Authorization was not found in the request. Access denied." } }
Response 404 Not Found
This response indicates that the issue with the specified ID does not exist or is inaccessible to the user due to insufficient permissions. (For security reasons, the response will not differ between inaccessible and missing issues.)
{ "error": { "code": "ProjectNotFound", "message": "Requested project is not available.", "target": "projectId" } }
Response 422 Unprocessable Entity
This response indicates that there is a problem with the format of the URL. Most likely problem: The 'projectId' parameter is missing or not a valid GUID.
{ "error": { "code": "InvalidIssueRequest", "message": "Cannot retrieve issues.", "details": [{ "code": "MissingRequiredParameter", "message": "The 'projectId' query parameter must be provided.", "target": "projectId" }] } }
Response 429 Too many requests
This response indicates that the user has sent too many requests in a given amount of time.
{ "error": { "code": "TooManyRequests", "message": "More requests were received than the subscription rate-limit allows." } }
Response headers
The number of requests exceeds the rate-limit for the client subscription.
Issues List (Prefer return=minimal)
Issues List (Prefer return=representation)
Issue Summary state
Indicates whether the issue's current workflow status is an Open, Closed, or Draft status.
Issue Summary
The issue's unique ID. Can be used to query for issue details with the Get Issue Details endpoint.
Name that should be used to display this issue to users.
Read-only. Describes which domain of work the issue involves, which determines what applications will show it. Automatically set based on the form definition (referenced by formId) that was used to create the issue.
Indicates whether the issue's current workflow status is an Open, Closed, or Draft status.
A user-provided short description of the issue, if it exists. Can be shown alongside DisplayName to display the issue to users in a UI.
Issue Representation
Contains the full data of this issue, except formId, for inclusion in a list. Any property that was never set on the issue will be omitted from the response.
Unique identifier for this instance. Read-only.
Name that should be used to show this issue in a list of issues in the UI. This is read-only. Project managers can configure how this is generated; usually, it will be the value of another property.
Brief title/description of the issue.
Detailed description of the issue.
Read-only. Describes which domain of work the issue involves, which determines what applications will show it. Automatically set based on the form definition that was used to create the issue.
An human-readable identifier for the issue, consisting of an alphanumeric prefix (that can be configured by the project administrator) followed by an auto-incrementing number. Read-only.
The date by which an action should be taken on this issue. Applications will use this to determine whether an issue is near due or overdue.
The current workflow status the issue is in right now.
Indicates whether the issue's status is an Open, Closed, or Draft status. This property is read-only.
A RBG hexadecimal color string, e.g. #ff0000. Read-only. If set, this gives a hint for how to highlight the issue in a list of issues based on its current workflow status.
For cases when an issue is assigned to multiple people and/or roles, this lists all of them rather than just the primary assignee.
The display name of the user who originally created this issue. Read-only.
The date and time when this issue was originally created. Read-only.
The display name of the user who most recently made a change to this issue. Read-only.
The date and time when this issue was most recently edited. Read-only.
Origin info. An object linking the issue to an entity outside the Issues service, such as a file in Storage or an element in an iModel, that the issue was created to pertain to.
Origin info. Describes a rectangular-prism area of the model that the issue pertains to.
Origin info. Describes a point in 3D space that the issue pertains to. May or may not be based on the position of a particular element.
Origin info. Describes a view of the model that shows the relevant elements that the issue pertains to.
The date and time represented in the model where the issue occurred (if in a 4D model).
Contains all issue-type-specific and user-defined properties that were set on this issue. Properties set here may be strings, numbers, booleans, arrays, or objects, depending on how the project's administrator defined them in the Form Designer.
Links to related entities, if applicable.
Primary Assignee
An object describing the primary user or role assigned to an issue.
The GUID identifying the user or role.
The role's name, or the user's given name and surname, as it should be displayed in an application.
Secondary Assignee
An object describing one of potentially several users or roles assigned to an issue.
The GUID identifying the user or role.
The role's name, or the user's given name and surname, as it should be displayed in an application.
If true, this is a role; otherwise, it is an individual user.
bounding-box
Origin info. Describes a rectangular-prism-shaped region in a 3D model that the issue pertains to.
Model Pin
Origin info. Associates an issue with a single point in a model that does not necessarily correspond to a model element.
String describing the relevance of the pin's location.
Model View
Origin info. Describes the view that was visible when the issue was created.
The ID of a saved view showing the issue.
point3D
camera
Endpoint of a vector from the origin that determines which direction appears as upwards in the view.
Determines the zoom level of the camera, i.e. how much to multiply 1 distance unit in the view by to get the actual distance in meters in the model. Either this or fieldOfView should be specified, but not both.
Determines the number of degrees in the circular arc around the camera's position that is visible in the view. Either this or viewToWorldScale should be specified, but not both.
location
Origin info. The geographical location the issue pertains to.
The degrees latitude of the issue's location. North: positive, south: negative.
The degrees longitude of the issues location. East: positive, west: negative.
The geographical elevation above/below sea level. Units for this property are not standardized, so an application should not make assumptions about this property's value set by other applications unless that other application's units are known.
A string describing the significance of this location.
source-entity-file
Represents a file in Storage about which an issue was created.
ID used to identify the file in the Storage API.
ID of the folder containing the file in the Storage API.
Name of the file, including extension.
source-entity-i-model-element
Represents an element in an iModel about which an issue was created.
ID of the iModel containing the element, as it exists in the iModels API.
ID of the element. Can be a hexadecimal numeric string (space-separated to include multiple elements) or a presentation key.
ID of the changeset where the issue was created.
Name of the model.
source-entity-links-file
Links to retrieve the related file, and the folder that contains it, from the Storage API.
source-entity-links-i-model-element
Links to retrieve the related element's specific changeset, or iModel in general, from the iModels API.
Dynamic Object
An object whose properties can vary depending on user customization within the project.
Forward Only Paging Links
URLs for redoing the current request or getting the next page of results, if applicable. Links to the previous page are not available.
link
DetailedError
Contains error information and an array of more specific errors.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
Detailed Error Response
Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.
Error
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
Error Response
Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.
Was this page helpful?