openapi: 3.0.3 info: version: 2.0.0 title: Cintoo Open Account File 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: File paths: /api/2/accounts/{accountRef}/projects/{projectRef}/files: get: summary: Get files operationId: getFiles description: 'BETAget all files in project. This endpoint accepts a "category" parameter to restrain the categories of the files that will be listed. Permissions: - the user must have permission `workzone:workzones:read` in work zones in which you can list files. ' tags: - File parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/categoryFilter' responses: '200': description: List of files for this project content: application/json: schema: type: array items: $ref: '#/components/schemas/File' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/files\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/projects/%s/files\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token}\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}/files`;\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" /api/2/accounts/{accountRef}/projects/{projectRef}/files/{fileRef}: patch: summary: Update a file name operationId: updateFileName description: "Update the name of a file.\n\nRequires write permission on the file workzone:\n * `workzone:reality-data:write` for scans/geo-images/site maps\n * `workzone:cad-model:write` for models\n * `workzone:model-reports:write` for model reports\n * `workzone:documents:write` for documents/media/misc/archive\n * `workzone:video3d:write` for video 360\n * `workzone:workzones:write` for other file types\n" tags: - File parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/fileRef' requestBody: content: application/json: schema: $ref: '#/components/schemas/fileUpdate' responses: '200': description: The updated file content: application/json: schema: $ref: '#/components/schemas/File' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport FILEUUID=...\n\ncurl --request PATCH --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/files/$FILEUUID\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"filename\": \"updated-name.jpg\"\n }'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nfileUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.patch(\n \"https://%s/api/2/accounts/%s/projects/%s/files/%s\"\n % (host, accountUUID, projectUUID, fileUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = {\n \"filename\": \"updated-name.jpg\"\n }\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst fileUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/files/${fileUUID}`;\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 filename: \"updated-name.jpg\",\n }),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/accounts/{accountRef}/projects/{projectRef}/files/bulk-transformation: post: summary: Update the position and/or rotation of a scan, model, geoImage or video3d operationId: UpdateBulkFilesTransformation description: 'BETAUpdate the position, rotation and scale for a list of files, with the following restrictions: - the scan, model and geoImage files accept update of only the position and rotation. - the video3d files accept update of all three fields. Required permissions depend on the type of the files being transformed: - scan files: `workzone:reality-data:transform` - model files: `workzone:cad-model:transform` - geoImage files: `workzone:geoimages:transform` - video3d files: `workzone:video3d:transform` ' tags: - File parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' requestBody: content: application/json: schema: $ref: '#/components/schemas/filesTransformationUpdate' responses: '200': description: 'The files are successfully updated. The response returns the updated files information. ' content: application/json: schema: type: array items: $ref: '#/components/schemas/File' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/files/bulk-transformation\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '[\n {\n \"id\": \"...\",\n \"position\": {\"x\": 1., \"y\": 2., \"z\": 3.},\n \"rotation\": {\"x\": 4., \"y\": 5., \"z\": 6., \"w\": 7.}\n }\n ]'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.post(\n \"https://%s/api/2/accounts/%s/projects/%s/files/bulk-transformation\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token},\n json = [\n {\n \"id\": \"...\",\n \"position\": {\"x\": 1., \"y\": 2., \"z\": 3.},\n \"rotation\": {\"x\": 4., \"y\": 5., \"z\": 6., \"w\": 7.}\n }\n ]\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\nconst payload = [\n {\n id: \"...\",\n position: { x: 1, y: 2, z: 3 },\n rotation: { x: 4, y: 5, z: 6, w: 7 },\n },\n];\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/files/bulk-transformation`;\nconst res = await fetch(url, {\n method: \"POST\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify(payload),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/accounts/{accountRef}/projects/{projectRef}/blobs/{blobRef}: get: summary: Download a blob operationId: getBlob description: Download a blob, via a redirection to pre-signed URL tags: - File parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - name: blobRef in: path required: true schema: type: string description: a blob ref -> `blob` attribute in File schema example: 1f74af182236bd4e5df2c3f18f3d94fe.png responses: '302': description: Redirection to a pre-signed download link, in the Location header 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport BLOBID=...\n\ncurl --location \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/blobs/$BLOBID\" \\\n --header \"Authorization: Bearer $TOKEN\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nblobId = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n \"https://%s/api/2/accounts/%s/projects/%s/blobs/%s\"\n % (host, accountUUID, projectUUID, blobId),\n headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nwith open(blobId, mode='wb') as localfile:\n localfile.write(response.content)\n" - lang: TypeScript source: "import { writeFile } from \"node:fs/promises\";\n\n\n const host = \"aec.cintoo.com\";\n const accountUUID = \"...\";\n const projectUUID = \"...\";\n const blobId = \"...\";\n const token = \"...\";\n\n const url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/blobs/${blobId}`;\n const res = await fetch(url, {\n redirect: \"follow\",\n headers: {\n \"Authorization\": `Bearer ${token}`,\n },\n });\n\n console.log(res.status);\n const fileBuffer = Buffer.from(await res.arrayBuffer());\n await writeFile(blobId, fileBuffer);\n" /api/2/accounts/{accountRef}/projects/{projectRef}/blobs: post: summary: Get pre-signed urls for multiple blobs operationId: getBlobs description: Get pre-signed urls for multiple blobs. tags: - File parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' requestBody: content: application/json: schema: type: array items: type: string description: list of blob refs -> `blob` attribute in File schema example: 1f74af182236bd4e5df2c3f18f3d94fe.png responses: '200': description: Pre-signed urls to the requested blobs content: application/json: schema: type: object required: - expiresIn - urls properties: expiresIn: description: validity duration of urls, in seconds type: integer urls: description: map associating each blob ref to its pre-signed download link type: object additionalProperties: $ref: '#/components/schemas/Url' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport BLOBID=...\n\ncurl --request POST --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/blobs\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data \"[ \\\"$BLOBID\\\" ]\"\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nblobId = \"...\"\ntoken = \"...\"\n\nresponse = requests.post(\n \"https://%s/api/2/accounts/%s/projects/%s/blobs\"\n % (host, accountUUID, projectUUID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = [ blobId ]\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\nconst blobId = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/blobs`;\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 [ blobId ]\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/accounts/{accountRef}/projects/{projectRef}/workzones/{workzoneRef}/bulk-files: post: summary: Get a signed URL for cloud file upload operationId: signUploadURL description: "BETAGet a signed URL for cloud file upload\n\nRequires the permission `workzone:documents:write` and/or `workzone:reality-data:write` on the workzone, depending on the file types\n\nAfter this call, use the `url`s from the response to upload the files.\nNote that there are examples on how to upload the data after calling the endpoints in the example section.\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: - File parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/workzoneRef' requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/bulk-files' responses: '200': description: The signing process succeeded content: application/json: schema: type: object properties: provider: type: string expiresIn: type: integer files: type: array items: type: object properties: name: type: string extension: type: string size: type: integer format: int64 md5: type: string url: type: string blobName: $ref: '#/components/schemas/BlobName' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTID=...\nexport PROJECTID=...\nexport WORKZONEID=...\n\ncurl --request POST --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTID/projects/$PROJECTID/workzones/$WORKZONEID/bulk-files\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '[\n {\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\",\n \"isAttachment\": false\n }\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 = \"...\"\nworkzoneID = \"...\"\ntoken = \"...\"\n\nresponse = requests.post(\n \"https://%s/api/2/accounts/%s/projects/%s/workzones/%s/bulk-files\"\n % (host, accountID, projectID, workzoneID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = [\n {\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\",\n \"isAttachment\": false\n }\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: "\nconst host = \"aec.cintoo.com\";\nconst accountId = \"...\";\nconst projectId = \"...\";\nconst workzoneId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountId}/projects/${projectId}/workzones/${workzoneId}/bulk-files`;\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 {\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\",\n \"isAttachment\": false\n }\n ]\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" put: summary: Register cloud files on a workzone operationId: registerFiles description: 'BETARegister cloud files on a workzone Requires the permission `workzone:documents:write` and/or `workzone:reality-data:write` in the work zone, depending on the file types This actually adds an already uploaded file in a work zone, so that it appears in the file browser ' tags: - File parameters: - $ref: '#/components/parameters/accountRef' - $ref: '#/components/parameters/projectRef' - $ref: '#/components/parameters/workzoneRef' requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/bulk-files' responses: '200': description: the files have been correctly registered content: application/json: schema: type: array items: type: object properties: name: type: string extension: type: string size: type: integer format: int64 md5: type: string id: $ref: '#/components/schemas/FileUrn' blobName: $ref: '#/components/schemas/BlobName' 4XX: $ref: '#/components/responses/UnexpectedError' x-codeSamples: - lang: cURL source: "export TOKEN=...\nexport ACCOUNTID=...\nexport PROJECTID=...\nexport WORKZONEID=...\n\ncurl --request PUT --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTID/projects/$PROJECTID/workzones/$WORKZONEID/bulk-files\" \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --header \"Content-Type: application/json\" \\\n --data '[\n {\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\",\n \"isAttachment\": false\n }\n ]'\n" - lang: Python source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountID = \"...\"\nprojectID = \"...\"\nworkzoneID = \"...\"\ntoken = \"...\"\n\nresponse = requests.put(\n \"https://%s/api/2/accounts/%s/projects/%s/workzones/%s/bulk-files\"\n % (host, accountID, projectID, workzoneID),\n headers = { \"Authorization\": \"Bearer %s\" % token },\n json = [\n {\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\",\n \"isAttachment\": false\n }\n ]\n)\nprint(response.status_code)\nprint(response.json())\n" - lang: TypeScript source: "\nconst host = \"aec.cintoo.com\";\nconst accountId = \"...\";\nconst projectId = \"...\";\nconst workzoneId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountId}/projects/${projectId}/workzones/${workzoneId}/bulk-files`;\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 {\n \"name\":\"tumbleweed.gif\",\n \"extension\":\"gif\",\n \"size\":448459,\n \"md5\":\"da04845eaedb7db7f5b6f32c4076821f\",\n \"isAttachment\": false\n }\n ]\n ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n" /api/2/values/formats: get: summary: List file formats operationId: listFormats description: BETAList supported file formats tags: - File responses: '200': description: List of file formats content: application/json: schema: type: array items: $ref: '#/components/schemas/FileFormat' 4XX: $ref: '#/components/responses/UnexpectedError' components: schemas: ProjectUrn: type: string description: '"urn:cintoo:project:" followed by an UUIDv4 ' FileFormat: type: object x-tags: - File required: - id - name - description - extension - icon - canBeUploaded - shareUrlType - categoryName - categoryDescription - categoryType properties: id: $ref: '#/components/schemas/FormatId' name: type: string description: type: string extension: type: string icon: type: string canBeUploaded: type: boolean shareUrlType: type: string categoryName: type: string categoryDescription: type: string categoryType: type: string FileTransformable: type: object properties: translation: type: object allOf: - $ref: '#/components/schemas/Vector3D' description: 'A vector representing the position in the Workzone, with three components in meter: `x`, `y` and `z` ' nullable: true rotation: type: object allOf: - $ref: '#/components/schemas/Quaternion' description: 'A quaternion representing the rotation, with the pivot point being its current position defined by translation. It has four components: `x`, `y`, `z` and `w` ' nullable: true scale: type: object allOf: - $ref: '#/components/schemas/Vector3D' description: 'A vector representing a scale deformation along the three axis with three ratio components : `x`, `y` and `z` ' nullable: true FileCategoryModelReport: type: string enum: - modelReport description: 'Model report files: `.cipm`' File: type: object x-tags: - File oneOf: - $ref: '#/components/schemas/Archive' - $ref: '#/components/schemas/Document' - $ref: '#/components/schemas/Gaussian' - $ref: '#/components/schemas/GeoImage' - $ref: '#/components/schemas/Media' - $ref: '#/components/schemas/MiscFile' - $ref: '#/components/schemas/Model' - $ref: '#/components/schemas/ModelReport' - $ref: '#/components/schemas/Scan' - $ref: '#/components/schemas/SiteMap' - $ref: '#/components/schemas/Video3d' discriminator: propertyName: type mapping: archive: '#/components/schemas/Archive' document: '#/components/schemas/Document' gaussian: '#/components/schemas/Gaussian' geoImage: '#/components/schemas/GeoImage' media: '#/components/schemas/Media' miscfile: '#/components/schemas/MiscFile' model: '#/components/schemas/Model' modelReport: '#/components/schemas/ModelReport' scan: '#/components/schemas/Scan' sitemap: '#/components/schemas/SiteMap' video3d: '#/components/schemas/Video3d' FileCategoryModel: type: string enum: - model description: 'Model files: `.3ds`, `.dae`, `.dxf`, `.ifc`, `.dwg`, `.rvt`, etc.' 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' Video3d: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategoryVideo3d' FileCategoryDocument: type: string enum: - document description: 'Document files: `.doc[x]`, `.xls[x]`, `.ppt[x]`, `.txt`, `.rtf`, `.odt`, `.pdt`, `.pub`, `.csv`' Gaussian: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - $ref: '#/components/schemas/FileImported' - $ref: '#/components/schemas/FilePlaced' - $ref: '#/components/schemas/FileScaled' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategoryGaussian' src: $ref: '#/components/schemas/FileSrcGaussian' Quaternion: type: object required: - x - y - z - w properties: x: type: number format: float y: type: number format: float z: type: number format: float w: type: number format: float FileSrcGaussian: type: object required: - version - name - pipelineSha - numberOfSplats - training properties: version: type: string description: Version of the splatting format example: '1' name: type: string description: Name of the splatting example: splatting pipelineSha: type: string description: SHA hash of the pipeline used to generate the splatting example: 524ebd1c8d8a2ecdbc8b47d18cab116ac8b28ae7 numberOfSplats: type: integer description: Total number of gaussian splats in the file example: 2497204 training: type: object required: - backend - evalMetrics properties: backend: type: string description: Training backend used example: brush evalMetrics: type: object required: - psnr - ssim properties: psnr: type: number format: double description: Peak Signal-to-Noise Ratio metric example: 24.12155 ssim: type: number format: double description: Structural Similarity Index metric example: 0.8322978 FileBlob: type: object required: - blob - blobName - url properties: blob: type: string deprecated: true description: use `blobName` instead. `blob` will be removed the 1st of november 2025 allOf: - $ref: '#/components/schemas/BlobName' blobName: $ref: '#/components/schemas/BlobName' url: $ref: '#/components/schemas/Url' FileId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 AccountId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 FileCategoryVideo3d: type: string enum: - video3d description: 'Video3d files: `.mp4`' Dimension2d: type: object required: - w - h properties: w: type: integer h: type: integer WorkzoneId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 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 ' GeoImage: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - $ref: '#/components/schemas/FileImported' - $ref: '#/components/schemas/FilePlaced' - type: object required: - type - resolution - urlPreview - panoramaWidth - panoramaHeight properties: type: $ref: '#/components/schemas/FileCategoryGeoImage' resolution: type: object allOf: - $ref: '#/components/schemas/Dimension2d' description: 'The image''s resolution: has a `w` and a `h`, respectively for *width* and *height*. This is not the same as `PanoramaWidth` and `PanoramaHeight` ' scanInfo: type: string blobPreview: type: string allOf: - $ref: '#/components/schemas/BlobName' urlPreview: type: string allOf: - $ref: '#/components/schemas/Url' panoramaWidth: type: number format: int description: The image's *width*, in pixels panoramaHeight: type: number format: int description: The image's *height*, in pixels src: type: object description: Contains metadata usable by the Cintoo Viewer properties: idd: type: object properties: scan_id: type: string scan_guid: type: string description: Optional external scan identifier, carried over from the import CSV. idd_type: type: string example: Corrosion fileStatus: type: string enum: - pending - success - failure description: Cloud import job status of this IDD image (absent for legacy Connect imports, treated as success). FileCategoryMiscFile: type: string enum: - miscfile description: Any other type of files Document: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategoryDocument' FileCategoryGaussian: type: string enum: - gaussian description: 'Gaussian Splatting files: `.ply`, `.spz`' FileCategoryArchive: type: string enum: - archive description: 'Archive files: `zip`' Scan: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - $ref: '#/components/schemas/FileImported' - $ref: '#/components/schemas/FileTransformable' - type: object required: - type - translation - rotation - resolution - urlPreview - panoramaWidth - panoramaHeight properties: translation: {} rotation: {} type: $ref: '#/components/schemas/FileCategoryScan' resolution: type: object allOf: - $ref: '#/components/schemas/Dimension2d' description: 'The scan''s resolution: has a `w` and a `h`, respectively for *width* and *height*. This is not the same as `PanoramaWidth` and `PanoramaHeight` ' scanInfo: type: string blobPreview: type: string allOf: - $ref: '#/components/schemas/BlobName' urlPreview: type: string allOf: - $ref: '#/components/schemas/Url' panoramaWidth: type: number format: int description: The image's *width*, in pixels panoramaHeight: type: number format: int description: The image's *height*, in pixels azimuthLeft: type: number format: float description: 'The max left angle of a scan coverage on the azimuth, in radians. For instance, a scan with 360 degrees coverage will have -π if the `azimuthLeft` is π ' azimuthRight: type: number format: float description: 'The max right angle of a scan coverage on the azimuth, in radians. For instance, a scan with 360 degrees coverage will have π if the `azimuthRight` is -π ' elevationTop: type: number format: float description: 'The max top angle of a scan coverage on the elevation, in radians. For example, a scan with 180 degrees coverage will have π/2 if the `elevationBottom` is -π/2 ' elevationBottom: type: number format: float description: 'The max bottom angle of a scan coverage on the elevation, in radians. For example, a scan with 180 degrees coverage will have -π/2 if the `elevationTop` is π/2 ' appliedScaleFactor: type: number format: int description: 'Scale value applied while the scans are imported through Cintoo Connect. Mainly used for conversion unit between imperial system and metric system. ' src: type: object description: Contains metadata usable by the Cintoo Viewer bulk-files: type: object required: - name - extension - size - md5 properties: name: type: string minimum: 1 maximum: 255 extension: type: string size: type: integer format: int64 md5: type: string FormatId: type: integer readOnly: true example: 5 AccountUrn: type: string description: '"urn:cintoo:account:" followed by an UUIDv4 ' FileImported: type: object properties: importedAt: type: string nullable: true allOf: - $ref: '#/components/schemas/DateTime' FileUrn: type: string description: '"urn:cintoo:file:" followed by an UUIDv4 ' filesTransformationUpdate: type: array items: allOf: - $ref: '#/components/schemas/FileTransformableBody' - type: object required: - id properties: id: $ref: '#/components/schemas/FileUrn' FileSrcModelReports: type: object required: - model - elements - scans - tolerance properties: model: $ref: '#/components/schemas/FileUrn' elements: type: array items: type: string scans: type: array items: $ref: '#/components/schemas/FileUrn' tolerance: type: number 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 ' FilePlaced: type: object required: - translation properties: translation: type: object allOf: - $ref: '#/components/schemas/Vector3D' description: 'A vector representing the position of the image in the Workzone, with three components in meter: `x`, `y` and `z` ' rotation: type: object allOf: - $ref: '#/components/schemas/Quaternion' description: 'A quaternion representing the rotation of the image, with the pivot point being its current position defined by translation. It has four components: `x`, `y`, `z` and `w` ' nullable: true FileCategoryGeoImage: type: string enum: - geoImage description: 'Geo Image files: `.idd`, `.360`' FileCategoryScan: type: string enum: - scan description: 'Scan files: `.fls`, `.e57`, etc.' SiteMap: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategorySiteMap' ModelReport: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlobOptional' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategoryModelReport' src: $ref: '#/components/schemas/FileSrcModelReports' FileScaled: type: object properties: scale: type: object allOf: - $ref: '#/components/schemas/Vector3D' description: 'A vector giving the scaling that we need to apply to make the object fit with other elements of the scene. It has ratios for the three directions: `x`, `y` and `z` ' nullable: true ProjectId: allOf: - $ref: '#/components/schemas/Uuid' example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368 Media: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategoryMedia' Uuid: type: string description: UUIDv4 format: uuid example: 156fff1a-0ef7-4335-891a-627928a19e29 Url: type: string format: uri description: Link that will redirect to 302 signed link to download the corresponding file. Model: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - $ref: '#/components/schemas/FileImported' - $ref: '#/components/schemas/FileTransformable' - type: object required: - type - translation - contentId properties: type: $ref: '#/components/schemas/FileCategoryModel' translation: {} src: description: Metadata attached to the model. Could be present or not. anyOf: - type: object properties: mfi: type: object description: The MFI location and its format required: - blobName - format properties: blobName: $ref: '#/components/schemas/BlobName' format: enum: - json-br-1 description: the format of the Model MFI FileCategoryMedia: type: string enum: - media description: 'Media files: `.png`, `.jp[e]g`, `.gif`, `.bmp`, `.tiff`' Vector3D: type: object required: - x - y - z properties: x: type: number format: double y: type: number format: double z: type: number format: double FileBase: type: object required: - id - api1Id - projectId - workzoneId - name - formatId - size - createdAt - createdBy properties: id: $ref: '#/components/schemas/FileUrn' api1Id: $ref: '#/components/schemas/FileId' projectId: $ref: '#/components/schemas/ProjectUrn' workzoneId: $ref: '#/components/schemas/WorkzoneUrn' name: type: string example: fileName formatId: $ref: '#/components/schemas/FormatUrn' size: type: integer format: int64 minimum: 0 description: File size in Bytes createdAt: $ref: '#/components/schemas/DateTime' createdBy: $ref: '#/components/schemas/UserUrn' updatedAt: type: string allOf: - $ref: '#/components/schemas/DateTime' nullable: true updatedBy: type: string allOf: - $ref: '#/components/schemas/UserUrn' nullable: true MiscFile: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategoryMiscFile' fileUpdate: type: object required: - name properties: name: type: string minimum: 1 maximum: 255 description: New name for the file Archive: allOf: - $ref: '#/components/schemas/FileBase' - $ref: '#/components/schemas/FileBlob' - type: object required: - type properties: type: $ref: '#/components/schemas/FileCategoryArchive' 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 FileBlobOptional: type: object properties: blob: type: string nullable: true deprecated: true description: use `blobName` instead. `blob` will be removed the 1st of november 2025 allOf: - $ref: '#/components/schemas/BlobName' blobName: type: string nullable: true allOf: - $ref: '#/components/schemas/BlobName' url: type: string nullable: true allOf: - $ref: '#/components/schemas/Url' FileCategorySiteMap: type: string enum: - sitemap description: 'Site Map files: `.map`' FileTransformableBody: type: object properties: translation: type: object allOf: - $ref: '#/components/schemas/Vector3D' description: 'A vector representing the position in the Workzone, with three components in meter: `x`, `y` and `z` ' nullable: true rotation: type: object allOf: - $ref: '#/components/schemas/Quaternion' description: 'A quaternion representing the rotation, with the pivot point being its current position defined by translation. It has four components: `x`, `y`, `z` and `w` ' nullable: true scale: type: object allOf: - $ref: '#/components/schemas/Vector3D' description: 'A vector representing a scale deformation along the three axis with three ratio components : `x`, `y` and `z` ' nullable: true FormatUrn: type: string description: '"urn:cintoo:format:" followed by a number ' 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 parameters: fileRef: name: fileRef in: path required: true description: The Id or Urn of the file schema: oneOf: - $ref: '#/components/schemas/FileUrn' - $ref: '#/components/schemas/FileId' categoryFilter: name: category in: query required: false description: 'Comma-separated list of case-sensitive categories of the files we want to list. Providing at least 1 invalid category will return a 400 Bad Request error. Providing empty parameter will return empty files list. If not provided, all files are returned. The category of an existing file can be found in its "type" field. ' schema: type: array items: type: string enum: - document - model - scan - media - miscfile - archive - geoImage - sitemap - modelReport - video3d - gaussian examples: oneId: summary: Example of single category value: - scan multipleIds: summary: Example of multiple categories value: - geoImage - model - video3d - gaussian workzoneRef: name: workzoneRef in: path required: true description: The Id or Urn of the work zone schema: oneOf: - $ref: '#/components/schemas/WorkzoneUrn' - $ref: '#/components/schemas/WorkzoneId' 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' 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