openapi: 3.0.3 info: version: 2.0.0 title: Cintoo Open Account Role API description: "Cintoo Open API 1.x documentation: https://aec.cintoo.com/api\n\nBETA: API v2 endpoints tagged \"BETA\" are available in beta-version, meaning that changes may be done later on.\n\n# API Specification\n\nThe Cintoo API specification document you are viewing is compliant with the Open API Specification 3.0.3 and can be\nexported to json or yaml format that can be used by the API tool of your liking.\n\nIt also means the generated json/yaml will contain all the details present in this documentation about the\n\n* JSON Objects schema being returned\n* The status codes\n* The authentication\n* The verbs/paths/resources\n\n## Technical details\n\n* The API is **resource oriented**\n* The encoding is done in **utf-8**\n* Do not hesitate to click on the Download button on the top of this page to get the `openapi.json` or `openapi.yaml`\n file generated and import in your favorite API client\n* Any Cintoo valid user can use the API\n\n- - -\n\n## Sandbox\n\nWith Cintoo Cloud API comes a Sandbox, which means a testing environment. This Sandbox is a separate tenant from the\nCintoo Cloud platform that you are already familiar with.\n\nThe Sandbox is at your disposal so that you can test and use the API with no consequence on your production data (no\nunfortunate deletion by mistake for example).\n\n### Sandbox restrictions\n\n* Scan capacity of 20 scans per user.\n* Company SSO (if any) is not applicable since the Sandbox uses a different account.\n* Please contact to get the invitation link to the Sandbox account.\n* You can use the same email but you will be asked to set a new password by clicking on the invitation link.\n* Please note that this is an experimental platform, so we reserve the right to refresh/delete the data (unlike the\n production platform).\n* There is no limit in time for using the Sandbox.\n* The BIM & CAD Module (BCM) is activated in this Sandbox, so feel free to use your BIM or CAD model in this testing\n environment.\n\nRegistering to the Sandbox / Cintoo Cloud API\n\nPlease contact our Support Team to be invited to the Sandbox and get all the documentation for\nCintoo Cloud API.\n\n- - -\n\n## Authentication\n\nThe Cintoo API relies on JWT Tokens for authenticating users with the standard combination `Access Token`+\n`Refresh Token`.\n\nNote that the first acquisition of the token pair requires a manual step (see below) for security reasons, then it can\nbe fully automated.\n\n### Access Tokens and Refresh Tokens\n\nThere are 2 kind of tokens:\n\n* Access token:\n * is short lived (3h)\n * is used to authenticate each query\n * is personal and should not be shared, except for service users (see `Token management recipes` at the end of the\n documentation)\n * is a JWT and is stateless, ie. there is *NO* limit of Access Token being valid for a given user simultaneously,\n and ***can*** be used in parallel.\n * example of API call to list `accounts`:\n `curl -H Authorization=\"Bearer $access_token\" https://aec.cintoo.com/api/accounts`\n\n> ***Note***: Calling the API with an already-used/expired token results in a response with status code `401`\n\n* Refresh token:\n * is long lived (months)\n * is used **once** to obtain a new `Access Token` + `Refresh Token` pair.\n * **cannot** be used to make API calls.\n * is personal and should not be shared, except for service users (see `Token management recipes` at the end of the\n documentation)\n * there ***IS*** a limit of 10 Refresh Token being valid for a given user simultaneously\n * is stateful and ***CANNOT*** be used in parallel, as it is consumed when used\n * example of refresh token call to get a new pair of \"Access Token\" and \"Refresh Token\":\n `curl -X POST https://aec.cintoo.com/oauth/token -d \"grant_type=refresh_token&refresh_token=$refresh_token\"`\n\n> ***Note***: Calling the API with an already-used/expired token results in a response with status code `401`\n\n### The token flow\n\nThe Cintoo API follows the OAuth 2.0 Authorization Grant Type flow, and supports the PKCE extension which is recommended\nto provide better security (source: )\n\nConcretely, users are supposed to acquire the token once with a manual step (they have to click on approve), to get a\nfirst pair of tokens.\n\nOnce this is done, they can script the refresh with\na [simple curl command](#refreshing-tokens-ie-generating-programmatically-a-new-access-token--refresh-token-pair).\n\n> ***Note:*** a refresh token is valid for 21 days. It can be used only once. The refreshing mechanism can be done **an\nunlimited number of times**\n\n### Generating Tokens\n\n* You are just starting with the Cintoo API and want to test it manually -> look that \"Generating the JWT Bearer Token\n with the cintoo-login.exe\"\n* You are already familiar with oauth mechanisms/tools -> look at \"Using tools/3rd party to manage Tokens from Cintoo\n Oauth Service\"\n\n### Generating the Access Token & Refresh Token pair with the cintoo-login.exe\n\nTo generate an Access Token with OAuth please use the following nice CLI\ntool [cintoo-login.exe](https://cintooprodstatic.blob.core.windows.net/api/cintoo-login-1.1.0-signed.exe) and double\nclick on it.\n\n**If you are on a dedicated tenant, please add the argument `--url`.**\n\n```powershell\n.\\cintoo-login-1.1.0-signed.exe --url https://aec.cintoo.com\n\nOpening OAuth page in browser.\nTo receive your JWT token:\n * Ensure you are logged-in\n * Click on the 'Allow' button\nINFO: You have 30s to complete these actions\n```\n\nWhich opens this page\n\n> Hint: if you wait more than 30s you will have to run the command again\n> Hint: you can change the timeout duration to another value with `--timeout 60`\n\n![allow-button](./assets/oauth.png#width=500px;height=350px;)\n\nOnce you click on `Allow` the page should lead you to:\n\n![success](./assets/success.png#width=500px;height=350px;)\n\n*AND* (most importantly) the **token** appears magically in your cmd output\n\n> Hint: Copy paste the `Bearer xxxxx` to avoid errors\n\n```powershell\nOpening OAuth page in browser.\nTo receive your JWT token:\n * Ensure you are logged-in\n * Click on the 'Allow' button\nINFO: You have 30s to complete these actions\nHere is your token: to use it put in the Authorization header (copy paste below):\n{\"Authorization\": \"Bearer \"}\nIts validity is of 3h\nA new token can be-regenerated simply thanks to this refresh_token: \nValidating token\nSuccess: API Token was successfully validated\n```\n\n### Refreshing tokens ie. Generating programmatically a new Access Token + Refresh Token pair\n\nWhile the Refresh Token is valid (within 21 days), you can consume it to get a new Access-Token + Refresh-Token pair.\n\n> ***Note:*** consuming the Refresh Token can be done before the expiration of the Access Token\n> ***Note:*** consuming the Refresh Token does **NOT** invalidate other **Access Token** as they are short lived\n\nUsing shell (Linux, OSX)\n\n```shell\nrefresh_token=\"\"\ncurl -X POST https://aec.cintoo.com/oauth/token -d \"grant_type=refresh_token&refresh_token=$refresh_token\"\n```\n\nWhich returns the following\n\n```json\n{\n \"access_token\": \"{access_token}\",\n \"refresh_token\": \"{refresh_token}\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 10800,\n \"user_id\": \"{user_id}\"\n}\n```\n\nUsing powershell (Windows)\n\n```powershell\n$refresh_token = \"\"\n$params = @{\n Uri = 'https://aec.cintoo.com/oauth/token'\n Method = 'POST'\n Body = @{\n grant_type = 'refresh_token'\n refresh_token = $refresh_token\n }\n ContentType = 'application/x-www-form-urlencoded'\n}\nInvoke-RestMethod @params\n```\n\nWhich returns the following\n\n```powershell\naccess_token : {access_token}\nrefresh_token : {refresh_token}\ntoken_type : Bearer\nexpires_in : 10800\nuser_id : {user_id}\n```\n\n### Using tools/3rd party to manage Tokens from Cintoo Oauth Service\n\nThe Cintoo API follows the oauth\nprotocol [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) to generate the `access-tokens`\nand `refresh-tokens`.\n\nAs such, it is possible to use 3rd party libraries and tools that implement the Oauth2 Authorization Code protocol to\nmanage the tokens (and perform automatic refresh).\n\nThe important fields are the following and they match those defined by\nthe [authorization code request](https://www.oauth.com/oauth2-servers/access-tokens/authorization-code-request/), [authorization code request with PKCE](https://www.oauth.com/oauth2-servers/pkce/authorization-request/)\nand [refreshing access tokens](https://www.oauth.com/oauth2-servers/access-tokens/refreshing-access-tokens/) :\n\n| Field | Value |\n|----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Grant Type | `Authorization Code` or `Authorization Code (With PKCE)` |\n| Callback URL | `localhost` or `127.0.0.1` or `/` |\n| Auth URL | `https://aec.cintoo.com/oauth/authorize` |\n| Access Token URL | `https://aec.cintoo.com/oauth/token` |\n| Refresh Token URL | `https://aec.cintoo.com/oauth/token` |\n| State | use a random code made of `[a-z0-9]+` with a \"correct length\". More information about the [state-parameters](https://auth0.com/docs/secure/attack-protection/state-parameters) |\n| Code Challenge Method (only with PKCE) | `SHA-256` more info on [PKCE](https://www.oauth.com/oauth2-servers/pkce/) |\n\n### The flow in detail for acquiring the first Token pair\n\nThis section is here in case you want to **build an oauth client for acquiring the first Token pair without the help of\nthe cintoo-login or without 3rd party software**.\n\nThe term \"Client\" is going to be described as the originator of the oauth token request.\n\n* Client calls the Cintoo `oauth/authorize` endpoint ***from the browser*** with the following query parameters:\n * the `redirect_uri` (callback-url) it wants Cintoo to send the authorization code to\n * the `state` uses a random code made of `[a-z0-9]+` with a \"correct length\". More information about\n the [state-parameters](https://auth0.com/docs/secure/attack-protection/state-parameters)\n * (optional) `code_challenge` a random code that has been hashed using the SHA256 algorithm. More info\n on [PKCE](https://www.oauth.com/oauth2-servers/pkce/).\n > code_verifier = high-entropy cryptographic random STRING using the\n unreserved characters [A-Z] / [a-z] / [0-9] / \"-\" / \".\" / \"_\" / \"~\"\n from Section 2.3 of [RFC3986], with a minimum length of 43 characters\n and a maximum length of 128 characters.\n * (optional but mandatory if `code_challenge` is set) `code_challenge_method` : \"SHA256\"\n* Cintoo API returns an html element with an `approve` button to be clicked by the user that started the action (the\n same shown in the previous chapter)\n* Once the `approve` button is pressed there is a `Form Post URL redirect` that will target the `redirect_uri` provided\n by the Client with the query parameters : `code` and `state` (+ `code_challenge` and `code_challenge_method` if\n specified before)\n* The Client ***should check*** that the `state` sent and received are the same to avoid CSRF attacks.\n* If they are the same, the Client can then send a `POST` query to the `oauth/token` endpoint with the following payload\n that contains the `code` it received on the previous steps.\n\n ```json\n {\n \"code\": \"{code}\",\n \"grant_type\": \"authorization_code\",\n \"authorization_code\": \"{redirect_uri}\"\n }\n ```\n\n or with PKCE\n\n ```json\n {\n \"code\": \"{code}\",\n \"grant_type\": \"authorization_code\",\n \"authorization_code\": \"{redirect_uri}\",\n \"code_verifier\": \"{code_verifier}\"\n }\n ```\n\n* Finally the Cintoo API answers the `oauth/token` with a json object that contains the `access_token` and\n `refresh_token` pair:\n\n ```json\n {\n \"access_token\": \"{access_token}\",\n \"refresh_token\": \"{refresh_token}\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 10800,\n \"user_id\": \"{user_id}\"\n }\n ```\n\n- - -\n\n## Doing queries\n\nBelow you will find an example on how to use the token to do a query.\n\nA good endpoint to start with is the `isLogged` **resource** which simply returns `200` and `{\"success\": true}` if the\ntoken was recognized by the Cintoo API.\n\nWe highly recommend that you try it, then start changing the resource type (like `accounts` for instance) to get used to\nthe API.\n\n### Query example for Windows\n\n#### with cUrl\n\n```sh\nexport HOST=aec.cintoo.com\nexport TOKEN=...\n\ncurl --url \"https://{host}/api/2/accounts\" --header \"Authorization: Bearer $TOKEN\"\n```\n\n#### with Python\n\n```python\nimport requests\n\nhost = \"{host}\"\ntoken = \"...\"\n\nresponse = requests.get(\n \"https://%s/api/2/accounts\" % host,\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n```\n\n#### with Powershell\n\nCopy the code below and try it in your Powershell terminal.\n\n> Hint: copy paste this while replacing the `xxxxxxx` with your token, and call as many `Invoke-RestMethod` as you want.\n> Note: the token is surrounded by `\"`\n\n```powershell\n$token = \"xxxxxxxxxxxxxxxxxx\"\n$headers = @{\n Authorization=\"Bearer $token\"\n Content='application/json'\n}\nInvoke-RestMethod -Headers $headers -Method Get -Uri \"https://aec.cintoo.com/api/isLogged\"\n```\n\nThe powershell command line should return this\n\n```powershell\nsuccess\n-------\n True\n```\n\n## URNs\n\nURNs are standard [Uniform Resource Names](https://fr.wikipedia.org/wiki/Uniform_Resource_Name).\n\nOur NID is of course \"cintoo\", so they look like: ```urn:cintoo:{object type}:{object id}```.\n\nAll the endpoints that return an object or a list of objects include a field giving the URN of the object, that you can\nin turn use to reference this object whenever you need to mention it.\n\n## References\n\nThroughout the API, most endpoints need you to give *references* to existing objects,\nlike accounts, projects, roles, etc. For example, getting the details of an account will look like:\n\n```\nGET /api/2/accounts/{accountRef}\n```\n\nA *reference* can be any unambiguous identifier for the object. It typically is either:\n\n- the raw uuid or numerical id, depending on the type of the object:\n - ```c41aec8b-3b85-4bdd-81e5-c2cfdb8980e8```\n - ```5```\n- a URN (Uniform Resource Name), looking like: ``urn:cintoo::``. For example:\n - ```urn:cintoo:account:c41aec8b-3b85-4bdd-81e5-c2cfdb8980e8```\n - ```urn:cintoo:user:5```\n\nThe URN is the most durable option and should be preferred, each object returned by the API has an ```urn``` field\nholding it,\nwhereas at some point the raw id/uuid objects fields will be deprecated or removed from the objects content.\n\nIf your client needs to store identifiers for objects, **you should choose the URN**,\n\n- - -\n\n## Errors\n\nTo communicate errors, the Cintoo API\n\n* fills the HTTP status code defined by the\n standard: [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)\n\nIt is consensus in the industry that the ***status code is the source of truth*** on whether an API call was successful\nor not, the ***body is merely a BONUS***.\n\n### Error-body returned\n\nWe are following this [RFC](https://www.rfc-editor.org/rfc/rfc9457) whose content is the following\n\n> * The \"status\" member is a JSON number indicating The HTTP status code ([HTTP], Section 15) generated by the origin\n server for this occurrence of the problem.\n >\n > The \"status\" member, if present, is only advisory; it conveys the HTTP status code used for the convenience of\n the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP\n software that does not understand this format still behaves correctly. See Section 5 for further caveats regarding\n its use.\n >\n > Consumers can use the status member to determine what the original status code used by the generator was when it\n has been changed (e.g., by an intermediary or cache) and when a message's content is persisted without HTTP\n information. Generic HTTP software will still use the HTTP status code.\n> * The \"title\" member is a JSON string containing a short, human-readable summary of the problem type.\n >\n > It SHOULD NOT change from occurrence to occurrence of the problem, except for localization (e.g., using\n proactive content negotiation; see [HTTP], Section 12.1).\n >\n > The \"title\" string is advisory and is included only for users who are unaware of and cannot discover the\n semantics of the type URI (e.g., during offline log analysis).\n> * \"detail\" (string) - The \"detail\" member is a JSON string containing a human-readable explanation specific to this\n occurrence of the problem.\n >\n > The \"detail\" string, if present, ought to focus on helping the client correct the problem, rather than giving\n debugging information.\n >\n > Consumers SHOULD NOT parse the \"detail\" member for information; extensions are more suitable and less\n error-prone ways to obtain such information.\n\nIn addition, 2 extension fields are added:\n\n* `errorCode`: detailed code describing the error, can be used to map to a localized message\n* `errorValues`: values implied in the error, typically an input parameter, can be used to include in a localized\n message\n\nThe mandatory fields that are always present are : `status` and `title`. Others are optional.\n\nExample:\n\n```json\n{\n \"status\": 404,\n \"title\": \"Not Found\",\n \"detail\": \"Account 1234 not found\",\n \"errorCode\": \"account-not-found\",\n \"errorValues\": {\n \"accountId\": \"1234\"\n }\n}\n```\n\nSo the HTTP response status code is both in the HTTP header, and in the `status` attribute of the returned JSON object.\n\nFor a list of `errorCode` and `errorValues`, see the dedicated section [Errors List](#tag/errors_list)\n\n- - -\n\n## Permissions\n\nEach resource needs to have a permission to be accessed.\nPermissions are represented by three elements:\n\n* *domain*: the level on which the resource is: `tenant`, `account`, `project` or `workzone`\n* *resource*: the type of resource, for example `users` or `tags`\n* *right*: the right on the resource the permission is giving.\n Most of the time it will be either `read` (get/list resource) or `write` (create, update, delete)\n but can be another action when finer granularity is needed.\n\nThis is represented by a string containing those 3 elements separated by a colon: `::`.\nFor example `account:users:read` is the permission to *read* (view/list) users on the account level.\n\nHere is the list of the currently supported permissions:\n\n* `tenant:user-permissions:read`\n* `tenant:user-permissions:write`\n* `account:account:read`\n* `account:account:update-owner`\n* `account:administrators:read`\n* `account:administrators:write`\n* `account:integrations:read`\n* `account:integrations:write`\n* `account:project-listers:read`\n* `account:project-listers:write`\n* `account:project-managers:read`\n* `account:project-managers:write`\n* `account:projects:read` (implies `project:project:read` on all projects of the account)\n* `account:projects:create`\n* `account:projects:update` (implies `project:project:update-details` on all projects of the account)\n* `account:projects:delete` (implies `project:project:delete` on all projects of the account)\n* `account:roles:read`\n* `account:roles:write`\n* `account:subscriptions:read`\n* `account:subscriptions:update-name`\n* `account:users:read`\n* `account:users:write` (implies `workzone:members:write` on all workzones in the account)\n* `account:groups:read`\n* `project:project:read`\n* `project:project:delete`\n* `project:project:update-details`\n* `project:project:update-owner`\n* `project:project:update-subscription`\n* `project:members:list`\n* `project:annotations:create-integration-link`\n* `project:integrations:read`\n* `project:integrations:write`\n* `workzone:annotations:read`\n* `workzone:annotations:write`\n* `workzone:crops:read`\n* `workzone:crops:write`\n* `workzone:documents:read`\n* `workzone:documents:write`\n* `workzone:export-jobs-reality-data:read`\n* `workzone:export-jobs-reality-data:write`\n* `workzone:import-jobs-reality-data:write`\n* `workzone:measurements:read`\n* `workzone:measurements:write`\n* `workzone:members:write`\n* `workzone:share-links:read`\n* `workzone:share-links:write`\n* `workzone:own-share-links:read`\n* `workzone:own-share-links:write`\n* `workzone:reality-data:read`\n* `workzone:reality-data:write`\n* `workzone:reality-data:transform`\n* `workzone:savedviews:read`\n* `workzone:savedviews:write`\n* `workzone:tags:read`\n* `workzone:tags:write`\n* `workzone:workzones:read`\n* `workzone:workzones:write`\n* `workzone:progress-monitoring-jobs:read`\n* `workzone:progress-monitoring-jobs:write`\n* `workzone:own-progress-monitoring-jobs:read`\n* `workzone:own-progress-monitoring-jobs:write`\n* `workzone:model-reports:read`\n* `workzone:model-reports:write`\n* `workzone:cad-model:read`\n* `workzone:cad-model:write`\n* `workzone:cad-model:transform`\n* `workzone:own-import-jobs-cad-model:read`\n* `workzone:own-import-jobs-cad-model:write`\n* `workzone:import-jobs-cad-model:read`\n* `workzone:import-jobs-cad-model:write`\n* `workzone:video3d:read`\n* `workzone:video3d:write`\n* `workzone:import-video3d:write`\n\n### Roles\n\nA user is given permissions through roles. There are roles on the different levels detailed below.\n\n#### Roles at the account level\n\nRoles on an account are currently not modifiable, and are the following:\n\n* *Account Member* is any user invited to the account\n* *Account Owner*\n* *Account Administrator*\n* *Project Manager*\n* *Project Lister*\n\nAn *account member* has the following permissions:\n\n* `account:account:read` to view the account\n* `account:roles:read` to view roles on the account\n* `account:groups:read` to view groups on the account\n\nAn *account owner* or *account administrator* are account members, and have the following additional permissions:\n\n* `account:projects:read` to list and view all projects on the account\n* `account:projects:update` to update any project on the account\n* `account:roles:write` to create, edit and delete roles on the account\n* `account:users:read` to list users members of the account\n* `account:users:write` to invite or remove users on the account\n* `account:subscriptions:read` to view subscriptions of the account\n* `account:subscriptions:update-name` to rename a subscription of the account\n* `account:administrators:read` to list administrators on the account\n* `account:administrators:write` to invite or remove an administrator\n* `account:project-managers:read` to list project managers on the account\n* `account:project-managers:write` to invite or remove a project manager\n* `account:project-listers:read` to list project listers on the account\n* `account:project-listers:write` to invite or remove a project lister\n* `account:integrations:read` to list and view all integrations configured on the account\n* `account:integrations:write` to create, update and delete integrations on the account\n\nAn account owner has also the permission `account:account:update-owner` that an account administrator does not have,\nto set another user as the account owner\n\nA *project manager* is an account member with the following additional permissions:\n\n* `account:projects:read` to list and view all projects on the account\n* `account:projects:create` to create new projects\n* `account:projects:update` to update any project\n* `account:projects:delete` to delete any project\n* `account:roles:write` to create, edit and delete roles on the account\n* `account:users:read` to list users of the account\n* `account:users:write` to invite or remove users on the account\n* `account:subscriptions:read` to view subscriptions of the account\n* `account:project-managers:read` to list project managers on the account\n* `account:project-managers:write` to invite or remove a project manager\n\nA *project lister* is an account member with the following additional permission:\n\n* `account:projects:read` to list and view all projects of the account\n\n#### Roles at project and workzone levels\n\nRoles can be created on an account to give permissions on project and workzone levels.\n\nUsers and groups are invited to a project with a specific role, thus a user has the role assigned to him,\nbut also the roles of the groups he belongs to.\nA user's permissions are determined by adding the permissions of all his roles.\n\nCurrently the permissions given to a role are restricted to the following:\n\n* `project:project:update-details` + `project:project:delete`\n allows the user to manage the project\n* `workzone:workzones:read` + `workzone:workzones:write`\n allows the user to create, modify and delete work zones\n* `workzone:reality-data:read` + `workzone:crops:read` allows the user to view reality data\n* `workzone:reality-data:write` + `workzone:import-jobs-reality-data:write`\n allows the user to import or delete scans\n* `workzone:reality-data:transform`\n allows the user to modify the position and/or rotation of a scan\n* `workzone:export-jobs-reality-data:write`\n allows the user to export and download reality data\n* `workzone:annotations:read` allows the user to view annotations\n* `workzone:annotations:read` + `workzone:annotations:write`\n allows the user to create, edit and delete annotations, and assign notes to team members\n* `workzone:measurements:read` + `workzone:measurements:write` + `workzone:crops:write`\n allows the user to add and view 3D measurements (and add/update crops)\n* `workzone:share-links:read` + `workzone:share-links:write`\n allows the user to create, edit and delete share links\n* `workzone:own-share-links:read` + `workzone:own-share-links:write`\n allows the user to create, edit and delete the share links they created\n* `workzone:documents:read` + `workzone:documents:write`\n allows the user to upload and download documents\n* `workzone:tags:read` allows the user to view tags\n* `workzone:tags:write`\n allows the user to import, create, edit and delete tags\n* `workzone:savedviews:read` allows the user to view saved views\n* `workzone:savedviews:read` + `workzone:savedviews:write`\n allows the user to create, edit and delete saved views\n* `workzone:members:write` allows the user to add and remove team members\n* `workzone:progress-monitoring-jobs:read` + `workzone:progress-monitoring-jobs:write`\n + `workzone:own-progress-monitoring-jobs:read` + `workzone:own-progress-monitoring-jobs:write`\n + `workzone:model-reports:read` + `workzone:model-reports:write`\n allows the user to create, edit, download and delete progress monitoring reports\n* `workzone:cad-model:read` + `workzone:cad-model:write` + `workzone:own-import-jobs-cad-model:read` +\n `workzone:own-import-jobs-cad-model:write` + `workzone:import-jobs-cad-model:read` +\n `workzone:import-jobs-cad-model:write` allow the user to create, edit, download and delete CAD Model and to import\n them from different sources.\n* `workzone:cad-model:transform`\n allows the user to modify the position and/or rotation of a 3D model\n* `workzone:video3d:write` + `workzone:import-video3d:write` allow the user to trigger the Add 360Video job\n\nAny member of a project also automatically has the following permissions:\n\n* `project:project:read` and `project:members:list` on the project\n* `workzone:workzones:read` on the workzone he is member and all its child workzones\n\nA project owner automatically has all permissions on the project and all its workzones.\n\nA member having permission `workzone:annotations:write` on the root work zone of a project,\nautomatically has the following permissions on the project:\n\n* `project:annotations:create-integration-link`\n* `project:integrations:read`\n* `project:integrations:write`\n\n- - -\n\n## API 1 and API 2\n\n### What to expect with API 2\n\n* Stage 1: API 2 provides features not covered by API 1.\\\n Most of features are tagged `BETA` showing that they will continue to mature\n* Stage 2: API 2 `BETA` tags are removed, and API 2 starts covering API 1 features\n* Stage 3: API 2 fully covers API 1 scope\n* Stage 4: API 1 will have a end of life support date communicated\n* Stage 5: API 1 will be decommissioned\n\n### Similarities\n\n* Authentication system is the same. Tokens used on API 1 can be used in API 2.\n* Do follow the same kind of path ex: `/accounts/{accountRef}/projects/{projectRef}/...`\n\n### Differences\n\n* Reference system is different: API 2 handles new Reference types (URNs), classic references (UUID) and \"legacy\n references\" coming from API 1.\\\n API 1 supports UUID and \"legacy references\" only.\n* Error messages in API 2 follow\n the [RFC 9457 (Problem Details for HTTP APIs)](https://www.rfc-editor.org/rfc/rfc9457).\\\n In short `{\"code\": ..., \"message\": ...}` becomes `{\"status\": ..., \"title\": ...}`.\n* All resources returned by API 2 have multiple ref types (always an URN + UUID or INT)\n* POST and PUT endpoints do return full objets (normally available with a GET)\n* Objects returned from API 1 and API 2 differ\n\n### Endpoints only in API 1\n\n* Report Projects Last Accessed Date\n* Report Users Last Activity Date" license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: name: API Support email: support@cintoo.com x-logo: url: ./assets/logo_api.svg altText: Cintoo API servers: - url: https://aec.cintoo.com security: - oauth2: [] tags: - name: Role paths: /api/2/accounts/{accountRef}/roles: get: summary: List Roles operationId: getRoles description: 'BETAList available roles into this account. Requires the permission `account:roles:read`. ' tags: - Role parameters: - $ref: '#/components/parameters/accountRef' responses: '200': description: List and content of the Roles content: application/json: schema: type: array items: $ref: '#/components/schemas/Role' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/roles\"\n % (host, accountUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/roles`;\nconst res = await fetch(url, {\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" post: summary: Create Role operationId: createRole description: 'BETACreate a custom role. Requires the permission `account:roles:write`. One of `permissions` or `legacyPermissions` must be present and non-empty. If both are specified (discouraged) they must be strictly equivalent. For the field `permissions`, the allowed combinations are documented [here](#section/API-Specification/Permissions). ' tags: - Role parameters: - $ref: '#/components/parameters/accountRef' requestBody: content: application/json: schema: $ref: '#/components/schemas/roleCreate' responses: '201': description: The role was successfully created content: application/json: schema: $ref: '#/components/schemas/Role' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\n\ncurl --request POST --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"Viewer\",\n \"description\": \"Read only user\",\n \"color\": \"#123456\",\n \"permissions\": [\"view3d\", \"measure\", \"view_tag\"]\n}'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.post(\n \"https://%s/api/2/accounts/%s/roles\"\n % (host, accountUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"name\": \"Viewer\",\n \"description\": \"Read only user\",\n \"color\": \"#12345e\",\n \"permissions\": [\"view3d\", \"measure\", \"view_tag\"]\n }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/roles`;\nconst res = await fetch(url, {\n method: \"POST\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(\n {\n \"name\": \"Viewer\",\n \"description\": \"Read only user\",\n \"color\": \"#123456\",\n \"permissions\": [\"view3d\", \"measure\", \"view_tag\"]\n }\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/accounts/{accountRef}/roles/{roleRef}: get: summary: Get Role operationId: getRole description: 'BETAGet a role details. Requires the permission `account:roles:read`. ' tags: - Role parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/roleRef' responses: '200': description: Content of the requested Role content: application/json: schema: $ref: '#/components/schemas/Role' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport ROLEID=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles/$ROLEID\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nroleId = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/roles/%s\"\n % (host, accountUUID, roleId),\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst roleId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/roles/${roleId}`;\nconst res = await fetch(url, {\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" delete: summary: Delete Role operationId: deleteRole description: 'BETADelete a Role. Requires the permission `account:roles:write`. ' tags: - Role parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/roleRef' responses: '204': description: The role was successfully deleted '400': description: Cannot delete base role, or role is used in projects content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorBadRequest' - type: object properties: errorCode: type: string description: '* `cannot-delete-base-role` if the role is a base role * `role-used` if the role is used in projects ' errorValues: type: object properties: roleId: type: string description: role id for errorCode `role-used` projectIds: type: string description: comma separated list of projects using the role for errorCode `role-used` examples: cannot-delete-base-role: value: status: 400 title: Bad Request detail: Base roles can't be deleted errorCode: cannot-delete-base-role role-used: value: status: 400 title: Bad Request detail: Role 1234 is in use in projects projectId1, projectId2, projectId3 errorCode: role-used errorValues: roleId: '1234' projectIds: projectId1, projectId2, projectId3 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport ROLEID=...\n\ncurl --request DELETE --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles/$ROLEID\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nroleId = \"...\"\ntoken = \"...\"\n\nresponse = requests.delete(\n \"https://%s/api/2/accounts/%s/roles/%s\"\n % (host, accountUUID, roleId),\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst roleId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/roles/${roleId}`;\nconst res = await fetch(url, {\n method: \"DELETE\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" put: summary: Update Role operationId: updateRole description: 'BETAUpdate a role. ⚠ Overwrites all fields. Missing fields will be considered as null and current values will be erased Permissions: Requires the permission `account:roles:write`. One of `permissions` or `legacyPermissions` must be present and non-empty. If both are specified (discouraged) they must be strictly equivalent. For the field `permissions`, the allowed combinations are documented [here](#section/API-Specification/Permissions). ' tags: - Role parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/roleRef' requestBody: content: application/json: schema: $ref: '#/components/schemas/roleUpdate' responses: '200': description: New content of the updated Role content: application/json: schema: $ref: '#/components/schemas/Role' '400': description: Cannot update base role content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorBadRequest' - type: object properties: errorCode: type: string description: '`cannot-update-base-role` if the role is a base role' examples: cannot-update-base-role: value: status: 400 title: Bad Request detail: Base roles can't be updated errorCode: cannot-update-base-role 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport ROLEID=...\n\ncurl --request PUT --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles/$ROLEID\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"description\": \"Better description\",\n \"color\": \"#E529B0\"\n }'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nroleId = \"...\"\ntoken = \"...\"\n\nresponse = requests.put(\n \"https://%s/api/2/accounts/%s/roles/%s\"\n % (host, accountUUID, roleId),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"description\": \"Better description\",\n \"color\": \"#E529B0\"\n }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst roleId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/roles/${roleId}`;\nconst res = await fetch(url, {\n method: \"PUT\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(\n {\n \"description\": \"Better description\",\n \"color\": \"#E529B0\"\n }\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" components: schemas: RolePermissions: type: array description: permissions given by the role. Please check the [permissions](#section/API-Specification/Permissions) section for the list of allowed combinations minItems: 1 items: type: string enum: - project:project:delete - project:project:update-details - workzone:workzones:write - workzone:workzones:read - workzone:annotations:write - workzone:annotations:read - workzone:measurements:write - workzone:measurements:read - workzone:share-links:write - workzone:share-links:read - workzone:own-share-links:write - workzone:own-share-links:read - workzone:reality-data:read - workzone:reality-data:write - workzone:reality-data:transform - workzone:cad-model:transform - workzone:cad-model:read - workzone:import-jobs-reality-data:write - workzone:export-jobs-reality-data:read - workzone:export-jobs-reality-data:write - workzone:documents:write - workzone:documents:read - workzone:members:write - workzone:tags:write - workzone:tags:read - workzone:savedviews:write - workzone:savedviews:read - workzone:model-reports:read - workzone:model-reports:write - workzone:progress-monitoring-jobs:read - workzone:progress-monitoring-jobs:write - workzone:own-progress-monitoring-jobs:read - workzone:own-progress-monitoring-jobs:write AccountUrn: type: string description: '"urn:cintoo:account:" followed by an UUIDv4 ' roleUpdate: type: object properties: name: type: string example: BIM / VDC Manager description: type: string example: Can do anything except creating projects color: $ref: '#/components/schemas/Color' permissions: type: array nullable: true allOf: - $ref: '#/components/schemas/RolePermissions' legacyPermissions: type: array nullable: true allOf: - $ref: '#/components/schemas/RoleLegacyPermissions' AccountId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 Role: type: object required: - id - type - api1Id - name - description - color - createdBy - createdAt - updatedAt - permissions - legacyPermissions x-tags: - Role properties: id: readOnly: true $ref: '#/components/schemas/RoleUrn' type: type: string enum: - role name: type: string example: BIM / VDC Manager description: type: string example: Can do anything except creating projects color: $ref: '#/components/schemas/Color' createdBy: type: string allOf: - $ref: '#/components/schemas/UserUrn' nullable: true createdAt: type: string allOf: - $ref: '#/components/schemas/DateTime' nullable: true updatedAt: type: string allOf: - $ref: '#/components/schemas/DateTime' nullable: true permissions: $ref: '#/components/schemas/RolePermissions' legacyPermissions: $ref: '#/components/schemas/RoleLegacyPermissions' DateTime: type: string format: date-time description: 'The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31Z)' example: '2017-08-18T12:41:31Z' Uuid: type: string description: UUIDv4 format: uuid example: 156fff1a-0ef7-4335-891a-627928a19e29 UserUrn: type: string description: '"urn:cintoo:user:" followed by an UUIDv4 ' ErrorBadRequest: type: object required: - status - title properties: status: type: integer format: int32 enum: - 400 title: type: string enum: - Bad Request detail: type: string description: human readable description of the error in english RoleId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 Color: type: string pattern: ^#[0-9a-f]{6}$ example: '#0698ec' Error: type: object required: - status - title properties: status: type: integer format: int32 title: type: string detail: type: string description: human readable description of the error in english errorCode: type: string description: detailed code describing error, can be used to map to a localized message errorValues: type: object description: values implied in the error, typically an input parameter, can be used to include in a localized message roleCreate: type: object required: - name properties: name: type: string example: BIM / VDC Manager description: type: string example: Can do anything except creating projects color: $ref: '#/components/schemas/Color' permissions: $ref: '#/components/schemas/RolePermissions' legacyPermissions: $ref: '#/components/schemas/RoleLegacyPermissions' RoleLegacyPermissions: type: array description: "Permissions given by the role, in the legacy format, among:\n - `create_project`: Update, delete or restore projects created by a project manager\n - `workzone`: Create, modify & delete Work Zones\n - `view3d`: Overview, 3D view, Scan View\n - `annotate`: Create, edit and delete annotations, assign notes to Team Members\n - `measure`: Add and view 3D measurements\n - `share`: Can share project\n - `upload`: Upload or delete laser scans or 360° images and manage versions\n - `download`: Export in E57 or download Reality Data via Cintoo Connect\n - `upload_doc`: Upload and download documents and 3D models from BIM platforms or from desktop\n - `manage_users`: Add / remove new Team Members and define permissions\n - `create_asset`: Import, create, edit and delete tags\n - `view_asset`: View and export tags\n - `view_annotation`: View annotations\n - `manage_savedview`: Create, edit and delete saved views\n - `view_savedview`: View saved views\n - `manage_cipm`: Manage Progress Monitoring Jobs\n" minItems: 1 items: type: string enum: - create_project - workzone - view3d - annotate - measure - share - upload - download - upload_doc - manage_users - create_asset - view_asset - view_annotation - manage_savedview - view_savedview - manage_cipm RoleUrn: type: string description: '"urn:cintoo:role:" followed by an UUIDv4 ' parameters: roleRef: name: roleRef in: path required: true description: The Id or Urn of the role schema: oneOf: - $ref: '#/components/schemas/RoleUrn' - $ref: '#/components/schemas/RoleId' accountRef: name: accountRef in: path required: true description: The Id or Urn of the account schema: oneOf: - $ref: '#/components/schemas/AccountUrn' - $ref: '#/components/schemas/AccountId' responses: UnexpectedError: description: unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' examples: '400': value: status: 400 title: Bad Request '401': value: status: 401 title: Unauthorized '403': value: status: 403 title: Forbidden '404': value: status: 404 title: Not Found '405': value: status: 405 title: Method Not Allowed '406': value: status: 406 title: Not Acceptable securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://aec.cintoo.com/oauth/authorize tokenUrl: https://aec.cintoo.com/oauth/token scopes: {} refreshUrl: https://aec.cintoo.com/oauth/token x-tagGroups: - name: General tags: - errors_list - internal_information - token_management - Permissions - Authentication - name: Resources tags: - Resources - name: Tenant tags: - Tenant - name: Account tags: - Account - Subscription - Role - User - Group - Trusted Device - name: Subscription tags: - Usage Report - name: Project tags: - Project - Members - Workzone - name: Project Data tags: - File - Annotation - Saved View - Share Link - Crop - Measurement - Tag List - Tag - name: Jobs tags: - Progress Monitoring - Import Model - Export Scene - Segmentation - Video360 - Import IDD - name: Integrations tags: - Integrations - Konekt - Autodesk - Procore - name: Tutorials tags: - tuto_upload_file - understand_tag_data