itwins

---

Returns the primary Account for the calling user. 

When a user creates a new iTwin, it will be created in the primary Account unless specified otherwise.

If a user is associated with an Organization, that user will be able to query for any Account iTwin owned by their Organization. If the Organization has more than one Account then the MyPrimaryAccount endpoint will return only the primary Account for that Organization. Other Accounts can be queried using the [Get My iTwins](https://developer.bentley.com/apis/itwins/operations/get-my-itwins/) endpoint with the subClass=Account parameter.

If a user is not associated with an Organization, then a single Account iTwin will be created for the user. The MyPrimaryAccount endpoint will return that Account.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-my-primary-account

OAuth access token with scope `itwins: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 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

Minimal representation of a iTwin that contains only id, class, subClass, type, number and displayName.

iTwin-summary

string

The [Class](https://developer.bentley.com/apis/itwins/overview/#itwinclassesandsubclasses) of your iTwin.

class

The [subClass](https://developer.bentley.com/apis/itwins/overview/#itwinclassesandsubclasses) your iTwin.

subClass

An open ended property to better define your iTwin's Type.

type

A unique number or code for the iTwin. This is the value that uniquely identifies the iTwin within your organization.

number

displayName

iTwin (summary)

Contains error information and an optional array of more specific errors.

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

---

Add an iTwin to the calling user's favorites list.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the specified iTwin. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---


add-itwin-to-my-favorites

OAuth access token with scope `itwins:modify`

The user has insufficient permissions for the requested operation.

This response indicates that specified iTwin was not found.

---

Retrieves a list of favorite iTwins for the calling user.

### Inactive iTwins
iTwins with *status=Inactive* are not returned by default. This improves query performance and reduces clutter in user interfaces by filtering out unused iTwins. 
You should still provide a way for users to see their Inactive iTwins if they request them. In the API, you can do this by setting the status parameter or by using the includeInactive parameter.

If *status=Inactive*, the API will return only Inactive iTwins.  
If *includeInactive=true*, the API will return all iTwins (Active, Trial and Inactive).

The includeInactive parameter is optional and defaults to false. A 422 error will be returned if you try to use a status parameter at the same time as the includeInactive parameter.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

Any user can call this endpoint. It will only return iTwins that the user is a member of. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---


get-my-favorite-itwins

Specify a particular [subClass](https://developer.bentley.com/apis/itwins/overview/#itwinclassesandsubclasses) that you wish to query on.

Specify a particular status that you wish to query on.

status

Specify a particular type that you wish to query on.

The [$top](https://www.odata.org/getting-started/basic-tutorial/#topskip) system query option requests the number of items in the queried collection to be included in the result.

$top

The [$skip](https://www.odata.org/getting-started/basic-tutorial/#topskip) query option requests the number of items in the queried collection that are to be skipped and not included in the result.

$skip

By default, the query will not return Inactive iTwins unless you set includeInactive=true. Cannot be used at the same time as the status parameter.

includeInactive

Indicates a level of details in the response. Valid values are 'return=representation' or 'return=minimal'. The default is 'return=minimal'.

Prefer

---

Remove an iTwin from the calling user's favorites list.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the specified iTwin. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---


remove-itwin-from-my-favorites

---

Deletes the image assoicated with the specified iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization
The user must have the `itwins_modify` permission on the iTwin in order to delete the image associated with the iTwin.

An Organization Administrator can modify any iTwins owned by their Organization. This allows Organization Administrators to delete the iTwin image.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin.
Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be [invited] (https://developer.bentley.com/apis/access-control/operations/add-iTwin-members/) to collaborate on the iTwin.


An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---

delete-itwin-image

iTwinId

This response indicates that iTwin with specified ID was not found.

---

Gets the image metadata for the specified iTwin. 

The metadata will contain the name of the image and a URL for downloading the image. The name of the image is unique and will only change if the image changes. It can be used as a long term cache key to determine if you have already downloaded the image. The URLs will be valid for a minimum of 1 hour.

This API is used to get a link to the small image and the original uploaded image. To make it easier to use the small image as a thumbnail, the small image link is also included as a property on every iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the specified iTwin. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---

get-itwin-image

iTwin ID associated with the retrieved image.

This response indicates that the specified iTwin was not found.

---

Uploads an image for the specified iTwin. Maximum supported size is 5 megabytes.

A small, thumbnail image will be automatically generated based on the uploaded image. For convenience, the link to this thumbnail is also returned in the 'image' property on the iTwin.

Upload the image by adding a binary stream to the request body. You must specify the Content-Type header as either image/png or image/jpeg.

 C# Example:
 ```
 var stream = File.OpenRead("c:/test.jpg");
 var streamContent = new StreamContent(stream);
 streamContent.Headers.ContentType = new MediaTypeHeaderValue ("image/jpeg");
 var response = await httpClient.PutAsync($"{iTwinId}/image", streamContent);
 ```
		
### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization
The user must have the `itwins_modify` permission on the iTwin in order to add an image to the iTwin.

An Organization Administrator can modify any iTwins owned by their Organization. This allows Organization Administrators to upload an iTwin image.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin.
Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be [invited] (https://developer.bentley.com/apis/access-control/operations/add-iTwin-members/) to collaborate on the iTwin.


An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---

upload-itwin-image

Indicates request body content type. Must be image/png or image/jpeg.

Content-Type

This response indicates that one of the associated entities could not be found.

Indicates that the file the user attempted to upload is above the maximum size.

Invalid request to add iTwin image.  Review the 'Field Values' section near the top of this page.

---

Create a new iTwin. 

The user that creates the iTwin will automatically be given the `iTwin owner` role on the iTwin. This will give that user full access to the iTwin, including the ability to create new child iTwins under the iTwin they are creating. After the iTwin is created, the `iTwin owner` role can be removed from the user or granted to other users.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization
The user must have the `itwins_create` permission on the parent iTwin specified in the request. If there is no parent iTwin in the request then the user must have the `itwins_create` permission on the [Account iTwin] (https://developer.bentley.com/apis/iTwins/overview/#account).

An Organization Administrator can create iTwins for their Organization.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin.
Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be [invited] (https://developer.bentley.com/apis/access-control/operations/add-iTwin-members/) to collaborate on the iTwin.


An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


create-itwin

Invalid request to create a iTwin.  Review the 'Field Values' section near the top of this page.

---

Delete the specified iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization
Only an Organization Administrator can delete iTwins owned by their Organization.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin.
Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be [invited] (https://developer.bentley.com/apis/access-control/operations/add-iTwin-members/) to collaborate on the iTwin.


An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


delete-itwin

---

Gets the metadata of the specified iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the specified iTwin. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---


get-itwin

---

Gets the Account for the specified iTwin.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the specified iTwin. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---


get-itwin-account

---

Retrieves a list of iTwins that the calling user is a member of. 

### Inactive iTwins
iTwins with *status=Inactive* are not returned by default. This improves query performance and reduces clutter in user interfaces by filtering out unused iTwins. 
You should still provide a way for users to see their Inactive iTwins if they request them. In the API, you can do this by setting the status parameter or by using the includeInactive parameter.

If *status=Inactive*, the API will return only Inactive iTwins.  
If *includeInactive=true*, the API will return all iTwins (Active, Trial and Inactive).

The includeInactive parameter is optional and defaults to false. A 422 error will be returned if you try to use a status parameter at the same time as the includeInactive parameter.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

Any user can call this endpoint. It will only return iTwins that the user is a member of. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---


get-my-itwins

Find all iTwins with the exact number specified. Cannot be used at the same time as the $search parameter.

Find all iTwins with the exact displayName specified. Cannot be used at the same time as the $search parameter.

Find all iTwins that are children of the specified parentId.

parentId

Find all iTwins that are owned by the specified iTwinAccountId.

iTwinAccountId

Find all iTwins that have the search string anywhere in the number or displayName. Cannot be used at the same time as the number or displayName parameters.

$search

---

Update the specified iTwin.

For updates, all properties are optional. The request payload should only contain the properties that you would like to update. 

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization
The user must have the `itwins_modify` permission in order to modify iTwin properties.

An Organization Administrator can modify iTwins owned by their Organization.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin.
Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be [invited] (https://developer.bentley.com/apis/access-control/operations/add-iTwin-members/) to collaborate on the iTwin.


An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


update-itwin

A iTwin instance with the fields that should be updated.  ReadOnly fields should not be included.  

Invalid request to update a iTwin.  Review the 'Field Values' section near the top of this page.

---

Adds an iTwin to the calling User's recently used iTwins list. No more than 25 iTwins are stored in the recently used list. Older ones are removed to make room for new ones.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

The calling user must be a member of the specified iTwin. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---

add-itwin-to-my-recents

---

Retrieves a list of recently used iTwins for the calling user.

### Inactive iTwins
iTwins with *status=Inactive* are not returned by default. This improves query performance and reduces clutter in user interfaces by filtering out unused iTwins. 
You should still provide a way for users to see their Inactive iTwins if they request them. In the API, you can do this by setting the status parameter or by using the includeInactive parameter.

If *status=Inactive*, the API will return only Inactive iTwins.  
If *includeInactive=true*, the API will return all iTwins (Active, Trial and Inactive).

The includeInactive parameter is optional and defaults to false. A 422 error will be returned if you try to use a status parameter at the same time as the includeInactive parameter.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

Any user can call this endpoint. It will only return iTwins that the user is a member of. Use the [Access Control API](https://developer.bentley.com/apis/access-control/) to manage an iTwin's members.

---


get-my-recently-used-itwins

---

Creates a new Repository URI.

A repository is a Uri link to iTwin data managed by another service. The links for most classes are autogenerated but some can only be added manually using this POST endpoint.
      
The following Classes/SubClasses are supported. Classes in italics are auto generated. The others can be added using this POST endpoint.
- *iModels*
- *RealityData*
- *Storage*
- *Forms*
- *Issues* 
- GeographicInformationSystem
	+ WebMapService
    + WebMapTileService
    + MapServer
- ProjectWise

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization
The user must have the `itwins_modify` permission in order to add a repository URI to the iTwin.

An Organization Administrator can modify iTwins owned by their Organization. This includes adding a repository URI.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin.
Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be [invited] (https://developer.bentley.com/apis/access-control/operations/add-iTwin-members/) to collaborate on the iTwin.


An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


create-repository

This response indicates that the specified repository was not found.

---

Delete the specified Repository URI.

Only repositories added via the POST endpoint can be deleted. Autogenerated repository Uris cannot be deleted.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization
The user must have the `itwins_modify` permission in order to remove a repository URI from the iTwin.

An Organization Administrator can modify iTwins owned by their Organization. This includes deleting a repository URI.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin.
Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be [invited] (https://developer.bentley.com/apis/access-control/operations/add-iTwin-members/) to collaborate on the iTwin.


An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


delete-repository

repositoryId

---

Gets the details of the specified repository.

A repository is a Uri link to iTwin data managed by another service.

For example, if an iTwin has Forms data then you can get the Uri for that
data by using this api and specifying iTwinId = 547d397a-9921-4e4f-a7a2-c47fc19219b0 and Class = Forms. It will return the following.
```
{
   "repositories": [
   {
      "id": "547d397a-9921-4e4f-a7a2-c47fc19219b0",
      "class": "Forms",
      "subClass": null,
      "uri": "https://api.bentley.com/forms?projectId=547d397a-9921-4e4f-a7a2-c47fc19219b0"
   }]

```
If no Class is specified then all repositories containing data for the iTwin will be returned. The Uri is automatically generated
by calling each service to determine if its repository contains data for the specified iTwin. For example, if there are no iModels for the specified iTwin
then the iModel Repository Uri will not be returned. 

The following Classes/SubClasses are supported. Classes in italics are auto generated. The others can be added manually using the POST endpoint.
- *iModels*
- *RealityData*
- *Storage*
- *Forms*
- *Issues* 
- GeographicInformationSystem
   + WebMapService
   + WebMapTileService
   + MapServer
- ProjectWise

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwins:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must be an Organization Administrator for the Organization that owns the specified iTwin Repository or be an iTwin team member.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

---


get-repositories-by-itwin-id

Specify a particular class that you wish to query on.

Specify a particular subClass that you wish to query on (NOTE:  Only the 'GeographicInformationSystem' class can have a subClass).

Get My Primary Account - iTwins | iTwin Platform

This tutorial will guide you through the process of creating and querying iTwins

iTwins

Authentication

Request

Request headers

Response

Response 200 OK

Response 401 Unauthorized

Response 429 Too many requests

Definitions

iTwin (summary)

Error

Error Response