Create & Query Projects

Introduction

This tutorial will take you through the process of creating and querying for an iTwin Project.

By the end of this walk-through, you will be able to utilize the API endpoints in order to create or query projects.

Info

Skill level:

Basic

Duration:

20 minutes

Prerequisites

This tutorial assumes that you already have:

  • A tool such as Postman that can be used to execute http calls. These calls can also be made using the TryIt button in the API documentation.
  • If a user is affiliated with an Organization, then the user must be an Organization Administrator in order to create a project. 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 wiki page.

1. Register an Application

To build an application on the iTwin Platform, you will need to register a client.

Click the Register Application button to automatically register a client for this quick start. You can find registered application in My apps page.

Application registration process


To register a client:

  1. Go to the iTwin Platform home page
  2. Click the Sign In button and sign-in using your Bentley account credentials
    • If you have not already registered, click Register now and complete the registration process.
  3. Click on your user icon and navigate to the My Apps page
  4. Click the Register New button
  5. Give your application a Name
  6. Select the Administration API
  7. Select application type SPA (Single Page Web Application)
  8. Enter Redirect URL
    • For this tutorial use https://localhost:3000
  9. Leave post logout redirect URIs empty.
  10. Click the Save button
Note the Client ID that is generated during the registration process. You will need this in a later step.

2. Get a token

Before you can make a request to the APIs, a user token is needed. There are several ways to get it.

Implement Authorization Code Flow in the application


Here you can use Client ID generated from previous registration step.

Grab a user token from Api reference “Try it” Section


  1. Go here
  2. Click Try it button.
  3. Under the Authorization section, select authorizationCode from the dropdown.
  4. After the signin popup closes, the Authorization header with token value should be visible beneath the HTTP request dropdown.
  5. Copy & paste the Authorization value for this tutorial.
Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

3. Create a new iTwin Project

The Projects API is used to create and manage projects. A POST call to the projects endpoint will create a new project.

Only displayName and projectNumber are required for creating a new project. They must be unique so if you get a Conflict error then you will need to replace them with unique values. See the Projects API documentation for descriptions of the different properties, including default values. For this example, we will set allowExternalTeamMembers to true. This will allow us to add any user to the project, even users that are not part of our organization.

The POST call will return a new project instance. The id can be used to query for the project. The project Id is also used in many other iTwin APIs. You may want to save this Id to use in other tutorials.

Request Syntax


1 POST https://api.bentley.com/projects/ HTTP/1.1

Request Headers


1 2 3 Accept: application/vnd.bentley.itwin-platform.v1+json Content-Type: application/json Authorization: Bearer JWT_TOKEN

Request Body


1 2 3 4 5 6 7 8 9 10 { "displayName": "Tutorial Sample Project", "projectNumber": "Tutorial Project 123", "geographicLocation": "Exton, PA, USA", "latitude": "40.032970", "longitude": "-75.631538", "timeZone": "Eastern Standard Time", "billingCountry": "US", "allowExternalTeamMembers": true }

Response Headers


1 2 3 4 5 6 7 8 HTTP/1.1 201 Created content-length: 937 content-type: application/json date: Thu, 24 Jun 2021 14:44:18 GMT request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 5262b13f-394e-49b8-95ea-a5361d2513a3 x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US

Response Body


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 { "Project": { "id": "083004cb-9cc1-4d1b-bc2a-d6329288200e", "displayName": "Tutorial Sample Project"", "projectNumber": "Tutorial Project 123", "registrationDateTime": "2021-06-24T14:44:19.3300000", "registeredBy": "d27f4f7a-cf24-41fa-8044-c17eaaaccfb5", "geographicLocation": "Exton, PA, USA", "latitude": "40.032970", "longitude": "-75.631538", "timeZone": "Eastern Standard Time", "dataCenterLocation": "East US", "billingCountry": "US", "status": "active", "allowExternalTeamMembers": true, "_links": { "storage": { "href": "https://api.bentley.com/storage/folders/ywQwCMGcG028KtYykoggDssEMAjBnBtNvCrWMpKIIA4" }, "forms": { "href": "https://api.bentley.com/forms?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" }, "issues": { "href": "https://api.bentley.com/issues?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" }, "imodels": { "href": "https://api.bentley.com/imodels?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" } } } }

4. Query for an iTwin Project Using the Project Id

The project id can be used to query for a specific project.

The project will only be returned if you are an Organization Administrator or if you have been added as a member of the project with any role. Only a single project will be returned.

Request Syntax


1 GET https://api.bentley.com/projects/083004cb-9cc1-4d1b-bc2a-d6329288200e HTTP/1.1

Request Headers


1 2 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN

Response Headers


1 2 3 4 5 6 7 8 HTTP/1.1 200 OK content-length: 936 content-type: application/json date: Thu, 24 Jun 2021 18:10:04 GMT request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: fed95960-ea7c-43b5-a9af-66ab5353d073 x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US

Response Body


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 { "Project": { "id": "083004cb-9cc1-4d1b-bc2a-d6329288200e", "displayName": "Tutorial Sample Project", "projectNumber": "Tutorial Project 123", "registrationDateTime": "2021-06-24T14:44:19.3300000", "registeredBy": "d27f4f7a-cf24-41fa-8044-c17eaaaccfb5", "geographicLocation": "Exton, PA, USA", "latitude": "40.032970", "longitude": "-75.631538", "timeZone": "Eastern Standard Time", "dataCenterLocation": "East US", "billingCountry": "US", "status": "active", "allowExternalTeamMembers": true, "_links": { "storage": { "href": "https://api.bentley.com/storage/folders/ywQwCMGcG028KtYykoggDssEMAjBnBtNvCrWMpKIIA4" }, "forms": { "href": "https://api.bentley.com/forms?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" }, "issues": { "href": "https://api.bentley.com/issues?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" }, "imodels": { "href": "https://api.bentley.com/imodels?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" } } } }

5. Query for an iTwin Projects Using the Project Number

The projectNumber query parameter can be used to find a project using the projectNumber. Because this is a query, the response will be a list of projects that will usually contain one element. The projectNumber is unique for projects created in your organization. However, it is possible that you are a member of a project in another organization that has the same projectNumber.

The api will only return projects that you are able to access. If you expect it to return a specific project and it does not then you may not have access to that project.

Request Syntax


1 GET https://api.bentley.com/projects/?projectNumber=Tutorial%20Project%20123 HTTP/1.1

Request Headers


1 2 3 Prefer: return=representation Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN

Response Headers


1 2 3 4 5 6 7 8 9 HTTP/1.1 200 OK cache-control: must-revalidate, no-cache, private content-encoding: gzip content-type: application/json date: Thu, 24 Jun 2021 18:20:43 GMT request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: dd4d68c9-614d-4d67-8e51-7147c18513f8 x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US

Response Body


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 { "Projects": [{ "id": "083004cb-9cc1-4d1b-bc2a-d6329288200e", "displayName": "Tutorial Sample Project", "projectNumber": "Tutorial Project 123", "registrationDateTime": "2021-06-24T14:44:19.3300000", "registeredBy": "d27f4f7a-cf24-41fa-8044-c17eaaaccfb5", "geographicLocation": "Exton, PA, USA", "latitude": "40.032970", "longitude": "-75.631538", "timeZone": "Eastern Standard Time", "dataCenterLocation": "East US", "billingCountry": "US", "status": "active", "allowExternalTeamMembers": true, "_links": { "storage": { "href": "https://api.bentley.com/storage/folders/ywQwCMGcG028KtYykoggDssEMAjBnBtNvCrWMpKIIA4" }, "forms": { "href": "https://api.bentley.com/forms?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" }, "issues": { "href": "https://api.bentley.com/issues?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" }, "imodels": { "href": "https://api.bentley.com/imodels?projectId=083004cb-9cc1-4d1b-bc2a-d6329288200e" } } }], "_links": { "self": { "href": "https://api.bentley.com/projects/?$skip=0&$top=100" } } }

6. Query for an iTwin Projects Using the Project Number or Name (wildcard)

The $search query parameter can be used to find a project using a query string that will search using the projectNumber or displayName. This example will find all projects with “Tutorial” in the projectNumber or displayName. The query is case sensitive and you should not add wildcard characters to the query string. This example is the SQL equivalent of projectNumber like “%Tutorial%” OR displayName like '%Tutorial%’.

Because this is a query, the response will be a list that could contain many projects. Notice that this example is using the prefer header to indicate that only the minimal representation of the projects should be returned. This should be used whenever possible to improve performance and reduce the size of the response payload.

The api will only return projects that you are able to access. If you expect it to return a specific project and it does not then you may not have access to that project.

Request Syntax


1 GET https://api.bentley.com/projects/?$search=Tutorial HTTP/1.1

Request Headers


1 2 3 Prefer: return=minimal Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN

Response Headers


1 2 3 4 5 6 7 8 9 HTTP/1.1 200 OK cache-control: must-revalidate, no-cache, private content-encoding: gzip content-type: application/json date: Thu, 24 Jun 2021 18:40:47 GMT request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584 x-correlation-id: 86bc760f-d0c4-4292-b72d-97a078ce1c7a x-itwinplatform-media-type: bentley.itwin-platform.v1 x-itwinplatform-region: East US

Response Body


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "Projects": [{ "id": "083004cb-9cc1-4d1b-bc2a-d6329288200e", "displayName": "Tutorial Sample Project", "projectNumber": "Tutorial Project 123" }, { "id": "0ed7a661-4b7f-44ce-b6c3-f0064bb14c70", "displayName": "A Tutorial Project", "projectNumber": "Project A" }, { "id": "bc29f384-bd93-48c9-ae6c-08cb36b40fb0", "displayName": "A Sample Project", "projectNumber": "tutorial A" }], "_links": { "self": { "href": "https://api.bentley.com/projects/?$skip=0&$top=100" } } }

Continue learning

More resources that you may like

iTwin Project Sample App

Sample application that uses the Projects API to create, update and query for projects.