openapi: 3.0.3 info: version: 2.0.0 title: Cintoo Open Account Project 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: Project paths: /api/2/accounts/{accountRef}/projects: get: summary: List Projects operationId: getProjects description: BETAList active and deleted projects into this account. tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/countScans' - $ref: '#/components/parameters/countTags' - $ref: '#/components/parameters/countWorkzones' responses: '200': description: List and content of the Projects content: application/json: schema: type: array items: $ref: '#/components/schemas/Project' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\n\n# Default: statsInfo includes all statistics\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects\" \\\n --header \"Authorization: Bearer $TOKEN\"\n\n# Disable all statistics for faster response\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects?countScans=false&countTags=false&countWorkzones=false\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\ntoken = \"...\"\n\n# Default: statsInfo includes all statistics\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/projects\"\n % (host, accountUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprojects = response.json()\nfor project in projects:\n print(project[\"name\"], project[\"statsInfo\"]) # {\"scanCount\": ..., ...}\n\n# Disable all statistics for faster response\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/projects\"\n % (host, accountUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token},\n params = { \"countScans\": \"false\", \"countTags\": \"false\", \"countWorkzones\": \"false\" }\n)\nprojects = response.json()\nfor project in projects:\n # statsInfo is null when all count* params are false\n print(project[\"name\"], project[\"statsInfo\"]) # None\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst token = \"...\";\n\n// Default: statsInfo includes all statistics\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects`;\nconst res = await fetch(url, {\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\nconst projects = await res.json();\nfor (const project of projects) {\n console.log(project.name, project.statsInfo); // { scanCount, scanSize, tagCount, workzoneCount }\n}\n\n// Disable all statistics for faster response\nconst params = new URLSearchParams({\n countScans: \"false\",\n countTags: \"false\",\n countWorkzones: \"false\",\n});\nconst urlFast = `${url}?${params}`;\nconst resFast = await fetch(urlFast, {\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\nconst projectsFast = await resFast.json();\nfor (const project of projectsFast) {\n // statsInfo is null when all count* params are false\n console.log(project.name, project.statsInfo); // null\n}\n" post: summary: Create Project operationId: createProject description: 'BETACreate a project. Requires the permission `account:projects:create` on the account. ' tags: - Project parameters: - $ref: '#/components/parameters/accountRef' requestBody: content: application/json: schema: type: object required: - name - subscriptionId properties: name: type: string minLength: 1 maxLength: 255 description: type: string nullable: true maxLength: 1000 subscriptionId: $ref: '#/components/schemas/SubscriptionRef' region: type: string nullable: true location: type: object nullable: true allOf: - $ref: '#/components/schemas/Location' cover: type: string nullable: true minLength: 1 maxLength: 255 spatialReference: type: object nullable: true allOf: - $ref: '#/components/schemas/SpatialReference' coordinatesTransformation: type: object nullable: true allOf: - $ref: '#/components/schemas/CoordinatesTransformationBody' responses: '201': description: The project was created successfully content: application/json: schema: $ref: '#/components/schemas/Project' '400': description: The subscription is not active content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorBadRequest' - type: object properties: errorCode: type: string description: '* `subscription-not-active` if the subscription is not active * `region-not-found` if the supplied region name is not known * `invalid-coordinates-transformation` if the selected transformation method does not have its corresponding parameters, or if a coordinates transformation is set without a spatial reference ' errorValues: type: object properties: subscriptionId: type: string description: Subscription ID for error code `subscription-not-active` examples: subscription-not-active: value: status: 400 title: Bad Request detail: Subscription is not active errorCode: subscription-not-active errorValues: subscriptionId: urn:cintoo:subscription:12345678-1234-4678-9234-123456789abc 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/projects\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"created with Wapi\",\n \"subscriptionId\": \"urn:cintoo:subscription:12345678-1234-4678-9234-123456789abc\",\n \"description\": \"Hello !\",\n \"region\": \"default\",\n \"location\": {\n \"lat\": 43.6554,\n \"lng\": 7.25\n }\n }'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nsubscriptionUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.post(\n \"https://%s/api/2/accounts/%s/projects\"\n % (host, accountUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"name\": \"created with Wapi\",\n \"subscriptionId\": \"urn:cintoo:subscription:%s\" % subscriptionUUID,\n \"description\": \"Hello !\",\n \"region\": \"default\",\n \"location\": {\n \"lat\": 43.6554,\n \"lng\": 7.25\n }\n }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst subscriptionUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects`;\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\": \"created with Wapi\",\n \"subscriptionId\": `urn:cintoo:subscription:${subscriptionUUID}`,\n \"description\": \"Hello !\",\n \"region\": \"default\",\n \"location\": {\n \"lat\": 43.6554,\n \"lng\": 7.25\n }\n }\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/accounts/{accountRef}/projects/{projectRef}: get: summary: Get Project operationId: getProject description: 'BETAGet a project details. Requires the permission `project:project:read` on the project. In other words, the requester MUST already be a member of the project at some level: - account owner, administrator, project manager or project lister - project creator or owner - be a contributor of the project, or be a member of a contributing group ' tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/countScans' - $ref: '#/components/parameters/countTags' - $ref: '#/components/parameters/countWorkzones' responses: '200': description: Content of the requested Project content: application/json: schema: $ref: '#/components/schemas/Project' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\n\n# Default: statsInfo includes all statistics\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID\" \\\n --header \"Authorization: Bearer $TOKEN\"\n\n# Disable scan statistics for faster response\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID?countScans=false\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\ntoken = \"...\"\n\n# Default: statsInfo includes all statistics\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/projects/%s\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n\n# Disable all statistics for faster response\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/projects/%s\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token},\n params = { \"countScans\": \"false\", \"countTags\": \"false\", \"countWorkzones\": \"false\" }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\n\n// Default: statsInfo includes all statistics\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}`;\nconst res = await fetch(url, {\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\nconsole.log(res.status);\nconst data1 = await res.json();\nconsole.log(data1);\n\n// Disable all statistics for faster response\nconst params = new URLSearchParams({\n countScans: \"false\",\n countTags: \"false\",\n countWorkzones: \"false\",\n});\nconst urlFast = `${url}?${params}`;\nconst resFast = await fetch(urlFast, {\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\nconsole.log(res.status);\nconst data2 = await res.json();\nconsole.log(data2);\n" delete: summary: Delete Project operationId: deleteProject description: 'BETADelete a project. Requires the permission `project:project:delete` on the project. (Note that permission `account:projects:delete` on the account implies the permission `project:project:delete` on all projects of the account). ' tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/permanentProjectDelete' responses: '204': description: The project was deleted successfully '400': description: The project is already deleted content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorBadRequest' - type: object properties: errorCode: type: string description: '* `project-deleted` if the project is already deleted. Add permanent flag to completely delete it. * `project-not-deleted` if asking for a permanent delete on a not deleted project. Delete it first. ' examples: project-deleted: value: status: 400 title: Bad Request detail: Project is deleted errorCode: project-deleted errorValues: projectId: '1234' project-not-deleted: value: status: 400 title: Bad Request detail: Project is not deleted yet errorCode: project-not-deleted errorValues: projectId: '1234' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\n\ncurl --request DELETE --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.delete(\n \"https://%s/api/2/accounts/%s/projects/%s\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}`;\nconst res = await fetch(url, {\n method: \"DELETE\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\n\nconsole.log(res.status);\nif (res.status !== 204) {\n const data = await res.json();\n console.log(data);\n}\n" put: summary: Update Project operationId: updateProject description: "BETAUpdate a Project. \n\n⚠ Overwrites all fields. Missing fields will be considered as null and current values will be erased\n\nPermissions:\n- To update everything: be the account owner, administrator, or project owner\n- To update everything EXCEPT the subscription and the owner: have the \"Update, delete or restore projects\" permission on the project\n- When updating the owner of a project, the new owner MUST be a project manager\n" tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/countScans' - $ref: '#/components/parameters/countTags' - $ref: '#/components/parameters/countWorkzones' requestBody: content: application/json: schema: type: object required: - name - description - subscriptionId - ownerId - location - coverBlobName - spatialReference properties: name: type: string example: New name for my project minLength: 1 maxLength: 255 description: type: string nullable: true maxLength: 1000 example: This is a really interesting project subscriptionId: $ref: '#/components/schemas/SubscriptionRef' ownerId: $ref: '#/components/schemas/UserRef' location: type: object nullable: true allOf: - $ref: '#/components/schemas/Location' coverBlobName: type: string nullable: true allOf: - $ref: '#/components/schemas/BlobName' spatialReference: type: object nullable: true allOf: - $ref: '#/components/schemas/SpatialReference' coordinatesTransformation: type: object nullable: true allOf: - $ref: '#/components/schemas/CoordinatesTransformationBody' responses: '200': description: The project was updated successfully content: application/json: schema: $ref: '#/components/schemas/Project' '400': description: Cannot update subscription because capacity is exceeded content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorBadRequest' - type: object properties: errorCode: type: string description: '* `capacity-exceeded-scan`, `capacity-exceeded-geoimage`, `capacity-exceeded-tag` if the target subscription cannot accept the project due to a capacity exceeded, respectively of Scan, GeoImage, or Tag * `new-project-owner-not-manager` the new owner of a project needs to be a project manager * `invalid-coordinates-transformation` if the selected transformation method does not have its corresponding parameters, or if a coordinates transformation is set without a spatial reference ' errorValues: type: object properties: subscriptionId: type: string description: target subscription ID for error codes `capacity-exceeded-xxx` examples: capacity-exceeded-scan: value: status: 400 title: Bad Request detail: not enough Scan capacity to accept project on subscription 1234 errorCode: capacity-exceeded-scan '403': description: Update project ownership or subscription forbidden, or New owner must be a Project Manager content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorForbidden' - type: object properties: errorCode: type: string description: '* `update-project-ownership-or-subscription-forbidden` * `new-project-owner-not-manager` ' examples: update-project-ownership-or-subscription-forbidden: value: status: 403 title: Forbidden detail: You do not have the permission to update project ownership or subscription. It requires to be Project Owner, or Administrator errorCode: update-project-ownership-or-subscription-forbidden new-project-owner-not-manager: value: status: 403 title: Forbidden detail: New owner must be a Project Manager errorCode: new-project-owner-not-manager 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\n\ncurl --request PUT --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"Better name\",\n \"description\": \"I love this name more\"\n }'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.put(\n \"https://%s/api/2/accounts/%s/projects/%s\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"name\": \"Better name\",\n \"description\": \"I love this name more\"\n }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}`;\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 \"name\": \"Better name\",\n \"description\": \"I love this name more\"\n }\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" patch: summary: Patch Project operationId: patchProject description: "BETAPatch a Project. \n\nⓘ Unlike the PUT operation (Update a project), the patch updates only the provided fields.\n\nPermissions:\n- To update everything: be the account owner, administrator, or project owner\n- To update everything EXCEPT the subscription and the owner: have the \"Update, delete or restore projects\" permission on the project\n- When updating the owner of a project, the new owner MUST be a project manager\n" tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/countScans' - $ref: '#/components/parameters/countTags' - $ref: '#/components/parameters/countWorkzones' requestBody: content: application/json: schema: type: object properties: name: type: string example: New name for my project minLength: 1 maxLength: 255 description: type: string nullable: true maxLength: 1000 example: This is a really interesting project subscriptionId: $ref: '#/components/schemas/SubscriptionRef' ownerId: $ref: '#/components/schemas/UserRef' location: type: object nullable: true allOf: - $ref: '#/components/schemas/Location' coverBlobName: type: string nullable: true allOf: - $ref: '#/components/schemas/BlobName' spatialReference: type: object nullable: true allOf: - $ref: '#/components/schemas/SpatialReference' coordinatesTransformation: type: object nullable: true allOf: - $ref: '#/components/schemas/CoordinatesTransformationBody' responses: '200': description: The project was updated successfully content: application/json: schema: $ref: '#/components/schemas/Project' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\n\ncurl --request PATCH --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\": \"Better name\",\n \"description\": \"I love this name more\"\n }'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.patch(\n \"https://%s/api/2/accounts/%s/projects/%s\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"name\": \"Better name\",\n \"description\": \"I love this name more\"\n }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}`;\nconst res = await fetch(url, {\n method: \"PATCH\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(\n {\n \"name\": \"Better name\",\n \"description\": \"I love this name more\"\n }\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/accounts/{accountRef}/projects/{projectRef}/cover: post: summary: Get a signed URL for project cover file upload operationId: signProjectCoverURL description: "BETAGet a signed URL for project cover file upload\n\nRequires the permission `projects:project:update-details`.\n\nAfter this call, use the `url`s from the response to upload the cover file.\n\nRequired headers to push the files\n* `Content-MD5: xxx` with `xxx` being a base 64 encode of the md5sum in binary format.\\\n Example: `MD5SUM=\"$(openssl md5 -binary < \"$FILENAME\" | base64)\"`\n* `Cache-Control: max-age=2592000`\n* `x-ms-blob-type: BlockBlob` mandatory if the storage type is Azure. \\\n Note: always adding the `x-ms-blob-type` could be a good idea as Aws ignores it anyway.\n" tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' requestBody: content: application/json: schema: type: object required: - name - extension - size - md5 properties: name: type: string extension: type: string enum: - png - jpg - jpeg size: type: integer format: int64 description: Size of the file (bytes) minimum: 1 maximum: 10485760 md5: type: string description: The md5 sum-check of the file responses: '200': description: The signing process succeeded content: application/json: schema: type: object required: - provider - expiresIn - file properties: provider: type: string expiresIn: type: integer description: After this amount of seconds, the upload link won't be available anymore file: type: object required: - name - extension - size - md5 - url properties: name: type: string extension: type: string size: type: integer format: int64 description: Size of the file (bytes) md5: type: string description: The md5 sum-check of the file url: type: string description: the url to which upload the file 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTID=...\nexport PROJECTID=...\n\ncurl --request POST --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTID/projects/$PROJECTID/cover\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\":\"cover.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\"\n }'\n\n# -- UPLOAD OF THE FILE --\n\n# the url received in the body of the response\nexport URL=...\nexport FILENAME=...\n\nMD5SUM=\"$(openssl md5 -binary < \"$FILENAME\" | base64)\"\ncurl --request PUT --url \"$URL\" --header \"Content-Type: application/json\" -T \"$FILENAME\" -H \"Content-MD5: ${MD5SUM}\" -H \"Cache-Control: max-age=2592000\" -H \"x-ms-blob-type: BlockBlob\" -i\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountID = \"...\"\nprojectID = \"...\"\ntoken = \"...\"\n\nresponse = requests.post(\n \"https://%s/api/2/accounts/%s/projects/%s/cover\"\n % (host, accountID, projectID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\"\n }\n)\nprint(response.status_code)\nprint(response.json())\n\nimport base64\nimport hashlib\n\n# the url received in the body of the response\nexport url=...\nexport filename=...\n\nhash_md5 = hashlib.md5()\nwith open(filename, \"rb\") as fin:\n for chunk in iter(lambda: fin.read(4096), b\"\"):\n hash_md5.update(chunk)\ndigest = hash_md5.digest()\nmd5 = base64.b64encode(digest).decode(\"utf-8\")\n\nheaders = {\n \"Content-MD5\": md5,\n \"Cache-Control\": \"max-age=2592000\",\n \"x-ms-blob-type\": \"BlockBlob\", # mandatory if storage type is azure\n}\ndata = open(filename, \"rb\")\nr = requests.put(url, data=data, headers=headers)\nprint(r.status_code)\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountId = \"...\";\nconst projectId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountId}/projects/${projectId}/cover`;\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\":\"cover.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\",\n }\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" put: summary: Update cloud file as cover for project operationId: updateProjectCover description: 'BETAUpdate the cover for the project Requires the permission `projects:project:update-details` This actually adds an already uploaded file as cover for a project ' tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' requestBody: content: application/json: schema: type: object required: - name - extension - size - md5 properties: name: type: string extension: type: string enum: - png - jpg - jpeg size: type: integer format: int64 description: Size of the file (bytes) minimum: 1 maximum: 10485760 md5: type: string description: The md5 sum-check of the file responses: '200': description: the cover has been updated content: application/json: schema: type: object required: - name - extension - size - md5 - id properties: name: type: string extension: type: string size: type: integer format: int64 description: Size of the file (bytes) md5: type: string description: The md5 sum-check of the file id: $ref: '#/components/schemas/FileUrn' description: the unique id of the file in the Cintoo Platform 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTID=...\nexport PROJECTID=...\n\ncurl --request PUT --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTID/projects/$PROJECTID/cover\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\"\n }'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountID = \"...\"\nprojectID = \"...\"\ntoken = \"...\"\n\nresponse = requests.put(\n \"https://%s/api/2/accounts/%s/projects/%s/cover\"\n % (host, accountID, projectID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"name\":\"tumbleweed.png\",\n \"extension\":\"png\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\"\n }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountId = \"...\";\nconst projectId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountId}/projects/${projectId}/cover`;\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 \"name\":\"tumbleweed.png\",\n \"extension\":\"png\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\"\n }\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/accounts/{accountRef}/projects/{projectRef}/restore: put: summary: Restore project operationId: restoreProject description: 'BETARestore a deleted project. Requires the permission `project:project:delete` on the project. (Note that permission `account:projects:delete` on the account implies the permission `project:project:delete` on all projects of the account). Error management: If the subscription used by this project does not have enough capacity to restore it, a 400 error is returned with a message, like "Target subscription does not have enough Scan capacity to accept project" ' tags: - Project parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/countScans' - $ref: '#/components/parameters/countTags' - $ref: '#/components/parameters/countWorkzones' responses: '200': description: The project was restored successfully content: application/json: schema: $ref: '#/components/schemas/Project' '400': description: The project is not deleted, or the subscription is not active, or subscription capacity exceeded content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorBadRequest' - type: object properties: errorCode: type: string description: '* `project-active` if the project is not deleted * `subscription-not-active` if the subscription is not active * `capacity-exceeded-scan`, `capacity-exceeded-geoimage`, `capacity-exceeded-tag` if the target subscription cannot accept the project due to a capacity exceeded, respectively of Scan, GeoImage, or Tag ' errorValues: type: object properties: projectId: type: string description: Project ID for error code `project-active` subscriptionId: type: string description: Subscription ID for error code `subscription-not-active` or `capacity-exceeded-xxx` examples: project-active: value: status: 400 title: Bad Request detail: Project is active errorCode: project-active errorValues: projectId: '1234' subscription-not-active: value: status: 400 title: Bad Request detail: Subscription is not active errorCode: subscription-not-active errorValues: subscriptionId: '1234' capacity-exceeded-scan: value: status: 400 title: Bad Request detail: not enough Scan capacity to accept project on subscription 1234 errorCode: capacity-exceeded-scan errorValues: subscriptionId: '1234' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\n\ncurl --request PUT --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/restore\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.put(\n \"https://%s/api/2/accounts/%s/projects/%s/restore\"\n % (host, accountUUID, projectUUID),\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 projectUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/restore`;\nconst res = await fetch(url, {\n method: \"PUT\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/values/spatial-references: get: summary: List Spatial References operationId: listSpatialReferences description: BETAList official Spatial References from https://spatialreference.org/ tags: - Project responses: '200': description: List of Spatial References content: application/json: schema: type: array items: $ref: '#/components/schemas/SpatialReferenceValue' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\n\ncurl --url \"https://aec.cintoo.com/api/2/values/spatial-references\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\ntoken = \"...\"\n\nresponse = requests.get(\n \"https://%s/api/2/values/spatial-references\" % host,\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/values/spatial-references`;\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" components: schemas: ProjectUrn: type: string description: '"urn:cintoo:project:" followed by an UUIDv4 ' UserId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 SpatialReferenceValue: type: object required: - authName - code - deprecated - name - type properties: authName: type: string description: The authority defining the used code (IGNF, NKG, OGC, IAU_2015, EPSG, ESRI) code: type: string description: The code of the geographic reference to be used for this project deprecated: type: boolean description: If true, the spatialReference cannot be used to define any project anymore (only available for already settled projects) name: type: string description: Description about the location of the SpatialReference type: type: string description: The kind of Coordinate Reference System. SubscriptionRef: oneOf: - $ref: '#/components/schemas/SubscriptionUrn' - $ref: '#/components/schemas/SubscriptionId' 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' Location: type: object required: - lat - lng properties: lat: type: number format: double minimum: -90 maximum: 90 lng: type: number format: double minimum: -180 maximum: 180 AccountId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 SubscriptionUrn: type: string description: '"urn:cintoo:subscription:" followed by an UUIDv4 ' WorkzoneUrn: type: string pattern: ^urn:cintoo:workzone:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ description: '"urn:cintoo:workzone:" followed by an UUIDv4 ' ErrorForbidden: type: object required: - status - title properties: status: type: integer format: int32 enum: - 403 title: type: string enum: - Forbidden detail: type: string description: human readable description of the error in english AccountUrn: type: string description: '"urn:cintoo:account:" followed by an UUIDv4 ' SimilarityTransformation: type: object required: - ordinate1 - ordinate2 - scaleFactor - rotationAngle properties: ordinate1: type: number format: double description: 'Translation in the first axis (unit: meter, precision: 3 decimal places)' ordinate2: type: number format: double description: 'Translation in the second axis (unit: meter, precision: 3 decimal places)' scaleFactor: type: number format: double description: 'Uniform scale factor on all axes (unit: coefficient, precision: 9 decimal places)' rotationAngle: type: number format: double description: 'Rotation angle around the up axis (unit: degree, precision: 9 decimal places)' FileUrn: type: string description: '"urn:cintoo:file:" followed by an UUIDv4 ' ModificationInfo: type: object required: - createdBy - isDeleted properties: createdAt: type: string allOf: - $ref: '#/components/schemas/DateTime' createdBy: $ref: '#/components/schemas/UserUrn' updatedAt: type: string allOf: - $ref: '#/components/schemas/DateTime' updatedBy: type: string allOf: - $ref: '#/components/schemas/UserUrn' deletedAt: type: string allOf: - $ref: '#/components/schemas/DateTime' deletedBy: type: string allOf: - $ref: '#/components/schemas/UserUrn' isDeleted: type: boolean BlobName: type: string description: "A `BlobName`: the actual filename of the file in the blob storage.\n\nTo retrieve a blob, two methods are available:\n- using the unitary endpoint [Download a blob](#tag/Project/operation/getBlob), which will automatically forward\n to the final URL, which is a pre-signed URL, expiring after 3 hours by default.\n- using the bulk endpoint [Get pre-signed urls for multiple blobs](#tag/Project/operation/getBlobs), which will\n return the list of pre-signed URLs.\n\nWhile the first option is the easiest, as it forwards automatically to the final URL transparently,\nthe second option should be preferred as much as possible to improve performances.\n" 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 SpatialReference: type: object required: - authName - code properties: authName: type: string minLength: 1 maxLength: 128 description: The authority defining the used code (IGNF, NKG, OGC, IAU_2015, EPSG, ESRI) code: type: string minLength: 1 maxLength: 128 description: The code of the geographic reference to be used for this project Project: type: object required: - id - type - api1Id - accountId - subscriptionId - isdemo - region - name - description - ownerId - location - modificationInfo - rootWorkzoneId - permissions - bimOnRootWz x-tags: - Project properties: id: readOnly: true $ref: '#/components/schemas/ProjectUrn' type: type: string enum: - project accountId: $ref: '#/components/schemas/AccountUrn' subscriptionId: $ref: '#/components/schemas/SubscriptionUrn' isdemo: type: boolean region: type: string description: Region.Id (can be found in accounts.regions.id) hosting the project data example: default name: type: string description: Named displayed for the project example: New Project description: type: string ownerId: $ref: '#/components/schemas/UserUrn' location: $ref: '#/components/schemas/Location' modificationInfo: $ref: '#/components/schemas/ModificationInfo' statsInfo: type: object allOf: - $ref: '#/components/schemas/ProjectStatsInfo' coverBlobName: type: string allOf: - $ref: '#/components/schemas/BlobName' coverUrl: type: string allOf: - $ref: '#/components/schemas/Url' rootWorkzoneId: $ref: '#/components/schemas/WorkzoneUrn' spatialReference: type: object allOf: - $ref: '#/components/schemas/SpatialReferenceProject' coordinatesTransformation: type: object allOf: - $ref: '#/components/schemas/CoordinatesTransformation' permissions: type: array items: description: list of permissions at project level, for the user doing the request. type: string bimOnRootWz: type: boolean description: 'Indicates whether the requesting user has the BIM role on the root workzone of this project. - `true`: the user has the BIM role on the root workzone - `false`: the user does not have the BIM role on the root workzone (also when the user lacks permission to compute it) ' CoordinatesTransformationBody: type: object required: - type properties: type: type: string nullable: true enum: - affine - similarity description: 'The active transformation method. When null, no transformation is active. Both `affine` and `similarity` blocks may be present simultaneously (to preserve user input when switching methods), but only the one indicated by `type` is active. ' affine: type: object nullable: true allOf: - $ref: '#/components/schemas/AffineTransformation' similarity: type: object nullable: true allOf: - $ref: '#/components/schemas/SimilarityTransformation' SubscriptionId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 ProjectStatsInfo: type: object description: 'Statistics about the project. By default all fields are included. Use the query parameters `countScans`, `countTags`, and `countWorkzones` to control which fields are returned. When all query parameters are set to `false`, `statsInfo` is `null`. **Upcoming change:** In a future release, all `count*` query parameters will default to `false`, meaning `statsInfo` will be `null` by default. Clients that need statistics should start passing the desired `count*` parameters explicitly set to `true`. ' properties: scanCount: type: integer scanSize: type: integer tagCount: type: integer workzoneCount: type: integer description: Number of workzones in a project (includes root workzone) ProjectId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 Url: type: string format: uri description: Link that will redirect to 302 signed link to download the corresponding file. Uuid: type: string description: UUIDv4 format: uuid example: 156fff1a-0ef7-4335-891a-627928a19e29 UserRef: oneOf: - $ref: '#/components/schemas/UserUrn' - $ref: '#/components/schemas/UserId' CoordinatesTransformation: type: object required: - type properties: type: type: string nullable: true enum: - affine - similarity description: 'The active transformation method. When null, no transformation is active. Both `affine` and `similarity` blocks may be present simultaneously (to preserve user input when switching methods), but only the one indicated by `type` is active. ' affine: type: object nullable: true allOf: - $ref: '#/components/schemas/AffineTransformation' similarity: type: object nullable: true allOf: - $ref: '#/components/schemas/SimilarityTransformation' AffineTransformation: type: object required: - a0 - a1 - a2 - b0 - b1 - b2 properties: a0: type: number format: double description: 'Translation for the first output ordinate (unit: meter, precision: 3 decimal places)' a1: type: number format: double description: 'First output ordinate coefficient for the first input ordinate (unit: coefficient, precision: 9 decimal places)' a2: type: number format: double description: 'First output ordinate coefficient for the second input ordinate (unit: coefficient, precision: 9 decimal places)' b0: type: number format: double description: 'Translation for the second output ordinate (unit: meter, precision: 3 decimal places)' b1: type: number format: double description: 'Second output ordinate coefficient for the first input ordinate (unit: coefficient, precision: 9 decimal places)' b2: type: number format: double description: 'Second output ordinate coefficient for the second input ordinate (unit: coefficient, precision: 9 decimal places)' SpatialReferenceProject: type: object required: - authName - code properties: authName: type: string description: The authority defining the used code (IGNF, NKG, OGC, IAU_2015, EPSG, ESRI) code: type: string description: The code of the geographic reference to be used for this project 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 parameters: countTags: name: countTags in: query required: false description: 'If true, includes `tagCount` in the `statsInfo` field of the response. If false, this field will not be included in `statsInfo`. **Upcoming change:** The default value will change from `true` to `false` in a future release. Clients that rely on `tagCount` should start passing `countTags=true` explicitly. ' schema: type: boolean default: true countScans: name: countScans in: query required: false description: 'If true, includes `scanCount` and `scanSize` in the `statsInfo` field of the response. If false, these fields will not be included in `statsInfo`. **Upcoming change:** The default value will change from `true` to `false` in a future release. Clients that rely on `scanCount` or `scanSize` should start passing `countScans=true` explicitly. ' schema: type: boolean default: true permanentProjectDelete: name: permanent in: query required: false description: Delete Permanently a project schema: type: boolean 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' projectRef: name: projectRef in: path required: true description: The Id or Urn of the project schema: oneOf: - $ref: '#/components/schemas/ProjectUrn' - $ref: '#/components/schemas/ProjectId' countWorkzones: name: countWorkzones in: query required: false description: 'If true, includes `workzoneCount` in the `statsInfo` field of the response. If false, this field will not be included in `statsInfo`. **Upcoming change:** The default value will change from `true` to `false` in a future release. Clients that rely on `workzoneCount` should start passing `countWorkzones=true` explicitly. ' schema: type: boolean default: true 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