Cintoo Annotation API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Cintoo Open Annotation 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: Annotation
paths:
  /api/2/accounts/{accountRef}/projects/{projectRef}/annotations:
    get:
      summary: List annotations in a project
      operationId: getAnnotationsFromProject
      description: 'BETAList all annotations in a project


        Only annotations on work zones where the user has the permission `workzone:annotations:read` are returned.'
      tags:
      - Annotation
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      - $ref: '#/components/parameters/includeComments'
      - $ref: '#/components/parameters/includeAttachments'
      responses:
        '200':
          description: List of annotations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Annotation'
        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/annotations\" \\\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/annotations\"\n    % (host, accountUUID, projectUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/annotations`;\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 an annotation
      operationId: createAnnotation
      description: 'BETACreate an annotation


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


        A maximum of 3000 annotations are allowed on the same project. If this limit is reached, an error 400 with

        error code `project-max-annotations` is returned.'
      tags:
      - Annotation
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/annotationCreate'
      responses:
        '201':
          description: The annotation was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport WORKZONEID=...\n\ncurl --request POST --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations\" \\\n  --header \"Authorization: Bearer $TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data \"{\\\"workzoneId\\\":\\\"$WORKZONEID\\\",\\\"type\\\":\\\"Note\\\",\\\"title\\\":\\\"test\\\",\\\"description\\\":\\\"test\\\",\\\"position\\\":\\\"1,2,3\\\"}\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nworkzoneId = \"\"\ntoken = \"...\"\n\nresponse = requests.post(\n  \"https://%s/api/2/accounts/%s/projects/%s/annotations\"\n    % (host, accountUUID, projectUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token },\n  json = {\n    \"workzoneId\": workzoneId,\n    \"type\": \"Note\",\n    \"title\": \"test\",\n    \"description\": \"test\",\n    \"position\": \"1,2,3\"\n  }\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst token = \"...\";\nconst workzoneId = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/annotations`;\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    {\"workzoneId\":workzoneId,\"type\":\"Note\",\"title\":\"test\",\"description\":\"test\",\"position\":\"1,2,3\"}\n  ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
  /api/2/accounts/{accountRef}/projects/{projectRef}/annotations/{annotationRef}:
    get:
      summary: Get annotation
      operationId: getAnnotationById
      description: 'BETARetrieve an annotation, optionally with comments and attachments


        Requires the permission `workzone:annotations:read` on the work zone where the annotation is.'
      tags:
      - Annotation
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      - $ref: '#/components/parameters/annotationRef'
      - $ref: '#/components/parameters/includeComments'
      - $ref: '#/components/parameters/includeAttachments'
      responses:
        '200':
          description: The content of the annotation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport ANNOTATIONID=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations/$ANNOTATIONID\" \\\n  --header \"Authorization: Bearer $TOKEN\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nannotationId = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n  \"https://%s/api/2/accounts/%s/projects/%s/annotations/%s\"\n    % (host, accountUUID, projectUUID, annotationId),\n  headers = { \"Authorization\": \"Bearer %s\" % token}\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst annotationId = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/annotations/${annotationId}`;\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"
    put:
      summary: Update an annotation
      operationId: updateAnnotation
      description: 'BETAUpdate an annotation


        ⚠ Overwrites all fields. Missing fields will be considered as null and current values will be erased


        Requires the permission `workzone:annotations:write` on the work zone.'
      tags:
      - Annotation
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      - $ref: '#/components/parameters/annotationRef'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/annotationUpdate'
      responses:
        '200':
          description: The annotation was updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport ANNOTATIONUUID=...\n\ncurl --request PUT --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations/$ANNOTATIONUUID\" \\\n  --header \"Authorization: Bearer $TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data \"{\\\"type\\\":\\\"Note\\\",\\\"title\\\":\\\"test\\\",\\\"description\\\":\\\"test\\\",\\\"position\\\":\\\"1,2,3\\\"}\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nannotationUUID = \"\"\ntoken = \"...\"\n\nresponse = requests.put(\n  \"https://%s/api/2/accounts/%s/projects/%s/annotations/%s\"\n    % (host, accountUUID, projectUUID, annotationUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token },\n  json = {\n    \"type\": \"Note\",\n    \"title\": \"test\",\n    \"description\": \"test\",\n    \"position\": \"1,2,3\"\n  }\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst annotationUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/annotations/${annotationUUID}`;\nconst res = await fetch(url, {\n  method: \"PUT\",\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify(\n    {\"type\":\"Note\",\"title\":\"test\",\"description\":\"test\",\"position\":\"1,2,3\"}\n  ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
    delete:
      summary: Delete an annotation
      operationId: deleteAnnotation
      description: 'BETADelete an annotation


        Requires the permission `workzone:annotations:write` on the work zone.'
      tags:
      - Annotation
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      - $ref: '#/components/parameters/annotationRef'
      responses:
        '204':
          description: The annotation was deleted successfully
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport ANNOTATIONUUID=...\n\ncurl --request DELETE --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations/$ANNOTATIONUUID\" \\\n  --header \"Authorization: Bearer $TOKEN\" \\\n  --header \"Content-Type: application/json\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nannotationUUID = \"\"\ntoken = \"...\"\n\nresponse = requests.delete(\n  \"https://%s/api/2/accounts/%s/projects/%s/annotations/%s\"\n    % (host, accountUUID, projectUUID, annotationUUID),\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 annotationUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/annotations/${annotationUUID}`;\nconst res = await fetch(url, {\n  method: \"DELETE\",\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n    \"Content-Type\": \"application/json\",\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}/annotations/{annotationRef}/comments:
    post:
      summary: Create a comment on an annotation
      operationId: createAnnotationComment
      description: 'BETACreate a comment on an annotation


        Requires the permission `workzone:annotations:write` on the work zone.'
      tags:
      - Annotation
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      - $ref: '#/components/parameters/annotationRef'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/annotationCommentCreate'
      responses:
        '201':
          description: The comment was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationComment'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\nexport PROJECTUUID=...\nexport ANNOTATIONUUID=...\n\ncurl --request POST --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/projects/$PROJECTUUID/annotations/$ANNOTATIONUUID/comments\" \\\n  --header \"Authorization: Bearer $TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data \"{\\\"description\\\":\\\"my comment\\\"}\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\nprojectUUID = \"...\"\nannotationUUID = \"\"\ntoken = \"...\"\n\nresponse = requests.post(\n  \"https://%s/api/2/accounts/%s/projects/%s/annotations/%s/comments\"\n    % (host, accountUUID, projectUUID, annotationUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token },\n  json = {\n    \"description\": \"my comment\"\n  }\n)\nprint(response.status_code)\nprint(response.json())\n"
      - lang: TypeScript
        source: "const host = \"aec.cintoo.com\";\nconst accountUUID = \"...\";\nconst projectUUID = \"...\";\nconst annotationUUID = \"...\";\nconst token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/annotations/${annotationUUID}/comments`;\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    {\"description\":\"my comment\"}\n  ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
components:
  schemas:
    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
    FormatUrn:
      type: string
      description: '"urn:cintoo:format:" followed by a number

        '
    AnnotationAttachmentUrn:
      type: string
      description: '"urn:cintoo:annotation-attachment:" followed by an UUIDv4

        '
    SavedViewData:
      oneOf:
      - type: object
        title: legacy
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - legacy
            description: internal legacy representation, do not use (subject to changes and deprecation)
      - type: object
        title: others
        required:
        - type
        properties:
          type:
            type: string
            description: structure will be defined in the future
        additionalProperties: true
    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"
    ProjectId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    AnnotationId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    Uuid:
      type: string
      description: UUIDv4
      format: uuid
      example: 156fff1a-0ef7-4335-891a-627928a19e29
    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'
    ProjectUrn:
      type: string
      description: '"urn:cintoo:project:" followed by an UUIDv4

        '
    FileUrn:
      type: string
      description: '"urn:cintoo:file:" followed by an UUIDv4

        '
    AnnotationCommentUrn:
      type: string
      description: '"urn:cintoo:annotation-comment:" followed by an UUIDv4

        '
    annotationCommentCreate:
      type: object
      required:
      - description
      properties:
        description:
          type: string
          minLength: 1
        attachments:
          type: array
          items:
            type: string
            example: '{blobName}'
          description: blob names
    AccountUrn:
      type: string
      description: '"urn:cintoo:account:" followed by an UUIDv4

        '
    AnnotationIntegration:
      type: object
      required:
      - type
      - url
      x-tags:
      - Annotation
      properties:
        type:
          type: string
          enum:
          - AUTODESK
          - NEWFORMA_KONEKT
          - PROCORE
        url:
          type:
          - string
          - 'null'
    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
    FileAttribute:
      type: object
      required:
      - id
      - size
      - name
      - formatId
      - blob
      - blobName
      properties:
        id:
          $ref: '#/components/schemas/FileUrn'
        size:
          type: integer
          format: int64
        name:
          type: string
        formatId:
          $ref: '#/components/schemas/FormatUrn'
        blob:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/BlobName'
        blobName:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/BlobName'
    AnnotationComment:
      type: object
      required:
      - id
      - type
      - modificationInfo
      - attachedTo
      - description
      - descriptionText
      - attachments
      x-tags:
      - Annotation
      properties:
        id:
          readOnly: true
          $ref: '#/components/schemas/AnnotationCommentUrn'
        type:
          type: string
          enum:
          - annotation-comment
        modificationInfo:
          $ref: '#/components/schemas/ModificationInfo'
        attachedTo:
          $ref: '#/components/schemas/AnnotationUrn'
        description:
          type:
          - string
          - 'null'
        descriptionText:
          type: string
        attachments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AnnotationCommentAttachment'
    AnnotationUrn:
      type: string
      description: '"urn:cintoo:annotation:" followed by an UUIDv4

        '
    Annotation:
      type: object
      required:
      - id
      - type
      - workzoneId
      - modificationInfo
      - annotationType
      - title
      - description
      - descriptionText
      - assignedTo
      - dueDate
      - priority
      - number
      - position
      - normal
      - imgBlobName
      - savedView
      - modelElementGUIDs
      - comments
      - attachments
      - labels
      - integrations
      x-tags:
      - Annotation
      properties:
        id:
          readOnly: true
          $ref: '#/components/schemas/AnnotationUrn'
        type:
          type: string
          enum:
          - annotation
        workzoneId:
          $ref: '#/components/schemas/WorkzoneUrn'
        modificationInfo:
          $ref: '#/components/schemas/ModificationInfo'
        annotationType:
          type: string
          enum:
          - Private note
          - Note
          - Issue
          - Resolved
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        descriptionText:
          type: string
        assignedTo:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UserUrn'
        dueDate:
          type:
          - string
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Date'
        priority:
          type:
          - integer
          - 'null'
        number:
          type:
          - integer
          - 'null'
        position:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Point3D'
        normal:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Point3D'
        imgBlobName:
          type:
          - string
          - 'null'
        savedView:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/SavedViewData'
        modelElementGUIDs:
          type:
          - array
          - 'null'
          items:
            type: string
        comments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AnnotationComment'
        attachments:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AnnotationAttachment'
        labels:
          type: array
          items:
            type: string
        integrations:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationIntegration'
    Date:
      type: string
      format: date
      description: 'The date-time notation as defined by RFC 3339, section 5.6 (ex: 2017-08-18)'
      example: '2017-07-21'
    AccountId:
      allOf:
      - $ref: '#/components/schemas/Uuid'
      example: 8196e320-8a4d-4d29-b0a9-077cd7ed3368
    annotationUpdate:
      type: object
      required:
      - annotationType
      - title
      - position
      properties:
        annotationType:
          type: string
          enum:
          - Private note
          - Note
          - Issue
          - Resolved
        title:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type:
          - string
          - 'null'
        assignedTo:
          type: array
          items:
            $ref: '#/components/schemas/UserUrn'
        dueDate:
          type: string
          format: date
        priority:
          type: integer
          enum:
          - 0
          - 1
          - 5
          - 8
          - 10
        imgBlobName:
          type: string
        position:
          $ref: '#/components/schemas/Point3D'
        normal:
          $ref: '#/components/schemas/Point3D'
        savedView:
          $ref: '#/components/schemas/SavedViewData'
        modelElementGUIDs:
          type:
          - array
          - 'null'
          items:
            type: string
        labels:
          type: array
          items:
            type: string
        attachments:
          type: array
          items:
            type: string
            example: '{blobName}'
          description: blob names
    UserUrn:
      type: string
      description: '"urn:cintoo:user:" followed by an UUIDv4

        '
    WorkzoneUrn:
      type: string
      pattern: ^urn:cintoo:workzone:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      description: '"urn:cintoo:workzone:" followed by an UUIDv4

        '
    Point3D:
      type: object
      required:
      - x
      - y
      - z
      properties:
        x:
          type: number
          format: double
        y:
          type: number
          format: double
        z:
          type: number
          format: double
    AnnotationCommentAttachment:
      type: object
      required:
      - id
      - type
      - attachedTo
      - file
      x-tags:
      - Annotation
      properties:
        id:
          readOnly: true
          $ref: '#/components/schemas/AnnotationCommentAttachmentUrn'
        type:
          type: string
          enum:
          - annotation-comment-attachment
        attachedTo:
          $ref: '#/components/schemas/AnnotationCommentUrn'
        file:
          $ref: '#/components/schemas/FileAttribute'
    annotationCreate:
      type: object
      required:
      - workzoneId
      - annotationType
      - title
      - position
      - savedView
      properties:
        workzoneId:
          $ref: '#/components/schemas/WorkzoneUrn'
        annotationType:
          type: string
          enum:
          - Private note
          - Note
          - Issue
          - Resolved
        title:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type:
          - string
          - 'null'
        assignedTo:
          type: array
          items:
            $ref: '#/components/schemas/UserUrn'
        dueDate:
          type: string
          format: date
        priority:
          type: integer
          enum:
          - 0
          - 1
          - 5
          - 8
          - 10
        imgBlobName:
          type: string
        position:
          $ref: '#/components/schemas/Point3D'
        normal:
          $ref: '#/components/schemas/Point3D'
        savedView:
          $ref: '#/components/schemas/SavedViewData'
        modelElementGUIDs:
          type:
          - array
          - 'null'
          items:
            type: string
        labels:
          type: array
          items:
            type: string
        attachments:
          type: array
          items:
            type: string
            example: '{blobName}'
          description: blob names
    AnnotationCommentAttachmentUrn:
      type: string
      description: '"urn:cintoo:annotation-comment-attachment:" followed by an UUIDv4

        '
    AnnotationAttachment:
      type: object
      required:
      - id
      - type
      - attachedTo
      - file
      x-tags:
      - Annotation
      properties:
        id:
          readOnly: true
          $ref: '#/components/schemas/AnnotationAttachmentUrn'
        type:
          type: string
          enum:
          - annotation-attachment
        attachedTo:
          $ref: '#/components/schemas/AnnotationUrn'
        file:
          $ref: '#/components/schemas/FileAttribute'
  parameters:
    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'
    includeComments:
      name: includeComments
      in: query
      required: false
      description: 'If true the operation retrieves comments attached to each annotation,

        else the comments field will not be returned.

        '
      schema:
        type: boolean
        default: false
    annotationRef:
      name: annotationRef
      in: path
      required: true
      description: The Id or Urn of the annotation
      schema:
        oneOf:
        - $ref: '#/components/schemas/AnnotationUrn'
        - $ref: '#/components/schemas/AnnotationId'
    includeAttachments:
      name: includeAttachments
      in: query
      required: false
      description: 'If true the operation retrieves information about files attached to each annotation or comment,

        else the attachments field will not be returned.

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