Cintoo Workzone API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Cintoo Open Workzone API
  description: '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.'
  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: Workzone
paths:
  /api/2/accounts/{accountRef}/projects/{projectRef}/workzones:
    get:
      summary: List Workzones
      operationId: getWorkzones
      description: BETAList work zones of a project
      tags:
      - Workzone
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      responses:
        '200':
          description: List of work zones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workzone'
        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/workzones\" \\\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/workzones\"\n    % (host, accountUUID, projectUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/workzones`;\nconst res = await fetch(url, {\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n  },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
    post:
      summary: Create a work zone
      operationId: createWorkzone
      description: '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.'
      tags:
      - Workzone
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/workzoneCreate'
      responses:
        '201':
          description: The work zone was successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workzone'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
  /api/2/accounts/{accountRef}/projects/{projectRef}/workzones/{workzoneRef}/members/users/{userRef}:
    delete:
      summary: Remove user from work zone
      operationId: removeUserFromWorkzone
      description: '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.'
      tags:
      - Workzone
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      - $ref: '#/components/parameters/workzoneRef'
      - $ref: '#/components/parameters/userRef'
      - $ref: '#/components/parameters/allowRemoveOnParents'
      responses:
        '204':
          description: The user was successfully removed from the work zone
        '400':
          description: The user is a contributor of a parent work zone and the parameter 'allowRemoveOnParents' is not set to 'true'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorBadRequest'
                - type: object
                  properties:
                    errorCode:
                      type: string
                      description: '* `invalid-input` if the user is a contributor of a parent work zone

                        and the parameter ''allowRemoveOnParents'' is not set to ''true''

                        '
              examples:
                invalid-input:
                  value:
                    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
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorForbidden'
                - type: object
                  properties:
                    errorCode:
                      type: string
                      description: '* `remove-contributor-from-work-zone-forbidden`

                        '
              examples:
                remove-contributor-from-work-zone-forbidden:
                  value:
                    status: 403
                    title: Forbidden
                    detail: You do not have the permission to remove contributor from work zone. It requires to be targeting self, or to be Project Owner, or to have permission "manage_users"
                    errorCode: remove-contributor-from-work-zone-forbidden
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport WORKZONEID=...\nexport USERID=...\n\ncurl --request DELETE --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/workzones/$WORKZONEID/members/users/$USERID\" \\\n  --header \"Authorization: Bearer $TOKEN\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nworkzoneId = \"...\"\nuserId = \"...\"\ntoken = \"...\"\n\nresponse = requests.delete(\n  \"https://%s/api/2/accounts/%s/projects/%s/workzones/%s/members/users/%s\"\n    % (host, accountUUID, projectUUID, workzoneId, userId),\n  headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\n"
      - lang: TypeScript
        source: "\nconst host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst workzoneId = \"...\";\nconst userId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/workzones/${workzoneId}/members/users/${userId}`;\nconst res = await fetch(url, {\n  method: \"DELETE\",\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n  },\n});\n\nconsole.log(res.status);\nif (res.status !== 204) {\n  const data = await res.json();\n  console.log(data);\n}\n"
  /api/2/accounts/{accountRef}/projects/{projectRef}/workzones/{workzoneRef}/copy:
    post:
      summary: Copy a work zone
      operationId: copyWorkzone
      description: 'BETACopy a work zone, its sub-work zones, and the files on these work zones.


        The destination of the copy is provided by:

        - `destinationProject`: if not provided or null, a new project is created, and the copied work zone will

        be the root work zone of the new project.

        - `destinationWorkzone`: if provided and not null, specify the work zone inside the destination project in which

        the copied work zone will be. Default is the root work zone of the destination project.

        Cannot be provided if `destinationProject` is not provided.

        - Only in case a new project is created (`destinationProject` not provided), the `destinationSubscription`

        can be provided to assign the new project to this subscription. Default is to use the same subscription as

        the source project.


        Notes:

        - the resources like tags, annotations, crops, etc... are not copied. Only the structure and the files

        are copied.

        - if the request is accepted, the server responds immediately with a 202 status code, but at this moment

        the copy is not yet processed. It will be processed asynchronously, and the user will receive a

        notification by email once the process is finished (either successfully or with an error).

        - if a copy is already in progress on the source or destination project, it will fail


        Permissions:

        - On the source work zone, the user must be contributor and have the permissions `workzone:workzones:read`,

        `workzone:reality-data:read` and `workzone:cad-model:read`

        ("View Reality Data" and "Upload and download documents"),

        which are automatically included for the project owner.

        - If the destination is a new project, the user must be a project manager.

        - If the destination is an existing project, the user must be a contributor of the destination work zone

        with permissions `workzone:workzones:write`, `workzone:reality-data:write` and `workzone:cad-model:write`

        ("Work Zones", "Upload or Delete Reality Data", "Upload and download documents"),

        which are automatically included for the project owner.


        ⚠ We strongly recommend not to make any modification in the source work zone (and its sub-work zones) while the copy is in progress. If any changes are done in the source, they may not be taken into account and it might compromise the result. Both source and destination projects may be temporarily not accessible during the copy.'
      tags:
      - Workzone
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      - $ref: '#/components/parameters/workzoneRef'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - destinationName
              properties:
                destinationName:
                  type: string
                  minLength: 1
                  maxLength: 255
                destinationProject:
                  description: The project to copy into. If not provided, a new project is created.
                  allOf:
                  - $ref: '#/components/schemas/ProjectRef'
                  type:
                  - string
                  - 'null'
                destinationWorkzone:
                  description: The work zone to copy into. Only valid if a destination project is specified.
                  allOf:
                  - $ref: '#/components/schemas/WorkzoneRef'
                  type:
                  - string
                  - 'null'
                destinationSubscription:
                  description: The subscription to use for the new project. Only valid if a destination project is not specified.
                  allOf:
                  - $ref: '#/components/schemas/SubscriptionRef'
                  type:
                  - string
                  - 'null'
      responses:
        '202':
          description: The copy has been accepted and will be processed in a short time
        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/copy\" \\\n  --header \"Authorization: Bearer $TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{ \"destinationName\": \"My copy\" }'\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/copy\"\n    % (host, accountID, projectID, workzoneID),\n  headers = { \"Authorization\": \"Bearer %s\" % token },\n  json = { \"destinationName\": \"My copy\" }\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}/copy`;\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    { \"destinationName\": \"My copy\" }\n  ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
components:
  schemas:
    SubscriptionRef:
      oneOf:
      - $ref: '#/components/schemas/SubscriptionUrn'
      - $ref: '#/components/schemas/SubscriptionId'
    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

        '
    AccountUrn:
      type: string
      description: '"urn:cintoo:account:" followed by an UUIDv4

        '
    ProjectRef:
      oneOf:
      - $ref: '#/components/schemas/ProjectUrn'
      - $ref: '#/components/schemas/ProjectId'
    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'
    SubscriptionUrn:
      type: string
      description: '"urn:cintoo:subscription:" followed by an UUIDv4

        '
    UserId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    ProjectUrn:
      type: string
      description: '"urn:cintoo:project:" followed by an UUIDv4

        '
    UserUrn:
      type: string
      description: '"urn:cintoo:user:" followed by an UUIDv4

        '
    AccountId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    Workzone:
      type: object
      required:
      - id
      - type
      - api1Id
      - projectId
      - rootWorkzoneId
      - name
      - description
      - roleIds
      - modificationInfo
      - statsInfo
      x-tags:
      - Workzone
      properties:
        id:
          readOnly: true
          $ref: '#/components/schemas/WorkzoneUrn'
        type:
          type: string
          enum:
          - workzone
        projectId:
          $ref: '#/components/schemas/ProjectUrn'
        parentId:
          $ref: '#/components/schemas/WorkzoneUrn'
          description: '`WorkzoneUrn` of the parent Workzone. Null if the work zone is a rootWorkzone.'
        rootWorkzoneId:
          $ref: '#/components/schemas/WorkzoneUrn'
        name:
          type: string
          example: New Workzone
        description:
          type: string
        roleIds:
          type: array
          items:
            $ref: '#/components/schemas/RoleUrn'
        coverBlobName:
          $ref: '#/components/schemas/BlobName'
        coverUrl:
          type: string
        modificationInfo:
          $ref: '#/components/schemas/ModificationInfo'
        statsInfo:
          $ref: '#/components/schemas/WorkzoneStatsInfo'
    RoleUrn:
      type: string
      description: '"urn:cintoo:role:" followed by an UUIDv4

        '
    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"
    WorkzoneId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    workzoneCreate:
      type: object
      required:
      - name
      - parentWorkzoneId
      properties:
        name:
          type: string
        parentWorkzoneId:
          $ref: '#/components/schemas/WorkzoneRef'
        description:
          type: string
        coverUrl:
          type: string
    ErrorForbidden:
      type: object
      required:
      - status
      - title
      properties:
        status:
          type: integer
          format: int32
          enum:
          - 403
        title:
          type: string
          enum:
          - Forbidden
        detail:
          type: string
          description: human readable description of the error in english
    ModificationInfo:
      type: object
      required:
      - createdBy
      - isDeleted
      properties:
        createdAt:
          type: string
          allOf:
          - $ref: '#/components/schemas/DateTime'
        createdBy:
          $ref: '#/components/schemas/UserUrn'
        updatedAt:
          type: string
          allOf:
          - $ref: '#/components/schemas/DateTime'
        updatedBy:
          type: string
          allOf:
          - $ref: '#/components/schemas/UserUrn'
        deletedAt:
          type: string
          allOf:
          - $ref: '#/components/schemas/DateTime'
        deletedBy:
          type: string
          allOf:
          - $ref: '#/components/schemas/UserUrn'
        isDeleted:
          type: boolean
    UserRef:
      oneOf:
      - $ref: '#/components/schemas/UserUrn'
      - $ref: '#/components/schemas/UserId'
    WorkzoneStatsInfo:
      type: object
      required:
      - scanCount
      - scanSize
      - tagCount
      properties:
        scanCount:
          type:
          - integer
          - 'null'
        scanSize:
          type:
          - integer
          - 'null'
        tagCount:
          type:
          - integer
          - 'null'
    WorkzoneRef:
      oneOf:
      - $ref: '#/components/schemas/WorkzoneUrn'
      - $ref: '#/components/schemas/WorkzoneId'
    SubscriptionId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    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
    Uuid:
      type: string
      description: UUIDv4
      format: uuid
      example: 156fff1a-0ef7-4335-891a-627928a19e29
    ProjectId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    ErrorBadRequest:
      type: object
      required:
      - status
      - title
      properties:
        status:
          type: integer
          format: int32
          enum:
          - 400
        title:
          type: string
          enum:
          - Bad Request
        detail:
          type: string
          description: human readable description of the error in english
  parameters:
    userRef:
      name: userRef
      in: path
      required: true
      description: The Id or Urn of the user
      schema:
        $ref: '#/components/schemas/UserRef'
    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'
    allowRemoveOnParents:
      name: allowRemoveOnParents
      in: query
      required: false
      description: '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.

        '
      schema:
        type: boolean
        default: false
    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'
  responses:
    UnexpectedError:
      description: unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            '400':
              value:
                status: 400
                title: Bad Request
            '401':
              value:
                status: 401
                title: Unauthorized
            '403':
              value:
                status: 403
                title: Forbidden
            '404':
              value:
                status: 404
                title: Not Found
            '405':
              value:
                status: 405
                title: Method Not Allowed
            '406':
              value:
                status: 406
                title: Not Acceptable
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://aec.cintoo.com/oauth/authorize
          tokenUrl: https://aec.cintoo.com/oauth/token
          scopes: {}
          refreshUrl: https://aec.cintoo.com/oauth/token
x-tagGroups:
- name: General
  tags:
  - errors_list
  - internal_information
  - token_management
  - Permissions
  - Authentication
- name: Resources
  tags:
  - Resources
- name: Tenant
  tags:
  - Tenant
- name: Account
  tags:
  - Account
  - Subscription
  - Role
  - User
  - Group
  - Trusted Device
- name: Subscription
  tags:
  - Usage Report
- name: Project
  tags:
  - Project
  - Members
  - Workzone
- name: Project Data
  tags:
  - File
  - Annotation
  - Saved View
  - Share Link
  - Crop
  - Measurement
  - Tag List
  - Tag
- name: Jobs
  tags:
  - Progress Monitoring
  - Import Model
  - Export Scene
  - Segmentation
  - Video360
  - Import IDD
- name: Integrations
  tags:
  - Integrations
  - Konekt
  - Autodesk
  - Procore
- name: Tutorials
  tags:
  - tuto_upload_file
  - understand_tag_data