The Clash Detection API allows you to manage clash detection suppression rules, tests, runs, and results. You can run tests and monitor the progress.

clash-detection

---

Retrieves details of a clash detection run for the run specified by the run id.

- Discover run ids by calling [GET /clashdetection/runs](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-runs/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-clashdetection-run

OAuth access token with scope `clashdetection:read`

Authorization

Setting to `application/vnd.bentley.itwin-platform.v1+json` is recommended.

Accept

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.

application/json;InvalidAuthorizationScheme

This response indicates that the specified run was not found.

This response indicates that the user has sent too many requests in a given amount of time.

The number of requests exceeds the rate-limit for the client subscription.

retry-after

clash-detection-run

string

The display name of the run is the test name and execution date/time.

displayName

The date/time when the test was executed.

executedDateTime

date-time

count

The name of the user that started the run.

userName

The status of the clash detection run. One of 'queued', 'started', 'completed', 'failed', 'downloadingIModel', 'storingResults', 'inProgress', 'completedToLimit', 'cancelled', 'invalidSuppressionRules', 'completedWithElementLoadErrors'

status

resultId

The links to get the result and test details.

_links

clash-detection-run-links

Clash Detection Run

result

Link

test

Clash Detection Run Links

href

Error

One of a server-defined set of error codes.

code

A human-readable representation of the error.

message

target

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.

ErrorResponse

error

Error Response

---

Gets the clash detection result details for the specified result id.

- Discover result ids by calling [GET /clashdetection/runs](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-runs/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-clashdetection-result

This response indicates that the specified result was not found.

---

Deletes the clash detection run for the specified run id.

- Discover run ids by calling [GET /clashdetection/runs](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-runs/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

delete-clashdetection-run

OAuth access token with scope `clashdetection:modify`

Indicates that the run was successfully deleted. There is no response body in this case.

---

Retrieves a list of Clash Detection runs for the project specified by the project id.

### Notes

The Prefer header can be used to specify how much clash detection run metadata is desired

- "return=minimal" (default) - returns the minimum clash detection run metadata

- "return=representation" - returns the full clash detection run metadata

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-clashdetection-runs

The project id of the project from which to retrieve the clash detection runs.

projectId

Optional.  Select preferred representation.

Prefer

This response indicates that the specified project was not found.

---

Runs a Clash Detection test for the specified test id and returns the run id. The maximum number of clashes may be specified with the resultsLimit parameter in the request body. If none is specified, the default is 100,000.

- This API has a rate limit of 6 API calls per second.  If an application exceeds the rate limit it will receive an HTTP error code 429 "Too Many Requests". The error response includes a Retry-After header that indicates how long clients should wait before retrying.

- A link is included to retrieve the run status as the agent job completes asynchronously.

- Discover test ids by calling [GET /clashdetection/tests](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-tests/)

- Discover iModel ids by calling [GET /imodels](/api-groups/data-management/apis/imodels/operations/get-project-imodels/)

- Discover named version ids by calling [GET /imodels/{id}/namedversions](/api-groups/data-management/apis/imodels/operations/get-imodel-named-versions/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

run-clashdetection-test

This response indicates that the specified test was not found.

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax)

---

Creates a clash detection suppression rule for the specified criteria and returns the rule id.

- Discover rule template ids by calling [GET /clashdetection/suppressionRuleTemplates](/api-groups/validation/apis/clash-detection/operations/get-suppression-rule-templates/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

create-clashdetection-suppression-rule

---

Deletes the clash detection suppression rule for the specified test id.

- Discover rule ids by calling [GET /clashdetection/suppressionrules](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-suppression-rules/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


delete-clashdetection-suppression-rule

Indicates that the suppression rule was successfully deleted. There is no response body in this case.

This response indicates that the specified suppression rule was not found.

---

Gets the clash detection suppression rule details for the specified rule id.

- Discover rule ids by calling [GET /clashdetection/r](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-suppression-rules/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-clashdetection-suppression-rule

Optional. Include user metadata when true.

Include-User-Metadata

This response indicates that the specified rule was not found.

---

Retrieves a list of clash detection suppression rules for the project specified by the project id.

### Notes

The Prefer header can be used to specify how much rule metadata is desired

- "return=minimal" (default) - returns the minimum suppression rule metadata

- "return=representation" - returns the full suppression rule metadata

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-clashdetection-suppression-rules

The project id of the project from which to retrieve clash detection suppression rules.

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.

continuationToken

The number of rules to get in each page. Max 50, but 10 is the default if this parameter is not included.

$top

Optional. Select preferred representation.

---

Retrieves a list of Clash Detection suppression rule templates for the project specified by the project id.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-suppression-rule-templates

The id of the project associated with the suppression rule templates.

The number of rule templates to get in each page. Max 50, but 15 is the default if this parameter is not included.

---

Updates a clash detection suppression rule for the specified criteria and returns the id of the successfully updated rule.

- Discover rule ids by calling [GET /clashdetection/suppressionrules](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-suppression-rules/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

update-clashdetection-suppression-rule

---

Creates clash detection test for the specified criteria and returns the test id.

- Discover rule ids by calling [GET /clashdetection/suppressionrules](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-suppression-rules/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

create-clashdetection-tests

---

Deletes the clash detection test for the specified test id.

- Discover test ids by calling [GET /clashdetection/tests](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-tests/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


delete-clashdetection-test

Indicates that the test was successfully deleted. There is no response body in this case.

---

Gets the clash detection test details for the specified test id.

- Discover test ids by calling [GET /clashdetection/tests](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-tests/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-clashdetection-test

---

Retrieves a list of Clash Detection tests for the project specified by the project id.

### Notes

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-clashdetection-tests

The project id of the project from which to retrieve clash detection tests.

The number of tests to get in each page. Max 50, but 10 is the default if this parameter is not included.

---

Updates a clash detection test for the specified criteria and returns the id of the successfully updated test.

- Discover test ids by calling [GET /clashdetection/tests](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-tests/)

- Discover rule ids by calling [GET /clashdetection/suppressionrules](/api-groups/validation/apis/clash-detection/operations/get-clashdetection-suppression-rules/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

update-clashdetection-test

---

Extracts the models and categories for the latest named version of an iModel.

- A status of 202 is returned if the extraction job was successfully started.  The job completes asynchronously so the user can periodically call [GET /clashdetection/modelsAndCategories/imodels](/api-groups/data-management/apis/clash-detection/operations/get-models-and-categories/) until a status of 'available' is returned with the response.

- Discover iModel ids by calling [GET /imodels](/api-groups/data-management/apis/imodels/operations/get-project-imodels/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

extract-models-and-categories

Location

This response indicates that the specified iModel or project was not found.

---

Gets the models and categories for the named version of an iModel. This request relies on a previous call to start the extraction job on an agent. Since this extraction completes asynchronously, the user can send this request periodically until a status of 'available' is returned in the response.

- Discover iModel ids by calling [GET /imodels](/api-groups/data-management/apis/imodels/operations/get-project-imodels/)

- Extract iModel models and categories by calling [POST /clashdetection/modelsAndCategories/imodels](/api-groups/validation/apis/clash-detection/operations/extract-models-and-categories/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-models-and-categories

The id of the project containing the iModel from which to retrieve the models and categories.

---

Extracts the schemas for the latest named version of an iModel.

- A status of 202 is returned if the schema extraction was successfully started.  The job completes asynchronously so the user can periodically call [GET /clashdetection/schemas/imodels](/api-groups/data-management/apis/clash-detection/operations/get-schema-info/) until a status of 'available' is returned with the response.

- Discover iModel ids by calling [GET /imodels](/api-groups/data-management/apis/imodels/operations/get-project-imodels/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

extract-schema-info

---

Gets the schemas for the latest named version of an iModel. This request relies on a previous call to start schema extraction on an agent. Since this extraction completes asynchronously, the user can send this request periodically until a status of 'available' is returned in the response.

- Discover iModel ids by calling [GET /imodels](/api-groups/data-management/apis/imodels/operations/get-project-imodels/)

- Extract iModel schemas by calling [POST /clashdetection/schemas/imodels](/api-groups/validation/apis/clash-detection/operations/extract-schema-info/)

### Authentication

Requires `Authorization` header with valid Bearer token for scope `clashdetection:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-schema-info

The id of the project containing the iModel from which to retrieve the schema info.

Get clash detection run - Clash Detection | iTwin Platform

Walk-through of the creation and usage of suppression rules for clash detection tests.

Clash Suppression Rules Basics

Walk-through of the clash detection lifecycle-creating, running and retrieving the results.

Clash Test Basics

Walk-through of retrieving and understanding basic model information needed for various validation functions.

Clash Detection Runs

Authentication

Request

Request parameters

Request headers

Response

Response 200 OK

Response 401 Unauthorized

Response 404 Not Found

Response 429 Too many requests

Definitions

Clash Detection Run

Clash Detection Run Links

Link

Error

Error Response