Cintoo Integrations API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Cintoo Open Integrations 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: Integrations
paths:
  /api/2/accounts/{accountRef}/integrations:
    get:
      summary: List integrations on the account
      operationId: getAccountIntegrations
      description: 'BETAList all integrations on the account


        Requires the permission `account:integrations:read` automatically granted for account administrators and account owner.'
      tags:
      - Integrations
      parameters:
      - $ref: '#/components/parameters/accountRef'
      responses:
        '200':
          description: List of integrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountIntegrations'
        4XX:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
      - lang: cURL
        source: "export TOKEN=...\nexport ACCOUNTUUID=...\n\ncurl --url \"https://aec.cintoo.com/api/2/accounts/$ACCOUNTUUID/integrations\" \\\n  --header \"Authorization: Bearer $TOKEN\"\n"
      - lang: Python
        source: "import requests\n\nhost = \"aec.cintoo.com\"\naccountUUID = \"...\"\ntoken = \"...\"\n\nresponse = requests.get(\n  \"https://%s/api/2/accounts/%s/integrations\"\n    % (host, accountUUID),\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 token = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/integrations`;\nconst res = await fetch(url, {\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n  },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
  /api/2/accounts/{accountRef}/projects/{projectRef}/annotations/bulk-create-integration:
    post:
      summary: Create integration links on annotations
      operationId: createAnnotationIntegrationLinks
      description: 'BETACreate integration links on annotations


        Requires the permission `project:annotations:create-integration-link` on the project, which is automatically

        granted for users having the permission `workzone:annotations:write` on the root work zone.


        Pre-requisites: to be created, an integration link needs the project to have a valid configuration:

        * An active subscription with BCM enabled

        * For Autodesk:

        * the project must be configured and linked to an Autodesk hub and project

        * a valid Autodesk token must exist for the user who created the annotation (logged in)

        * For Procore:

        * the project must be configured and linked to a Procore company and project

        * a valid Procore token must exist for the user who created the annotation (logged in)

        * For Newforma Konekt:

        * A valid Newforma Konekt token must exist on the account

        * The project must be configured and linked to a Konekt hub and project'
      tags:
      - Integrations
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/annotationCreateIntegrationLinks'
      responses:
        '202':
          description: "Returns the list of annotations' URN for which links have been initialized, and for each annotation the types of\nintegration that have been initialized.\n\nIf an annotation is not returned, or a requested integration type is not returned for an annotation,\nit means one of those situations:\n * the link already exist\n * the link cannot be created because the configuration is incorrect or missing\n\nAfter this call, the links are initialized but the creation will be processed by an asynchronous batch.\nTo check the status, you can get the annotations, and check the `integrations` field. In this field,\nan integration with inner field `url` set to `null` means it is still pending.\nOnce the `url` field is not null, it means the link has been successfully created.\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationBulkCreateIntegrationLinksResponse'
        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/bulk-create-integration\" \\\n  --header \"Authorization: Bearer $TOKEN\" \\\n  --header \"Content-Type: application/json\" \\\n  --data \"{\\\"annotations\\\":[\\\"$ANNOTATIONUUID\\\"], \\\"integrationTypes\\\":[\\\"AUTODESK\\\",\\\"PROCORE\\\"]}\"\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/bulk-create-integration\"\n    % (host, accountUUID, projectUUID),\n  headers = { \"Authorization\": \"Bearer %s\" % token },\n  json = {\n    \"annotations\": [annotationUUID],\n    \"integrationTypes\": [\"AUTODESK\",\"PROCORE\"]\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 annotationUUID = \"...\";\n\nconst url = `https://${host}/api/2/accounts/${accountUUID}/projects/${projectUUID}/annotations/bulk-create-integration`;\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    {\"annotations\":[annotationUUID], \"integrationTypes\":[\"AUTODESK\",\"PROCORE\"]}\n  ),\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
  /api/2/accounts/{accountRef}/projects/{projectRef}/integrations:
    get:
      summary: List integrations on the project
      operationId: getProjectIntegrations
      description: 'BETAList all integrations on the project


        Requires the permission `project:integrations:read` automatically granted for users having

        `workzone:annotations:write` on the root work zone of the project.'
      tags:
      - Integrations
      parameters:
      - $ref: '#/components/parameters/accountRef'
      - $ref: '#/components/parameters/projectRef'
      responses:
        '200':
          description: List of integrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectIntegrations'
        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/integrations\" \\\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/integrations\"\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}/integrations`;\nconst res = await fetch(url, {\n  headers: {\n    \"Authorization\": `Bearer ${token}`,\n  },\n});\n\nconsole.log(res.status);\nconst data = await res.json();\nconsole.log(data);\n"
components:
  schemas:
    ProjectIntegrations:
      type: object
      properties:
        konekt:
          $ref: '#/components/schemas/ProjectIntegrationKonekt'
        autodesk:
          $ref: '#/components/schemas/ProjectIntegrationAutodesk'
    AccountUrn:
      type: string
      description: '"urn:cintoo:account:" followed by an UUIDv4

        '
    AnnotationBulkCreateIntegrationLinksResponse:
      type: object
      required:
      - created
      properties:
        created:
          type: object
          description: Each key is an annotation URN, values are integration types initialized for the annotation
          additionalProperties:
            x-additionalPropertiesName: urn:cintoo:annotation:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
            type: array
            items:
              type: string
              enum:
              - AUTODESK
              - NEWFORMA_KONEKT
              - PROCORE
          example:
            urn:cintoo:annotation:956b7fb8-ad08-4f63-bed2-f958f0bf2e2c:
            - AUTODESK
            - PROCORE
            urn:cintoo:annotation:2d90addd-e3fb-4a0c-b54a-af09e17687e2:
            - NEWFORMA_KONEKT
    AccountIntegrationKonekt:
      type: object
      x-tags:
      - Konekt
      required:
      - id
      - konektId
      - beta
      - modificationInfo
      - link
      - options
      - name
      - connected
      - konektProjects
      - linkedProjects
      properties:
        id:
          $ref: '#/components/schemas/AccountIntegrationKonektUrn'
        konektId:
          type: string
          description: id of the hub on Konekt
        beta:
          type: boolean
          description: indicates if the hub is on Konekt beta or Konekt production
        modificationInfo:
          $ref: '#/components/schemas/ModificationInfo'
        link:
          type: string
        options:
          $ref: '#/components/schemas/AccountIntegrationNewformaKonektOptions'
        name:
          type: string
          description: name of the hub on Konekt if available
        connected:
          type: boolean
          description: indicates if a valid token is configured
        konektProjects:
          type: array
          items:
            $ref: '#/components/schemas/ProjectInKonektHub'
          description: list of projects on the Konekt Hub
        linkedProjects:
          type: array
          items:
            $ref: '#/components/schemas/AccountIntegrationNewformaKonektLinkedProject'
          description: Cintoo projects configured with this Konekt Hub
    annotationCreateIntegrationLinks:
      type: object
      required:
      - integrationTypes
      properties:
        annotations:
          type:
          - array
          - 'null'
          description: If omitted or null, all annotations of the project will be processed.
          items:
            $ref: '#/components/schemas/AnnotationUrn'
        integrationTypes:
          type: array
          items:
            type: string
            enum:
            - AUTODESK
            - NEWFORMA_KONEKT
            - PROCORE
    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'
    AccountIntegrationNewformaKonektOptions:
      type: object
      required:
      - allowCreateNewUsersOnHub
      - syncStrategy
      properties:
        allowCreateNewUsersOnHub:
          type: boolean
          description: if true it allows to create automatically new users on the Konekt Hub when synchronizing data
        syncStrategy:
          type: string
          enum:
          - CONFIG_ON_PROJECT
          - BOTH_WAY
          - UPDATES_ONLY_FROM_KONEKT
          description: 'CONFIG_ON_PROJECT means the option needs to be configured on each project.


            BOTH_WAY means an update on Cintoo triggers an update on Konekt.


            UPDATES_ONLY_FROM_KONEKT means an update on Cintoo does not trigger an update on Konekt.


            BOTH_WAY and UPDATES_ONLY_FROM_KONEKT means an update on Konekt will trigger an update on Cintoo.

            '
    ProjectIntegrationNewformaKonektOptions:
      type: object
      required:
      - allowInviteUsers
      - syncStrategy
      properties:
        allowInviteUsers:
          type: boolean
          description: if true it allows to invite users on the Konekt project when synchronizing data
        syncStrategy:
          type: string
          enum:
          - BOTH_WAY
          - UPDATES_ONLY_FROM_KONEKT
          description: 'BOTH_WAY means an update on Cintoo triggers an update on Konekt.


            UPDATES_ONLY_FROM_KONEKT means an update on Cintoo does not trigger an update on Konekt.


            BOTH_WAY and UPDATES_ONLY_FROM_KONEKT means an update on Konekt will trigger an update on Cintoo.

            '
    ProjectIntegrationAutodesk:
      type: object
      x-tags:
      - Autodesk
      required:
      - projectId
      - autodeskHubId
      - autodeskProjectId
      - link
      - createdAt
      - createdBy
      - updatedAt
      - updatedBy
      properties:
        projectId:
          $ref: '#/components/schemas/ProjectUrn'
        autodeskHubId:
          type: string
        autodeskProjectId:
          type: string
        link:
          type: string
        createdAt:
          $ref: '#/components/schemas/DateTime'
        createdBy:
          $ref: '#/components/schemas/UserUrn'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
        updatedBy:
          $ref: '#/components/schemas/UserUrn'
    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
    AccountIntegrations:
      type: object
      required:
      - konekt
      properties:
        konekt:
          type: array
          items:
            $ref: '#/components/schemas/AccountIntegrationKonekt'
    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
    ProjectInKonektHub:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: id of the project on Konekt
        name:
          type: string
          description: name of the project on Konekt
    ProjectIntegrationKonekt:
      type: object
      x-tags:
      - Konekt
      required:
      - projectId
      - hubId
      - konektId
      - options
      - link
      - createdAt
      - createdBy
      - updatedAt
      - updatedBy
      properties:
        projectId:
          $ref: '#/components/schemas/ProjectUrn'
        hubId:
          type: string
          description: id of the hub on Konekt
        konektId:
          type: integer
          description: id of the project on Konekt
        options:
          $ref: '#/components/schemas/ProjectIntegrationNewformaKonektOptions'
        link:
          type: string
        createdAt:
          $ref: '#/components/schemas/DateTime'
        createdBy:
          $ref: '#/components/schemas/UserUrn'
        updatedAt:
          $ref: '#/components/schemas/DateTime'
        updatedBy:
          $ref: '#/components/schemas/UserUrn'
    AccountIntegrationKonektUrn:
      type: string
      description: '"urn:cintoo:newforma-konekt-hub:" followed by an UUIDv4

        '
    AnnotationUrn:
      type: string
      description: '"urn:cintoo:annotation:" followed by an UUIDv4

        '
    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
    AccountIntegrationNewformaKonektLinkedProject:
      type: object
      required:
      - id
      - konektId
      - options
      properties:
        id:
          $ref: '#/components/schemas/ProjectUrn'
        konektId:
          type: integer
        options:
          $ref: '#/components/schemas/ProjectIntegrationNewformaKonektOptions'
    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
  parameters:
    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'
  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