Cintoo Open API (2.0.0)

Download OpenAPI specification:Download

API Support: support@cintoo.com License: Apache 2.0

Cintoo Open API 1.x documentation: https://aec.cintoo.com/api

BETA: API v2 endpoints tagged "BETA" are available in beta-version, meaning that changes may be done later on.

API Specification

The Cintoo API specification document you are viewing is compliant with the Open API Specification 3.0.3 and can be exported to a json format that can be used by the API tool of your liking.

It also means the generated json will contain all the details present in this documentation about the

  • JSON Objects schema being returned
  • The status codes
  • The authentication
  • The verbs/paths/resources

Technical details

  • The API is resource oriented
  • The encoding is done in utf-8
  • Do not hesitate to click on the Download button to get the openapi.json file generated and import in your favorite API client
  • Any Cintoo valid user can use the API

Sandbox

With Cintoo Cloud API comes a Sandbox, which means a testing environment. This Sandbox is a separate tenant from the Cintoo Cloud platform that you are already familiar with.

The Sandbox is at your disposal so that you can test and use the API with no consequence on your production data (no unfortunate deletion by mistake for example).

Sandbox restrictions

  • Scan capacity of 20 scans per user.
  • Company SSO (if any) is not applicable since the Sandbox uses a different account.
  • Please contact support@cintoo.com to get the invitation link to the Sandbox account.
  • You can use the same email but you will be asked to set a new password by clicking on the invitation link.
  • Please note that this is an experimental platform, so we reserve the right to refresh/delete the data (unlike the production platform).
  • There is no limit in time for using the Sandbox.
  • The BIM & CAD Module (BCM) is activated in this Sandbox, so feel free to use your BIM or CAD model in this testing environment.

Registering to the Sandbox / Cintoo Cloud API

Please contact our Support Team support@cintoo.com to be invited to the Sandbox and get all the documentation for Cintoo Cloud API.


Authentication

The Cintoo API relies on JWT Tokens for authenticating users with the standard combination Access Token+ Refresh Token.

Note that the first acquisition of the token pair requires a manual step (see below) for security reasons, then it can be fully automated.

Access Tokens and Refresh Tokens

There are 2 kind of tokens:

  • Access token:
    • is short lived (3h)
    • is used to authenticate each query
    • is personal and should not be shared, except for service users (see Token management recipes at the end of the documentation)
    • is a JWT and is stateless, ie. there is NO limit of Access Token being valid for a given user simultaneously, and can be used in parallel.
    • example of API call to list accounts: curl -H Authorization="Bearer $access_token" https://aec.cintoo.com/api/accounts

Note: Calling the API with an already-used/expired token results in a response with status code 401

  • Refresh token:
    • is long lived (months)
    • is used once to obtain a new Access Token + Refresh Token pair.
    • cannot be used to make API calls.
    • is personal and should not be shared, except for service users (see Token management recipes at the end of the documentation)
    • there IS a limit of 10 Refresh Token being valid for a given user simultaneously
    • is stateful and CANNOT be used in parallel, as it is consumed when used
    • example of refresh token call to get a new pair of "Access Token" and "Refresh Token": curl -X POST https://aec.cintoo.com/oauth/token -d "grant_type=refresh_token&refresh_token=$refresh_token"

Note: Calling the API with an already-used/expired token results in a response with status code 401

The token flow

The Cintoo API follows the OAuth 2.0 Authorization Grant Type flow, and supports the PKCE extension which is recommended to provide better security (source: https://oauth.net/2/grant-types/authorization-code/)

Concretely, users are supposed to acquire the token once with a manual step (they have to click on approve), to get a first pair of tokens.

Once this is done, they can script the refresh with a simple curl command.

Note: a refresh token is valid for 21 days. It can be used only once. The refreshing mechanism can be done an unlimited number of times

Generating Tokens

  • You are just starting with the Cintoo API and want to test it manually -> look that "Generating the JWT Bearer Token with the cintoo-login.exe"
  • You are already familiar with oauth mechanisms/tools -> look at "Using tools/3rd party to manage Tokens from Cintoo Oauth Service"

Generating the Access Token & Refresh Token pair with the cintoo-login.exe

To generate an Access Token with OAuth please use the following nice CLI tool cintoo-login.exe and double click on it.

cintoo-login.exe --url https://aec.cintoo.com/

Opening OAuth page in browser.
To receive your JWT token:
        * Ensure you are logged-in
        * Click on the 'Allow' button
INFO: You have 30s to complete these actions

Which opens this page

Hint: if you wait more than 30s you will have to run the command again Hint: you can change the timeout duration to another value with --timeout 60

allow-button

Once you click on Allow the page should lead you to:

success

AND (most importantly) the token appears magically in your cmd output

Hint: Copy paste the Bearer xxxxx to avoid errors

Opening OAuth page in browser.
To receive your JWT token:
        * Ensure you are logged-in
        * Click on the 'Allow' button
INFO: You have 30s to complete these actions
Here is your token: to use it put in the Authorization header (copy paste below):
{"Authorization": "Bearer <access_token>"}
Its validity is of 3h
A new token can be-regenerated simply thanks to this refresh_token: <refresh_token>
Validating token
Success: API Token was successfully validated

Refreshing tokens ie. Generating programmatically a new Access Token + Refresh Token pair

While the Refresh Token is valid (within 21 days), you can consume it to get a new Access-Token + Refresh-Token pair.

Note: consuming the Refresh Token can be done before the expiration of the Access Token Note: consuming the Refresh Token does NOT invalidate other Access Token as they are short lived

Using shell (Linux, OSX)

refresh_token="<Your refresh token>"
curl -X POST https://aec.cintoo.com/oauth/token -d "grant_type=refresh_token&refresh_token=$refresh_token"

Which returns the following

{
    "access_token": "{access_token}",
    "refresh_token": "{refresh_token}",
    "token_type": "Bearer",
    "expires_in": 10800,
    "user_id": "{user_id}"
}

Using powershell (Windows)

$refresh_token = "<Your refresh token>"
$params = @{
    Uri         = 'https://aec.cintoo.com/oauth/token'
    Method      = 'POST'
    Body        = @{
        grant_type     = 'refresh_token'
        refresh_token  = $refresh_token
    }
    ContentType = 'application/x-www-form-urlencoded'
}
Invoke-RestMethod @params

Which returns the following

access_token  : {access_token}
refresh_token : {refresh_token}
token_type    : Bearer
expires_in    : 10800
user_id       : {user_id}

Using tools/3rd party to manage Tokens from Cintoo Oauth Service

The Cintoo API follows the oauth protocol Authorization Code Grant to generate the access-tokens and refresh-tokens.

As such, it is possible to use 3rd party libraries and tools that implement the Oauth2 Authorization Code protocol to manage the tokens (and perform automatic refresh).

The important fields are the following and they match those defined by the authorization code request, authorization code request with PKCE and refreshing access tokens :

Field Value
Grant Type Authorization Code or Authorization Code (With PKCE)
Callback URL localhost or 127.0.0.1 or /
Auth URL https://aec.cintoo.com/oauth/authorize
Access Token URL https://aec.cintoo.com/oauth/token
Refresh Token URL https://aec.cintoo.com/oauth/token
State use a random code made of [a-z0-9]+ with a "correct length". More information about the state-parameters
Code Challenge Method (only with PKCE) SHA-256 more info on PKCE

The flow in detail for acquiring the first Token pair

This section is here in case you want to build an oauth client for acquiring the first Token pair without the help of the cintoo-login or without 3rd party software.

The term "Client" is going to be described as the originator of the oauth token request.

  • Client calls the Cintoo oauth/authorize endpoint from the browser with the following query parameters:

    • the redirect_uri (callback-url) it wants Cintoo to send the authorization code to
    • the state uses a random code made of [a-z0-9]+ with a "correct length". More information about the state-parameters
    • (optional) code_challenge a random code that has been hashed using the SHA256 algorithm. More info on PKCE.

      code_verifier = high-entropy cryptographic random STRING using the unreserved characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" from Section 2.3 of [RFC3986], with a minimum length of 43 characters and a maximum length of 128 characters.

    • (optional but mandatory if code_challenge is set) code_challenge_method : "SHA256"
  • Cintoo API returns an html element with an approve button to be clicked by the user that started the action (the same shown in the previous chapter)

  • Once the approve button is pressed there is a Form Post URL redirect that will target the redirect_uri provided by the Client with the query parameters : code and state (+ code_challenge and code_challenge_method if specified before)

  • The Client should check that the state sent and received are the same to avoid CSRF attacks.

  • If they are the same, the Client can then send a POST query to the oauth/token endpoint with the following payload that contains the code it received on the previous steps.

    {
        "code": "{code}",
        "grant_type": "authorization_code",
        "authorization_code": "{redirect_uri}"
    }
    

    or with PKCE

    {
        "code": "{code}",
        "grant_type": "authorization_code",
        "authorization_code": "{redirect_uri}",
        "code_verifier": "{code_verifier}"
    }
    
  • Finally the Cintoo API answers the oauth/token with a json object that contains the access_token and refresh_token pair:

    {
        "access_token": "{access_token}",
        "refresh_token": "{refresh_token}",
        "token_type": "Bearer",
        "expires_in": 10800,
        "user_id": "{user_id}"
    }
    

Doing queries

Below you will find an example on how to use the token to do a query.

A good endpoint to start with is the isLogged resource which simply returns 200 and {"success": true} if the token was recognized by the Cintoo API.

We highly recommend that you try it, then start changing the resource type (like accounts for instance) to get used to the API.

Query example for Windows

with cUrl

export HOST=aec.cintoo.com
export TOKEN=...

curl --url "https://{host}/api/2/accounts" --header "Authorization: Bearer $TOKEN"

with Python

import requests

host = "{host}"
token = "..."

response = requests.get(
  "https://%s/api/2/accounts" % host,
  headers = { "Authorization": "Bearer %s" % token}
)
print(response.status_code)
print(response.json())

with Powershell

Copy the code below and try it in your Powershell terminal.

Hint: copy paste this while replacing the xxxxxxx with your token, and call as many Invoke-RestMethod as you want. Note: the token is surrounded by "

$token = "xxxxxxxxxxxxxxxxxx"
$headers = @{
    Authorization="Bearer $token"
    Content='application/json'
}
Invoke-RestMethod -Headers $headers -Method Get -Uri "https://aec.cintoo.com/api/isLogged"

The powershell command line should return this

success
-------
   True

URNs

URNs are standard Uniform Resource Names.

Our NID is of course "cintoo", so they look like: urn:cintoo:{object type}:{object id}.

All the endpoints that return an object or a list of objects include a field giving the URN of the object, that you can in turn use to reference this object whenever you need to mention it.

References

Throughout the API, most endpoints need you to give references to existing objects, like accounts, projects, roles, etc. For example, getting the details of an account will look like:

GET /api/2/accounts/{accountRef}

A reference can be any unambiguous identifier for the object. It typically is either:

  • the raw uuid or numerical id, depending on the type of the object:
    • c41aec8b-3b85-4bdd-81e5-c2cfdb8980e8
    • 5
  • a URN (Uniform Resource Name), looking like: urn:cintoo:<object type>:<raw uuid or id>. For example:
    • urn:cintoo:account:c41aec8b-3b85-4bdd-81e5-c2cfdb8980e8
    • urn:cintoo:user:5

The URN is the most durable option and should be preferred, each object returned by the API has an urn field holding it, whereas at some point the raw id/uuid objects fields will be deprecated or removed from the objects content.

If your client needs to store identifiers for objects, you should choose the URN,

To keep some level of upward compatibility with the first version of the API, for numerical ids we still support older forms, although they are considered deprecated and using them is discouraged:

  • the typed identifier like user-5
  • a Base64 url-safe encoded string of the typed identifier: dXNlci01Cg

Errors

To communicate errors, the Cintoo API

It is consensus in the industry that the status code is the source of truth on whether an API call was successful or not, the body is merely a BONUS.

Error-body returned

We are following this RFC whose content is the following

  • The "status" member is a JSON number indicating The HTTP status code ([HTTP], Section 15) generated by the origin server for this occurrence of the problem.

    The "status" member, if present, is only advisory; it conveys the HTTP status code used for the convenience of the consumer. Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly. See Section 5 for further caveats regarding its use.

    Consumers can use the status member to determine what the original status code used by the generator was when it has been changed (e.g., by an intermediary or cache) and when a message's content is persisted without HTTP information. Generic HTTP software will still use the HTTP status code.

  • The "title" member is a JSON string containing a short, human-readable summary of the problem type.

    It SHOULD NOT change from occurrence to occurrence of the problem, except for localization (e.g., using proactive content negotiation; see [HTTP], Section 12.1).

    The "title" string is advisory and is included only for users who are unaware of and cannot discover the semantics of the type URI (e.g., during offline log analysis).

  • "detail" (string) - The "detail" member is a JSON string containing a human-readable explanation specific to this occurrence of the problem.

    The "detail" string, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.

    Consumers SHOULD NOT parse the "detail" member for information; extensions are more suitable and less error-prone ways to obtain such information.

In addition, 2 extension fields are added:

  • errorCode: detailed code describing the error, can be used to map to a localized message
  • errorValues: values implied in the error, typically an input parameter, can be used to include in a localized message

The mandatory fields that are always present are : status and title. Others are optional.

Example:

{
    "status": 404,
    "title": "Not Found",
    "detail": "Account 1234 not found",
    "errorCode": "account-not-found",
    "errorValues": {
        "accountId": "1234"
    }
}

So the HTTP response status code is both in the HTTP header, and in the status attribute of the returned JSON object.

For a list of errorCode and errorValues, see the dedicated section Errors List


Permissions

Each resource needs to have a permission to be accessed. Permissions are represented by three elements:

  • domain: the level on which the resource is: tenant, account, project or workzone
  • resource: the type of resource, for example users or tags
  • right: the right on the resource the permission is giving. Most of the time it will be either read (get/list resource) or write (create, update, delete) but can be another action when finer granularity is needed.

This is represented by a string containing those 3 elements separated by a colon: <domain>:<resource>:<right>. For example account:users:read is the permission to read (view/list) users on the account level.

Here is the list of the currently supported permissions:

  • tenant:user-permissions:read
  • tenant:user-permissions:write
  • account:account:read
  • account:account:update-owner
  • account:administrators:read
  • account:administrators:write
  • account:project-listers:read
  • account:project-listers:write
  • account:project-managers:read
  • account:project-managers:write
  • account:projects:read (implies project:project:read on all projects of the account)
  • account:projects:create
  • account:projects:update (implies project:project:update-details on all projects of the account)
  • account:projects:delete (implies project:project:delete on all projects of the account)
  • account:roles:read
  • account:roles:write
  • account:subscriptions:read
  • account:subscriptions:write
  • account:users:read
  • account:users:write (implies workzone:members:write on all workzones in the account)
  • account:groups:read
  • project:project:read
  • project:project:delete
  • project:project:update-details
  • project:project:update-owner
  • project:project:update-subscription
  • project:annotations:create-integration-link
  • workzone:annotations:read
  • workzone:annotations:write
  • workzone:documents:read
  • workzone:documents:write
  • workzone:export-jobs-reality-data:write
  • workzone:import-jobs-reality-data:write
  • workzone:measurements:read
  • workzone:measurements:write
  • workzone:members:write
  • workzone:own-shared-links:read
  • workzone:own-shared-links:write
  • workzone:reality-data:read
  • workzone:reality-data:write
  • workzone:savedviews:read
  • workzone:savedviews:write
  • workzone:tags:read
  • workzone:tags:write
  • workzone:workzones:read
  • workzone:workzones:write
  • workzone:progress-monitoring-jobs:read
  • workzone:progress-monitoring-jobs:write
  • workzone:own-progress-monitoring-jobs:read
  • workzone:own-progress-monitoring-jobs:write
  • workzone:model-reports:read
  • workzone:model-reports:write

Roles

A user is given permissions through roles. There are roles on the different levels detailed below.

Roles at the account level

Roles on an account are currently not modifiable, and are the following:

  • Account Member is any user invited to the account
  • Account Owner
  • Account Administrator
  • Project Manager
  • Project Lister

An account member has the following permissions:

  • account:account:read to view the account
  • account:roles:read to view roles on the account
  • account:groups:read to view groups on the account

An account owner or account administrator are account members, and have the following additional permissions:

  • account:projects:read to list and view all projects on the account
  • account:projects:update to update any project on the account
  • account:roles:write to create, edit and delete roles on the account
  • account:users:read to list users members of the account
  • account:users:write to invite or remove users on the account
  • account:subscriptions:read to view subscriptions of the account
  • account:subscriptions:write to add, update or remove subscriptions on the account
  • account:administrators:read to list administrators on the account
  • account:administrators:write to invite or remove an administrator
  • account:project-managers:read to list project managers on the account
  • account:project-managers:write to invite or remove a project manager
  • account:project-listers:read to list project listers on the account
  • account:project-listers:write to invite or remove a project lister

An account owner has also the permission account:account:update-owner that an account administrator does not have, to set another user as the account owner

A project manager is an account member with the following additional permissions:

  • account:projects:read to list and view all projects on the account
  • account:projects:create to create new projects
  • account:projects:update to update any project
  • account:projects:delete to delete any project
  • account:roles:write to create, edit and delete roles on the account
  • account:users:read to list users of the account
  • account:users:write to invite or remove users on the account
  • account:subscriptions:read to view subscriptions of the account
  • account:project-managers:read to list project managers on the account
  • account:project-managers:write to invite or remove a project manager

A project lister is an account member with the following additional permission:

  • account:projects:read to list and view all projects of the account

Roles at project and workzone levels

Roles can be created on an account to give permissions on project and workzone levels.

Users and groups are invited to a project with a specific role, thus a user has the role assigned to him, but also the roles of the groups he belongs to. A user's permissions are determined by adding the permissions of all his roles.

Currently the permissions given to a role are restricted to the following:

  • project:project:update-details + project:project:delete allows the user to manage the project
  • workzone:workzones:read + workzone:workzones:write allows the user to create, modify and delete work zones
  • workzone:reality-data:read allows the user to view reality data
  • workzone:reality-data:write + workzone:import-jobs-reality-data:write allows the user to import or delete scans
  • workzone:export-jobs-reality-data:write allows the user to export and download reality data
  • workzone:annotations:read allows the user to view annotations
  • workzone:annotations:read + workzone:annotations:write allows the user to create, edit and delete annotations, and assign notes to team members
  • workzone:measurements:read + workzone:measurements:write allows the user to add and view 3D measurements
  • workzone:own-shared-links:read + workzone:own-shared-links:write allows the user to create, edit and delete shared links
  • workzone:documents:read + workzone:documents:write allows the user to upload and download documents
  • workzone:tags:read allows the user to view tags
  • workzone:tags:write allows the user to import, create, edit and delete tags
  • workzone:savedviews:read allows the user to view saved views
  • workzone:savedviews:read + workzone:savedviews:write allows the user to create, edit and delete saved views
  • workzone:members:write allows the user to add and remove team members
  • workzone:progress-monitoring-jobs:read + workzone:progress-monitoring-jobs:write
    • workzone:own-progress-monitoring-jobs:read + workzone:own-progress-monitoring-jobs:write
    • workzone:model-reports:read + workzone:model-reports:write allows the user to create, edit, download and delete progress monitoring reports

Any member of a project also automatically has the following permissions:

  • project:project:read on the project
  • workzone:workzones:read on the workzone he is member and all its child workzones

A project owner automatically has all permissions on the project and all its workzones.

A member having permission workzone:annotations:write on the root work zone of a project, automatically has permission project:annotations:create-integration-link on the project


API 1 and API 2

What to expect with API 2

  • Stage 1: API 2 provides features not covered by API 1.
    Most of features are tagged BETA showing that they will continue to mature
  • Stage 2: API 2 BETA tags are removed, and API 2 starts covering API 1 features
  • Stage 3: API 2 fully covers API 1 scope
  • Stage 4: API 1 will have a end of life support date communicated
  • Stage 5: API 1 will be decommissioned

Similarities

  • Authentication system is the same. Tokens used on API 1 can be used in API 2.
  • Do follow the same kind of path ex: /accounts/{accountRef}/projects/{projectRef}/...

Differences

  • Reference system is different: API 2 handles new Reference types (URNs), classic references (UUID) and "legacy references" coming from API 1.
    API 1 supports UUID and "legacy references" only.
  • Error messages in API 2 follow the RFC 9457 (Problem Details for HTTP APIs).
    In short {"code": ..., "message": ...} becomes {"status": ..., "title": ...}.
  • All resources returned by API 2 have multiple ref types (always an URN + UUID or INT)
  • POST and PUT endpoints do return full objets (normally available with a GET)
  • Objects returned from API 1 and API 2 differ

Endpoints only in API 1

  • Report Projects Last Accessed Date
  • Report Users Last Activity Date
  • Partial Update project : change of subscription only
  • List Tag Lists
  • Create/Update/Delete a Tag List
  • List/Get Group
  • List/Get Users

Endpoints only in API 2

  • Create a Project
  • Update project : any field can be changed (owner, description, subscription,...)
  • List Workzones
  • Remove user from Project
  • Get pre-signed urls for multiple blobs
  • Download a blob
  • Create/Update/Delete Role
  • Get subscription

Endpoints both in API 1 and in API 2

  • List Projects
  • Get a Project
  • List Files
  • List/Get Roles
  • List subscription

Account

Account

id
required
string (AccountUrn)

"urn:cintoo:account:" followed by an UUIDv4

type
required
string
Value: "account"
name
required
string
createdAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

updatedAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

ownerId
required
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

required
object (AccountPermissions)
required
Array of objects (Subscription)
{
  • "id": "string",
  • "type": "account",
  • "name": "My Account",
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "ownerId": "string",
  • "permissions": {
    },
  • "subscriptions": [
    ]
}

List accounts

BETAList available accounts for the current user

Authorizations:
oauth2

Responses

Request samples

export TOKEN=...

curl --url "https://aec.cintoo.com/api/2/accounts" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Get account

BETAGet an account details

Requires the permission account:account:read on the account (in other words to be a member of the account).

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID" --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "account",
  • "name": "My Account",
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "ownerId": "string",
  • "permissions": {
    },
  • "subscriptions": [
    ]
}

Project

Project

id
required
string (ProjectUrn)

"urn:cintoo:project:" followed by an UUIDv4

type
required
string
Value: "project"
accountId
required
string (AccountUrn)

"urn:cintoo:account:" followed by an UUIDv4

subscriptionId
required
string (SubscriptionUrn)

"urn:cintoo:subscription:" followed by an UUIDv4

isdemo
required
boolean
region
required
string
name
required
string
description
required
string
required
object (Location)
required
object (ModificationInfo)
required
object (ProjectStatsInfo)
coverUrl
required
string
ownerId
required
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

{
  • "id": "string",
  • "type": "project",
  • "accountId": "string",
  • "subscriptionId": "string",
  • "isdemo": true,
  • "region": "default",
  • "name": "New Project",
  • "description": "string",
  • "location": {
    },
  • "modificationInfo": {
    },
  • "statsInfo": {
    },
  • "coverUrl": "string",
  • "ownerId": "string"
}

File

id
string (FileUrn)

"urn:cintoo:file:" followed by an UUIDv4

type
required
string
Enum: "document" "model" "scan" "media" "miscfile" "archive" "geoImage" "sitemap"
projectId
string (ProjectUrn)

"urn:cintoo:project:" followed by an UUIDv4

workzoneId
string (WorkzoneUrn)

"urn:cintoo:workzone:" followed by an UUIDv4

name
required
string
formatId
string (FormatUrn)

"urn:cintoo:format:" followed by a number

size
integer
createdAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

createdBy
required
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

updatedAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

updatedBy
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

importedAt
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

object (Point3D)
object (Rotation)
object (Point3D)
object (Dimension2d)
scanInfo
string
blob
string

actual filename in the blob storage

blobPreview
string
url
string

URL to download the blob

urlPreview
string

URL to download a preview of the blob

panoramaVersion
integer
panoramaWidth
integer
panoramaHeight
integer
azimuthLeft
number
azimuthRight
number
elevationTop
number
elevationBottom
number
appliedScaleFactor
integer
contentId
string
FileSrcIdd (object) or FileSrcAutodesk (object) or FileSrcFile (object) or FileSrcModelReports (object)

Additional data associated with the blob

{
  • "id": "string",
  • "type": "document",
  • "projectId": "string",
  • "workzoneId": "string",
  • "name": "string",
  • "formatId": "string",
  • "size": 0,
  • "createdAt": "2017-07-21T17:32:28Z",
  • "createdBy": "string",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "updatedBy": "string",
  • "importedAt": "2017-07-21T17:32:28Z",
  • "translation": {
    },
  • "rotation": {
    },
  • "scale": {
    },
  • "resolution": {
    },
  • "scanInfo": "string",
  • "blob": "string",
  • "blobPreview": "string",
  • "url": "string",
  • "urlPreview": "string",
  • "panoramaVersion": 0,
  • "panoramaWidth": 0,
  • "panoramaHeight": 0,
  • "azimuthLeft": 0,
  • "azimuthRight": 0,
  • "elevationTop": 0,
  • "elevationBottom": 0,
  • "appliedScaleFactor": 0,
  • "contentId": "string",
  • "src": {
    }
}

Workzone

id
required
string (WorkzoneUrn)

"urn:cintoo:workzone:" followed by an UUIDv4

type
required
string
Value: "workzone"
projectId
required
string (ProjectUrn)

"urn:cintoo:project:" followed by an UUIDv4

rootWorkzoneId
required
string (WorkzoneUrn)

"urn:cintoo:workzone:" followed by an UUIDv4

name
required
string
description
required
string
roleIds
required
Array of strings (RoleUrn)
coverUrl
required
string
required
object (ModificationInfo)
required
object (ProjectStatsInfo)
{
  • "id": "string",
  • "type": "workzone",
  • "projectId": "string",
  • "rootWorkzoneId": "string",
  • "name": "New Workzone",
  • "description": "string",
  • "roleIds": [
    ],
  • "coverUrl": "string",
  • "modificationInfo": {
    },
  • "statsInfo": {
    }
}

List Projects

BETAList active and deleted projects into this account.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Create a project

BETACreate a project.

Requires the permission account:projects:create on the account.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Request Body schema: application/json
name
string
description
string
subscriptionId
string (SubscriptionUrn)

"urn:cintoo:subscription:" followed by an UUIDv4

region
string
object (Location)
coverUrl
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "subscriptionId": "string",
  • "region": "string",
  • "location": {
    },
  • "coverUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "project",
  • "accountId": "string",
  • "subscriptionId": "string",
  • "isdemo": true,
  • "region": "default",
  • "name": "New Project",
  • "description": "string",
  • "location": {
    },
  • "modificationInfo": {
    },
  • "statsInfo": {
    },
  • "coverUrl": "string",
  • "ownerId": "string"
}

Get Project

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
Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "project",
  • "accountId": "string",
  • "subscriptionId": "string",
  • "isdemo": true,
  • "region": "default",
  • "name": "New Project",
  • "description": "string",
  • "location": {
    },
  • "modificationInfo": {
    },
  • "statsInfo": {
    },
  • "coverUrl": "string",
  • "ownerId": "string"
}

Delete Project

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).

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

query Parameters
permanent
boolean

Delete Permanently a project

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...

curl --request DELETE --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "detail": "Project is deleted",
  • "errorCode": "project-deleted",
  • "errorValues": {
    }
}

Update a Project

BETAUpdate a Project

Permissions:

To update the name, description or location of the project, the requester MUST either:

  • be the account owner, administrator, or project manager
  • have a role with the "Update, delete or restore projects" permission on the project

To update the owner or the subscription of a project, the requester MUST to be the account owner or administrator

When updating the owner of a project, the new owner MUST alread be a project manager

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Request Body schema: application/json
name
string
description
string <= 1000 characters
subscriptionId
string (SubscriptionUrn)

"urn:cintoo:subscription:" followed by an UUIDv4

ownerId
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

object (Location)

Responses

Request samples

Content type
application/json
{
  • "name": "New name for my project",
  • "description": "This is a really interesting project",
  • "subscriptionId": "string",
  • "ownerId": "string",
  • "location": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "project",
  • "accountId": "string",
  • "subscriptionId": "string",
  • "isdemo": true,
  • "region": "default",
  • "name": "New Project",
  • "description": "string",
  • "location": {
    },
  • "modificationInfo": {
    },
  • "statsInfo": {
    },
  • "coverUrl": "string",
  • "ownerId": "string"
}

Restore project

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"

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...

curl --request PUT --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/restore" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "project",
  • "accountId": "string",
  • "subscriptionId": "string",
  • "isdemo": true,
  • "region": "default",
  • "name": "New Project",
  • "description": "string",
  • "location": {
    },
  • "modificationInfo": {
    },
  • "statsInfo": {
    },
  • "coverUrl": "string",
  • "ownerId": "string"
}

List project files

BETAList Project files.

Permissions:

  • the user must be a member of this account
  • the result will only list the files that the user has the permission to retrieve:
    • the files whose formats are in the "Scans", "CAD Models", "GeoImages" categories require to have the permission workzone:reality-data:read on their workzone.
    • the other files only require to be a workzone member.
Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

query Parameters
category
Array of strings
Examples:
  • category=scan - Example of single category
  • category=geoImage,model - Example of multiple categories

Comma-separated list of case-sensitive categories of the files we want to list.

Invalid categories will be ignored. The supported categories are: document, model, scan, media, miscfile, archive, geoImage, sitemap, modelReports.

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/files" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

List Workzones

BETAList workzones of a project

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/workzones" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Create a work zone

BETACreate a work zone in a project, under an existing one (possibly the root work zone of the project).

The new work zone automatically inherits the contributors (users and groups) from the parent work zone.

Requires the permission workzone on the parent work zone.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Request Body schema: application/json
name
required
string
required
WorkzoneUrn (string) or WorkzoneId (string) or WorkzoneOldId (string)
description
string
coverUrl
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parentWorkzoneId": "string",
  • "description": "string",
  • "coverUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "workzone",
  • "projectId": "string",
  • "rootWorkzoneId": "string",
  • "name": "New Workzone",
  • "description": "string",
  • "roleIds": [
    ],
  • "coverUrl": "string",
  • "modificationInfo": {
    },
  • "statsInfo": {
    }
}

Bulk remove users and groups from project

BETARemove users and groups from the project.

This endpoint will ignore users or groups that are not really contributors of the project.

Permissions: Requires a role with "Manage User" permission on the top most workzone of the project.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Request Body schema: application/json
users
Array of objects (userRef)
groups
Array of objects (groupRef)

Responses

Request samples

Content type
application/json
{
  • "users": [
    ],
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "status": 403,
  • "type": "Cannot remove users or groups. Need to have \"manage_user\" permission on the project"
}

Remove user from project

BETARemove a user from the project.

Requires the permission workzone:members:write on the top most workzone of the project.

Note can be invoked on self. Any user can remove himself from a project.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

required
UserUrn (string) or UserId (string) or UserOldId (string)

The Id or Urn of the user

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...
export USERID=...

curl --request DELETE --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/members/users/$USERID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "status": 403,
  • "title": "Forbidden",
  • "detail": "You do not have the permission to remove contributor. It requires to be targeting self, or to have permission \"manage_users\"",
  • "errorCode": "remove-contributor-forbidden"
}

Remove group from project

BETARemove a group from the project.

Permissions:

Requires the permission workzone:members:write on the top most workzone of the project.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

required
GroupUrn (string) or GroupId (string)

The Id or Urn of the group

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...
export GROUPUUID=...

curl --request DELETE --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/members/groups/$GROUPUUID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "status": 403,
  • "type": "Cannot remove group(s). Need to have \"manage_user\" permission on the project"
}

Remove user from workzone

BETARemove a user from a work zone and all child work zones.

If the work zone is not the project's root work zone, and the user to remove is also a contributor on a parent work zone, the user must be removed from the parents for which he is a contributor. If this is the case, and the query parameter 'allowRemoveOnParents' is not specified or set to false, a bad request error will be returned (code 400).

Requires the permission workzone:members:write on the work zone as well as any parent work zone to which the user is a contributor if the parameter 'allowRemoveOnParents' is true.

Note can be invoked on self. Any user can remove himself from a work zone.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

required
WorkzoneUrn (string) or WorkzoneId (string) or WorkzoneOldId (string)

The Id or Urn of the workzone

required
UserUrn (string) or UserId (string) or UserOldId (string)

The Id or Urn of the user

query Parameters
allowRemoveOnParents
boolean
Default: false

If true the operation is allowed to remove from a parent.

If false and the operation needs to remove from a parent, a bad request error will be returned.

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...
export WORKZONEID=...
export USERID=...

curl --request DELETE --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/PROJECTUUID/workzones/$WORKZONEID/members/users/$USERID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "status": 400,
  • "title": "Bad Request",
  • "detail": "Invalid parameter allowRemoveOnParents: The user is contributor on a parent work zone and parameter 'allowRemoveOnParents' is false",
  • "errorCode": "invalid-input"
}

Get pre-signed urls for multiple blobs

BETAGet pre-signed urls for multiple blobs.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Request Body schema: application/json
Array
string

list of blob refs -> blob attribute in File schema

Responses

Request samples

Content type
application/json
[
  • "1f74af182236bd4e5df2c3f18f3d94fe.png"
]

Response samples

Content type
application/json
{
  • "expiresIn": 0,
  • "urls": { }
}

Download a blob

BETADownload a blob, via a redirection to pre-signed URL

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

blobRef
required
string
Example: 1f74af182236bd4e5df2c3f18f3d94fe.png

a blob ref -> blob attribute in File schema

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...
export BLOBID=...

curl --location "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/blobs/$BLOBID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
Example
{
  • "status": 400,
  • "title": "Bad Request"
}

List annotations on a project

BETAList all annotations on a project

Only annotations on work zones where the user has the permission workzone:annotations:read are returned.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

query Parameters
includeComments
boolean
Default: false

If true the operation retrieves comments attached to each annotation, else the comments field will not be returned.

includeAttachments
boolean
Default: false

If true the operation retrieves information about files attached to each annotation or comment, else the attachments field will not be returned.

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Create an annotation

BETACreate an annotation

Requires the permission workzone:annotations:write on the work zone.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

Request Body schema: application/json
workzoneId
required
string (WorkzoneUrn)

"urn:cintoo:workzone:" followed by an UUIDv4

type
required
string
Enum: "Private note" "Note" "Issue" "Resolved"
title
required
string [ 1 .. 255 ] characters
description
required
string non-empty
assignedTo
Array of strings (UserUrn)
dueDate
string <date>
priority
integer
Enum: 0 1 5 8 10
imgBlobName
string
required
object (Point3D)
object (Point3D)
scanId
string <= 12 characters
legacy (object) or others (object) (SavedViewData)
labels
Array of strings
attachments
Array of strings

blob names

Responses

Request samples

Content type
application/json
{
  • "workzoneId": "string",
  • "type": "Private note",
  • "title": "string",
  • "description": "string",
  • "assignedTo": [
    ],
  • "dueDate": "2019-08-24",
  • "priority": 0,
  • "imgBlobName": "string",
  • "position": {
    },
  • "normal": {
    },
  • "scanId": "string",
  • "savedView": {
    },
  • "labels": [
    ],
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "annotation",
  • "workzoneId": "string",
  • "modificationInfo": {
    },
  • "annotationType": "string",
  • "title": "string",
  • "description": "string",
  • "descriptionText": "string",
  • "assignedTo": [
    ],
  • "dueDate": null,
  • "priority": 0,
  • "number": 0,
  • "scanId": "string",
  • "position": {
    },
  • "normal": {
    },
  • "imgBlobName": "string",
  • "savedView": {
    },
  • "comments": [
    ],
  • "attachments": [
    ],
  • "labels": [
    ],
  • "integrations": [
    ]
}

Get annotation

BETARetrieve an annotation, optionally with comments and attachments

Requires the permission workzone:annotations:read on the work zone where the annotation is.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

required
AnnotationUrn (string) or AnnotationId (string)

The Id or Urn of the annotation

query Parameters
includeComments
boolean
Default: false

If true the operation retrieves comments attached to each annotation, else the comments field will not be returned.

includeAttachments
boolean
Default: false

If true the operation retrieves information about files attached to each annotation or comment, else the attachments field will not be returned.

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...
export ANNOTATIONID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations/ANNOTATIONID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "annotation",
  • "workzoneId": "string",
  • "modificationInfo": {
    },
  • "annotationType": "string",
  • "title": "string",
  • "description": "string",
  • "descriptionText": "string",
  • "assignedTo": [
    ],
  • "dueDate": null,
  • "priority": 0,
  • "number": 0,
  • "scanId": "string",
  • "position": {
    },
  • "normal": {
    },
  • "imgBlobName": "string",
  • "savedView": {
    },
  • "comments": [
    ],
  • "attachments": [
    ],
  • "labels": [
    ],
  • "integrations": [
    ]
}

Update an annotation

BETAUpdate an annotation

Requires the permission workzone:annotations:write on the work zone.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

required
AnnotationUrn (string) or AnnotationId (string)

The Id or Urn of the annotation

Request Body schema: application/json
type
required
string
Enum: "Private note" "Note" "Issue" "Resolved"
title
required
string [ 1 .. 255 ] characters
description
required
string non-empty
assignedTo
Array of strings (UserUrn)
dueDate
string <date>
priority
integer
Enum: 0 1 5 8 10
imgBlobName
string
required
object (Point3D)
object (Point3D)
scanId
string <= 12 characters
legacy (object) or others (object) (SavedViewData)
labels
Array of strings
attachments
Array of strings

blob names

Responses

Request samples

Content type
application/json
{
  • "type": "Private note",
  • "title": "string",
  • "description": "string",
  • "assignedTo": [
    ],
  • "dueDate": "2019-08-24",
  • "priority": 0,
  • "imgBlobName": "string",
  • "position": {
    },
  • "normal": {
    },
  • "scanId": "string",
  • "savedView": {
    },
  • "labels": [
    ],
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "annotation",
  • "workzoneId": "string",
  • "modificationInfo": {
    },
  • "annotationType": "string",
  • "title": "string",
  • "description": "string",
  • "descriptionText": "string",
  • "assignedTo": [
    ],
  • "dueDate": null,
  • "priority": 0,
  • "number": 0,
  • "scanId": "string",
  • "position": {
    },
  • "normal": {
    },
  • "imgBlobName": "string",
  • "savedView": {
    },
  • "comments": [
    ],
  • "attachments": [
    ],
  • "labels": [
    ],
  • "integrations": [
    ]
}

Delete an annotation

BETADelete an annotation

Requires the permission workzone:annotations:write on the work zone.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

required
AnnotationUrn (string) or AnnotationId (string)

The Id or Urn of the annotation

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export PROJECTUUID=...
export ANNOTATIONUUID=...

curl --request DELETE --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations/$ANNOTATIONUUID" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \

Response samples

Content type
application/json
Example
{
  • "status": 400,
  • "title": "Bad Request"
}

Create a comment on an annotation

BETACreate a comment on an annotation

Requires the permission workzone:annotations:write on the work zone.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
ProjectUrn (string) or ProjectId (string)

The Id or Urn of the project

required
AnnotationUrn (string) or AnnotationId (string)

The Id or Urn of the annotation

Request Body schema: application/json
description
required
string non-empty
attachments
Array of strings

blob names

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "attachments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "annotation-comment",
  • "modificationInfo": {
    },
  • "attachedTo": "string",
  • "description": "string",
  • "descriptionText": "string",
  • "attachments": [
    ]
}

Group

Group

id
string (GroupUrn)

"urn:cintoo:group:" followed by an UUIDv4

type
required
string
Value: "group"
name
required
string
description
string
color
required
string (Color) ^#[0-9a-f]{6}$
createdAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

createdBy
required
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

updatedAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

userIds
required
Array of strings (UserUrn)
accountIds
required
Array of strings (AccountUrn)
{
  • "id": "string",
  • "type": "group",
  • "name": "group",
  • "description": "group description",
  • "color": "#0698ec",
  • "createdAt": "2017-07-21T17:32:28Z",
  • "createdBy": "string",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "userIds": [
    ],
  • "accountIds": [
    ]
}

List groups

BETAList available groups in this account.

Requires the permission account:groups:read on the account.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/groups" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

List groups

BETAList available groups in this account.

Requires the permission account:groups:read on the account.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/groups" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Remove users from a group

BETARemoves a list of users from a group

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
GroupUrn (string) or GroupId (string)

The Id or Urn of the group

Request Body schema: application/json
Array
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
[
  • {
    }
]

Role

Role

id
required
string (RoleUrn)

"urn:cintoo:role:" followed by an UUIDv4

type
required
string
Value: "role"
name
required
string
description
string
color
string (Color) ^#[0-9a-f]{6}$
createdBy
required
string (UserUrn)

"urn:cintoo:user:" followed by an UUIDv4

createdAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

updatedAt
required
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

permissions
required
Array of strings (RolePermissions)
Items Enum: "project:project:delete" "project:project:update-details" "workzone:workzones:write" "workzone:workzones:read" "workzone:reality-data:read" "workzone:annotations:write" "workzone:annotations:read" "workzone:measurements:write" "workzone:measurements:read" "workzone:own-shared-links:write" "workzone:own-shared-links:read" "workzone:reality-data:write" "workzone:import-jobs-reality-data:write" "workzone:export-jobs-reality-data:write" "workzone:documents:write" "workzone:documents:read" "workzone:members:write" "workzone:tags:write" "workzone:tags:read" "workzone:savedviews:write" "workzone:savedviews:read" "workzone:model-reports:read" "workzone:model-reports:write" "workzone:progress-monitoring-jobs:read" "workzone:progress-monitoring-jobs:write" "workzone:own-progress-monitoring-jobs:read" "workzone:own-progress-monitoring-jobs:write"

permissions given by the role. Please check the permissions section for the list of allowed combinations

accountIds
required
Array of strings (AccountUrn)
{
  • "id": "string",
  • "type": "role",
  • "name": "BIM / VDC Manager",
  • "description": "Can do anything except creating projects",
  • "color": "#0698ec",
  • "createdBy": "string",
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "permissions": [
    ],
  • "accountIds": [
    ]
}

List roles

BETAList available roles into this account.

Requires the permission account:roles:read.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Create Role

BETACreate a custom role.

Requires the permission account:roles:write.

The allowed combinations of permissions are documented here

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Request Body schema: application/json
name
required
string
description
string
color
string (Color) ^#[0-9a-f]{6}$
permissions
required
Array of strings (RolePermissions)
Items Enum: "project:project:delete" "project:project:update-details" "workzone:workzones:write" "workzone:workzones:read" "workzone:reality-data:read" "workzone:annotations:write" "workzone:annotations:read" "workzone:measurements:write" "workzone:measurements:read" "workzone:own-shared-links:write" "workzone:own-shared-links:read" "workzone:reality-data:write" "workzone:import-jobs-reality-data:write" "workzone:export-jobs-reality-data:write" "workzone:documents:write" "workzone:documents:read" "workzone:members:write" "workzone:tags:write" "workzone:tags:read" "workzone:savedviews:write" "workzone:savedviews:read" "workzone:model-reports:read" "workzone:model-reports:write" "workzone:progress-monitoring-jobs:read" "workzone:progress-monitoring-jobs:write" "workzone:own-progress-monitoring-jobs:read" "workzone:own-progress-monitoring-jobs:write"

permissions given by the role. Please check the permissions section for the list of allowed combinations

Responses

Request samples

Content type
application/json
{
  • "name": "BIM / VDC Manager",
  • "description": "Can do anything except creating projects",
  • "color": "#0698ec",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "role",
  • "name": "BIM / VDC Manager",
  • "description": "Can do anything except creating projects",
  • "color": "#0698ec",
  • "createdBy": "string",
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "permissions": [
    ],
  • "accountIds": [
    ]
}

Get role

BETAGet a role details.

Requires the permission account:roles:read.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
RoleUrn (string) or RoleId (string) or RoleOldId (string)

The Id or Urn of the role

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export ROLEID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles/$ROLEID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "role",
  • "name": "BIM / VDC Manager",
  • "description": "Can do anything except creating projects",
  • "color": "#0698ec",
  • "createdBy": "string",
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "permissions": [
    ],
  • "accountIds": [
    ]
}

Delete role

BETADelete a Role.

Requires the permission account:roles:write.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
RoleUrn (string) or RoleId (string) or RoleOldId (string)

The Id or Urn of the role

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export ROLEID=...

curl --request DELETE --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/roles/$ROLEID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
Example
{
  • "status": 400,
  • "title": "Bad Request",
  • "detail": "Base roles can't be deleted",
  • "errorCode": "cannot-delete-base-role"
}

Update role

BETAUpdate a role.

Requires the permission account:roles:write.

The allowed combinations of permissions are documented here

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
RoleUrn (string) or RoleId (string) or RoleOldId (string)

The Id or Urn of the role

Request Body schema: application/json
name
string
description
string
color
string (Color) ^#[0-9a-f]{6}$
permissions
Array of strings (RolePermissions)
Items Enum: "project:project:delete" "project:project:update-details" "workzone:workzones:write" "workzone:workzones:read" "workzone:reality-data:read" "workzone:annotations:write" "workzone:annotations:read" "workzone:measurements:write" "workzone:measurements:read" "workzone:own-shared-links:write" "workzone:own-shared-links:read" "workzone:reality-data:write" "workzone:import-jobs-reality-data:write" "workzone:export-jobs-reality-data:write" "workzone:documents:write" "workzone:documents:read" "workzone:members:write" "workzone:tags:write" "workzone:tags:read" "workzone:savedviews:write" "workzone:savedviews:read" "workzone:model-reports:read" "workzone:model-reports:write" "workzone:progress-monitoring-jobs:read" "workzone:progress-monitoring-jobs:write" "workzone:own-progress-monitoring-jobs:read" "workzone:own-progress-monitoring-jobs:write"

permissions given by the role. Please check the permissions section for the list of allowed combinations

Responses

Request samples

Content type
application/json
{
  • "name": "BIM / VDC Manager",
  • "description": "Can do anything except creating projects",
  • "color": "#0698ec",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "role",
  • "name": "BIM / VDC Manager",
  • "description": "Can do anything except creating projects",
  • "color": "#0698ec",
  • "createdBy": "string",
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z",
  • "permissions": [
    ],
  • "accountIds": [
    ]
}

Subscription

Subscription

id
required
string (SubscriptionUrn)

"urn:cintoo:subscription:" followed by an UUIDv4

type
required
string
Value: "subscription"
accountId
required
string (AccountUrn)

"urn:cintoo:account:" followed by an UUIDv4

isVa
required
boolean
isActive
required
boolean
name
string
start
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

tagCapacity
integer
scanCapacity
integer
createdAt
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

updatedAt
string <date-time> (DateTime)

The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18T12:41:31+0000)

{
  • "id": "string",
  • "type": "subscription",
  • "accountId": "string",
  • "isVa": true,
  • "isActive": true,
  • "name": "My Subscription",
  • "start": "2017-07-21T17:32:28Z",
  • "tagCapacity": 50,
  • "scanCapacity": 500,
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z"
}

List subscriptions

BETAList available subscriptions into this account.

Requires the permission account:subscriptions:read on the account.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/subscriptions" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

Get subscription

BETAGet a subscription details.

Requires the permission account:subscriptions:read on the account.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

required
SubscriptionUrn (string) or SubscriptionId (string) or SubscriptionOldId (string)

The Id or Urn of the subscription

Responses

Request samples

export TOKEN=...
export ACCOUNTUUID=...
export SUBSCRIPTIONID=...

curl --url "https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/subscriptions/$SUBSCRIPTIONID" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "subscription",
  • "accountId": "string",
  • "isVa": true,
  • "isActive": true,
  • "name": "My Subscription",
  • "start": "2017-07-21T17:32:28Z",
  • "tagCapacity": 50,
  • "scanCapacity": 500,
  • "createdAt": "2017-07-21T17:32:28Z",
  • "updatedAt": "2017-07-21T17:32:28Z"
}

User

Invite users

BETAInvite users to an account

This endpoint is idempotent which means it applies the state requested by the caller. It can be used to invite users to an account with a set of accountRole or it can be used to grant new accountRoles to existing users.

Users that are new to the Cintoo cloud platform are expected to receive an invitation email where they will be able to define a password.

Requires the caller:

  • to have permission account:administrators:write to invite users as administrators
  • to have permission account:project-managers:write to invite users as project managers
  • to have permission account:project-listers:write to invite users as project listers
  • to have permission workzone:members:write to invite users without specific account role

If any of the roles is invalid or if some roles are not allowed for the caller, then the whole request returns an error, no invitation are sent and no change is applied.

Authorizations:
oauth2
path Parameters
required
AccountUrn (string) or AccountId (string)

The Id or Urn of the account

Request Body schema: application/json
Array
email
required
string
roles
Array of strings unique
Items Enum: "administrator" "projectLister" "projectManager"

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "status": 400,
  • "title": "Bad Request"
}

Values

Permission

name
required
string
{
  • "name": "string"
}

List permissions

BETAList available permissions

Authorizations:
oauth2

Responses

Request samples

export TOKEN=...

curl --url "https://aec.cintoo.com/api/2/values/permissions" \
  --header "Authorization: Bearer $TOKEN"

Response samples

Content type
application/json
[
  • {
    }
]

List file formats

BETAList supported file formats

Authorizations:
oauth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get accounts

Get the list of accounts

You can get your accounts with the accounts API: List Accounts

Here is an extract of what it returns:

[
    {
        "id": "{accountId}",
        "urn": "{accountUrn}",
        "type": "account",
        "name": "My Account",
        "createdAt": "2017-07-21T17:32:28Z",
        "createdBy": "{userId}",
        "ownerId": "{userId}",
        "permissions": {
          "owner": true,
          "manager": false,
          "admin": true
        }
    },
    ...
]

And here we are interested in the id field.

In javascript accessing those would look like this:

// assuming you have the result of the query in the "accounts" variable
> accounts.map(account => account.id)
[ "{accountId1}", "{accountId2}" ]

Get projects

Prerequisites

Follow the tutorial to get the list of accounts first: here.

Once you have the project list pick the {accountId} corresponding to the account you want your projects from.

Get the list of Projects

You can get your projects with the projects API: List Projects

Here is an extract of what it returns:

[
    {
        "id": "{projectId}",
        "urn": "{projectUrn}",
        "type": "project",
        "accountId": "{accountUrn}",
        "planId": "{subscriptionUrn}",
        "name": "{projectName}",
        ...
    },
    ...
]

Let's say that we are interested in the id field.

Assuming we have the result of the query in the "projects" variable, in javascript we could get their list:

> projects.map(project => project.id)
[ "{projectId}", "{projectId2}" ]

Get files

Prerequisites

Follow the tutorial to get the list of project first: here.

Once you have the project list pick the {projectId} or {projectUrn} corresponding to the project you want your files from.

Get the list of files

You can get this project files with the projects API: List Project files

Example of response body:

[
  {
    "id": "{fileId}",
    "urn": "{projectUrn}",
    "name": "{fileName}",
    "projectId": "{projectId}",
    "createdAt": "2019-08-24T14:15:22Z",
    "createdBy": "{userId}",
    "updatedAt": "2019-08-24T14:15:22Z",
    "updatedBy": "{userId}",
    "imageBlob": "547e638baece20bb63253287715eb87c.jpg",
    "imagePreviewBlob": "547e638baece20bb63253287715eb87c_preview.jpg",
    "type": "model",
    "translation": {
      "x": 0,
      "y": 0,
      "z": 0
    },
    "rotation": {
      "x": 0,
      "y": 0,
      "z": 0,
      "w": 0
    },
    "contentId": "string",
    "src": {
      "type": "string",
      "data": "string",
      "name": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "createdBy": "string",
      "version": 0,
      "treeBlob": "string",
      "metadataBlob": "string"
    },
    "importedAt": "2019-08-24T14:15:22Z"
  }
]

Get the list of scans/models/geoImages

This is the same call, with the additional "category" parameter to restrain the categories of the files that will be listed.

GET api/2/accounts/{accountId}/projects/{projectId}/files?category=scan,model,geoImage.

Full spec about the files endpoint List Project files.

Token Management

Good practices

Each user should have their own tokens

Tokens are personal and are bound to the person who generated them with all their roles and permissions.

In The Cintoo platform a subscription can hold an unlimited number of users. Furthermore, there are roles (Project Managers) to grant access users to resources with different levels of privileges (read, write, etc.).

There are only positive outcomes to use as many users as possible.

Single refresher, multiple accessors

If you absolutely need to have a single user do all the API calls, but multiple applications share the same tokens, you might very quickly hit the limit of simultaneous refresh tokens valid for a single user.

Remember from the Access Tokens and Refresh Tokens section that

  • Access Tokens are JWT tokens, that are stateless and can be used in parallel
  • Refresh Tokens are stateful and cannot be used in parallel

Our recommendation in that case would be to have

  • A 'refreshing process/app' which would be the only one to use the refresh token and store both Refresh Token and Access Token. The stored Access Token should remain available for other processes
  • Multiple processes/apps that would ask for the Access Tokens, which could be either in the DB OR from the 'refreshing process/app'. These requests should be performed intermittently to prevent Access Token expiration, so that the processes/apps can perform all the queries to the Cintoo API

Note: the Access Token is a JWT and can easily be decoded to check the expiration date

Race conditions risk without proper synchronization

In case that it is not possible to refresh the token from a single app, the client should at least handle race conditions in which a single refresh token is used twice by two concurrent processes. In this case the second refresh will fail. The first client should have stored the new Access-Token/Refresh-Token immediately after the refresh process.

Errors List

400 Bad Request

Invalid reference

All resources including a reference, such as accountRef or projectRef will return a status 400 when the reference is invalid.

Malformed URN

  • errorCode: invalid-xxx-urn where xxx is the type of reference

Example:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "ID type mismatch in Urn. Expected a 'user', found a 'role'",
  "errorCode": "invalid-user-urn"
}

Invalid reference ID

  • errorCode: invalid-xxx-id where xxx is the type of reference

Example:

{
  "status": 400,
  "title": "Bad Request",
  "detail": "project must be given as an UUID or URN",
  "errorCode": "invalid-project-id"
}

Invalid input

The error code invalid-input is used when an element of the request is invalid, for example updating a project with a too long name.

Specific cases

Each endpoint may have more specific error cases for input validation, for which you'll find the list and description in their dedicated section.

401 Unauthorized

All endpoints, except authentication endpoints, need to be authenticated. The status 401, with errorCode = unauthorized is returned if the request is done without authentication or with an invalid or expired authentication

403 Forbidden

Action forbidden

Entry points doing a creation, an update, or a deletion return a status 403 when the action is forbidden for the user.

  • errorCode: xxx-yyy-forbidden where:
    • xxx is the type of action, which is one of create, update, or delete
    • yyy is the type of resource on which the action is requested, for example role, user, ...
  • errorValues:
    • requiredPermissions: list of permissions

Example:

{
  "status": 403,
  "title": "Forbidden",
  "detail": "You do not have the permission to delete project. It requires to have permission \"project:project:delete\" or \"account:projects:delete\"",
  "errorCode": "delete-project-forbidden",
  "errorValues": {
    "requiredPermissions": ["project:project:delete", "account:projects:delete"]
  }
}

If the action is performed on a deleted element, for example create a new work zone on a deleted project, the error code deleted-xxx is returned with xxx the type of element on which the action is performed.

Example:

{
  "status": 403,
  "title": "Forbidden",
  "detail": "Access forbidden because workzone is deleted",
  "errorCode": "deleted-workzone",
  "errorValues": {
    "workzoneId": "12345"
  }
}

Specific cases

The following errorCode values can be returned with status 403:

  • not-member-of-project when a user tries to access to a project he is not a member of
  • not-contributor-of-project when a user tries to access to a work zone of a project he is not a contributor of
  • list-*-forbidden when trying to list resources without the related permissions
  • view-*-forbidden when trying to view a resource without needed permissions
  • remove-contributor-from-work-zone-forbidden when trying to remove a user as a contributor from a work zone without needed permissions

404 Not Found

Reference not found

All resources including a reference, such as accountRef or projectRef will return a status 404 when the reference is valid but does not exist.

  • errorCode: xxx-not-found where xxx is the type of reference
  • errorValues:
    • xxx: the ID of the reference, where xxx is the type of reference

Example:

{
    "status": 404,
    "title": "Not Found",
    "detail": "Account 1234 not found",
    "errorCode": "account-not-found",
    "errorValues": {
        "account": "1234"
    }
}

Specific cases

The following errorCode values can be returned with status 404:

  • user-email-not-found when referencing a user referenced by its email was not found in the database