NAV Navigation
HTTP

BCF REST API v2.1

Introduction

BCF-API v2.1

Go to the official BCF REST API for full documentation.

Catenda BCF-API is based on the official BCF REST API

What is described here

Topic Boards and BCF

A "topic board" is the same as a BCF project, and a "topic" is the same as a BCF topic. In bimsync, you may have multiple topic boards in the same project.

project_id points to the topic board, while bimsync_project_id points to the Catenda project

Users are managed within a Catenda project.

Getting Started

The Catenda BCF REST API is available at https://api.catenda.com/opencde. All API access is over HTTPS. Data is sent as query parameters and JSON data, and received as JSON.

Registration

Contact Catenda support to register your app.

Authentication

Authentication is based on the OAuth 2.0 Protocol. First you must retrieve the oauth2_auth_url and the oauth2_token_url.

Get authentication URLs

Example request

GET https://api.catenda.com/opencde/bcf/2.1/auth

Example response

{
    "oauth2_auth_url": "https://api.catenda.com/oauth2/authorize",
    "oauth2_token_url": "https://api.catenda.com/oauth2/token",
    "http_basic_supported": "false",
    "supported_oauth2_flows": [
        "authorization_code_grant"
    ]
}

Follow Catenda authentication documentation to retrieve the access token.

When requesting other resources the access token must be passed via the Authorization header using the Bearer scheme (e.g. Authorization: Bearer T9UNRV4sC9vr7ga)

Returns the oauth2_auth_url, the oauth2_token_url.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/auth

Response schema

auth_GET.json

Version

Get BCF API version

Example request

GET https://api.catenda.com/opencde/bcf/versions

Example response

{
    "versions": [
        {
            "version_id": "2.0",
            "detailed_version": "bimsync BCF API 2.0 version. BCF-xml schema version: 2.0. Documentation: https://api.catenda.com/developers/reference/bcf/2.0"
        },
        {
            "version_id": "2.1",
            "detailed_version": "Beta. bimsync BCF API 2.1 version. BCF-xml schema version: 2.1. Documentation: https://api.catenda.com/developers/reference/bcf/v2_1."
        }
    ]
}

Return all available BCF REST API versions. A version_id must be added to underlying resource URLs. If version_id equals 2.1, then the project's URL will be https://api.catenda.com/opencde/bcf/2.1/projects.

This resource does not require any authorization.

Resource URL

https://api.catenda.com/opencde/bcf/versions

Response schema

version_GET.json

User

Get current user

Example request

GET https://api.catenda.com/opencde/bcf/2.1/current-user

Example response

{
    "name": "User 1",
    "id": "user1@test.com"
}

Return the current user.

Users have 2 attributes. name and id. name is the name of the user. id is the email-address of the user.

Note: This resource is in addition to the BCF-API standard

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/current-user

Topic Board

Get topic board

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e

Example response

{
    "project_id": "3c34c9b3-1b9b-4750-a4f3-0641d58fe48e",
    "name": "My BCF project",
    "bimsync_project_name": "My Catenda project",
    "bimsync_project_id": "08b7c8adf14a4805a2c34681ab3869af",
    "bimsync_issue_board_name": "My BCF project"
}

Return the issue board.

The response includes bimsync_project_name, bimsync_project_id and bimsync_issue_board_name.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}

Response schema

project_GET.json

Get topic boards

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects?bimsync_project_id=71b7cefda7574e73beb80f23496f18b8

Example response

[
    {
        "project_id": "c0784b27-5057-43f6-bdb3-3607f4da86b0",
        "name": "Topic board 1",
        "bimsync_project_name": "My Catenda project",
        "bimsync_project_id": "71b7cefda7574e73beb80f23496f18b8",
        "bimsync_issue_board_name": "Topic board 1"
    },
    {
        "project_id": "5af9e867-659d-4eee-ae56-2370aaf8aabe",
        "name": "Topic board 2",
        "bimsync_project_name": "My Catenda project",
        "bimsync_project_id": "71b7cefda7574e73beb80f23496f18b8",
        "bimsync_issue_board_name": "Topic board 2"
    }
]

Return the topic boards you have access to.

The response also includes bimsync_project_name, bimsync_project_id and bimsync_issue_board_name.

Note: A Catenda project may have multiple topic boards. Use the bimsync_project_id query parameter to only return topic boards from the specified Catenda project. Use bimsync_archived to filter topic boards based on their archived status.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects

Query Parameters

NameTypeDescription
bimsync_project_id string bimsync project id Optional
bimsync_archived string archived, not-archived or all Optional, default is not-archived

Response schema

List of project_GET.json

Create topic board

Example request

POST https://api.catenda.com/opencde/bcf/2.1/projects
{
    "name": "My third BCF project",
    "bimsync_project_id": "08b7c8adf14a4805a2c34681ab3869af"
}

Example response

{
    "project_id": "485aa69d-8e25-4f68-9a97-04901b2288a7",
    "name": "My third BCF project",
    "bimsync_project_name": "My bimsync project",
    "bimsync_project_id": "08b7c8adf14a4805a2c34681ab3869af"
}

Note: The new issue board will be created in the project specified by the bimsync_project_id parameter.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
name string name of the issue board to create Mandatory
bimsync_project_id string Catenda project id Mandatory

Update topic board

Example request

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e
{
    "name": "Change my project name",
}

Example response

{
    "project_id": "3c34c9b3-1b9b-4750-a4f3-0641d58fe48e",
    "name": "Change my project name",
    "bimsync_project_name": "My Catenda project",
    "bimsync_project_id": "08b7c8adf14a4805a2c34681ab3869af",
    "bimsync_issue_board_name": "Change my project name"
}

Update the name of the topic board

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project-id}

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
name string new name of the topic board Mandatory

Request schema

project_PUT.json

Response schema

project_GET.json

Extensions

Topic board extensions

The extensions provide a list of valid values, such as statuses, types, and user emails.

Since Catenda also holds on additional information for these values, the BCF-API standard, for updating these values, is not sufficient. These resources are therefore added to Catenda BCF-API, but are not a part of the official BCF-API standard.

Statuses and types, that do not have this information, is considered unlinked. They cannot be used in new topics. Unlinked statuses and types occurs if you import a BCF-file that contains topics that have statuses or types that are not a part of the issue board extension.

Unlinked users occurs if you import a BCF-file, that references users that are not found in the project.

Get topic board extensions

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions

Example response

{
    "topic_type": [
        "Error",
        "Warning",
        "Info",
        "Unknown"
    ],
    "topic_status": [
        "Open",
        "Closed",
        "Test status"
    ],
    "topic_label": [
        "Arkitekt3"
    ],
    "snippet_type": [],
    "priority": [],
    "user_id_type": [
        "king@test.com",
        "pawn@test.com",
        "Chess mates"
    ],
    "stage": [],
    "project_actions": [
        "createTopic",
        "createDocument"
    ],
    "topic_actions": [
        "createComment",
        "createViewpoint",
        "update",
        "delete",
        "updateBimSnippet",
        "updateRelatedTopics",
        "updateDocumentReferences"
    ],
    "comment_actions": [
        "update"
    ]
}

Return the extensions.

For an issue board, the extensions provides valid values for topic types, topic statuses and users.

Note: the field user_id_type is a list of email addresses for users in the Catenda project.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions

Response schema

extensions_GET.json

Get topic board extension statuses

Example

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/statuses?include-unlinked=true
[
    {
        "name": "Open",
        "color": "#DD7E6B",
        "type": "open"
    },
    {
        "name": "Closed",
        "color": "#6AA84F",
        "type": "closed"
    },
    {
        "name": "In progress",
        "unlinked": true
    }
]

Return the extension statuses. These statuses have 3 attributes. name, color, type and unlinked. name is the name of the status. color is a hexadecimal string for the status color. type is one of three values: candidate, open, or closed. unlinked is a boolean, that is only set for statuses that are unlinked, and the value is true. These statuses do not have color or type

Note: this resource is additional to the BCF-API standard

Query Parameters

NameTypeDescription
include-unlinked boolean Should include unlinked statuses Optional

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/statuses

Create topic board extension status

Example

POST https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/statuses
{
    "name": "Icebox",
    "color": "#FFFF00",
    "type": "candidate"
}
{
    "name": "Icebox",
    "color": "#FFFF00",
    "type": "candidate"
}

Create the extension status.

Note: this resource is additional to the BCF-API standard

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
name string name of the status to create Mandatory
color string color as a hexadecimal Optional, default #000000
type string type of the status. open, closed or candidate Optional, default open

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/statuses

Update topic board extension status

Example

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/statuses
{
    "existingName": "Icebox",
    "name": "New",
    "color": "#FFFF00"
}
{
    "name": "New",
    "color": "#FFFF00",
    "type": "candidate"
}

Update the extension status. You cannot change the type of the last open status.

Note: this resource is additional to the BCF-API standard.

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
existingName string existing name of the status Mandatory
name string new name of the status Optional, default current name
color string new color as a hexadecimal Optional, default current value
type string new type of the status. open, closed or candidate Optional, default current type

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/statuses

Delete topic board extension status

Example

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/statuses
{
    "name": "New"
}

Delete the extension status.

Note: this resource is additional to the BCF-API standard. You cannot delete the last open status, or statuses that are in use.

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
name string name of the status Mandatory

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/statuses

Example

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/statuses/link
{
    "name": "Open",
    "unlinkedName": "reopened"
}
{
    "name": "Open",
    "color": "#DD7E6B",
    "type": "open"
}

Link the extension status. As described earlier, a status may be unlinked. This resource allows you to merge an unlinked status with a linked status.

Note: this resource is additional to the BCF-API standard.

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
name string name of the status Mandatory
unlinkedName string name of the unlinked status Mandatory

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/statuses/link

Get topic board extension types

Example

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/types?include-unlinked=true
[
    {
        "name": "Error",
        "color": "#DD7E6B"
    },
    {
        "name": "Warning",
        "color": "#FFFF00"
    },
    {
        "name": "Unknown",
        "unlinked": true
    }
]

Return the extension types. These types have 3 attributes. name, color, and unlinked. name is the name of the type. color is a hexadecimal string for the type color. unlinked is a boolean, that is only set for types that are unlinked, and the value is true. These types do not have color.

Note: this resource is additional to the BCF-API standard

Query Parameters

NameTypeDescription
include-unlinked boolean Should include unlinked types Optional

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/types

Create topic board extension type

Example

POST https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/types
{
    "name": "Info",
    "color": "#0000FF"
}
{
    "name": "Info",
    "color": "#0000FF"
}

Create the extension type.

Note: this resource is additional to the BCF-API standard

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
name string name of the type to create Mandatory
color string color as a hexadecimal Optional, default #000000

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/types

Update topic board extension type

Example

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/types
{
    "existingName": "Info",
    "name": "Information",
    "color": "#FFFF00"
}
{
    "name": "Information",
    "color": "#FFFF00"
}

Update the extension type.

Note: this resource is additional to the BCF-API standard.

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
existingName string existing name of the type Mandatory
name string new name of the type Optional, default current name
color string new color as a hexadecimal Optional, default current value

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/types

Delete topic board extension type

Example

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/types
{
    "name": "Error"
}

Delete the extension type. You cannot delete the last type, or types that are in use.

Note: this resource is additional to the BCF-API standard.

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
name string name of the type Mandatory

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/types

Example

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/types/link
{
    "name": "Warning",
    "unlinkedName": "Unknown"
}
{
    "name": "Warning",
    "color": "#FFFF00"
}

Link the extension type. As described earlier, a type may be unlinked. This resource allows you to merge an unlinked type with a linked type.

Note: this resource is additional to the BCF-API standard.

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
name string name of the type Mandatory
unlinkedName string name of the unlinked type Mandatory

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/types/link

Get issue board extension users

Example

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/users?include-unlinked=true
[
    {
        "name": "User 1",
        "id": "user1@test.com"
    },
    {
        "name": "User 2",
        "id": "user2@test.com"
    },
    {
        "name": "null",
        "id": "user5@test.com",
        "unlinked": true
    }
]

Return the extension users. These users have 3 attributes. name, id, and unlinked. name is the name of the user. id is the email-address of the user. unlinked is a boolean, that is only set for users that are unlinked, and the value is true.

Note: this resource is additional to the BCF-API standard

Query Parameters

NameTypeDescription
include-unlinked boolean Should include unlinked users Optional

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/users

Example

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/extensions/users/link
{
    "unlinkedUser": "user5@test.com",
    "existingUserId": "user1@test.com"
}
{
    "name": "User 1",
    "id": "user1@test.com"
}

Link the extension user. As described earlier, a user may be unlinked. This resource allows you to merge an unlinked user with a linked user.

Note: this resource is additional to the BCF-API standard.

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
existingUserId string id of the user Mandatory
unlinkedUser string id of the unlinked user Mandatory

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/users/link

Topic

Get topics

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics

Example response

[
    {
        "guid": "ea7ca636-77e9-4e89-9188-aa5fe7f53036",
        "topic_type": "Error",
        "topic_status": "Open",
        "reference_links": [],
        "title": "Door issue",
        "labels": [],
        "creation_date": "2020-02-20T15:56:03.254+0000",
        "creation_author": "king@test.com",
        "modified_date": "2020-03-02T11:11:01.771+0000",
        "modified_author": "king@test.com",
        "assigned_to": "king@test.com",
        "description": "Door is misplaced",
        "bimsync_issue_number": 2,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": {
                "ref": "fc9a1a7e2df143da887aeea27a90c400",
                "email": "team-h9TxeafTR6gWQXxF@bimsync.com",
                "name": "Chess mates"
            }
        }
    },
    {
        "guid": "0a4f77f2-7b6a-467d-ad70-32a3a6e0a345",
        "topic_type": "Warning",
        "topic_status": "Open",
        "reference_links": [],
        "title": "Heater in the air",
        "labels": [],
        "creation_date": "2020-02-20T15:55:27.507+0000",
        "creation_author": "king@test.com",
        "modified_date": "2020-03-02T11:11:12.925+0000",
        "modified_author": "king@test.com",
        "assigned_to": "pawn@test.com",
        "description": "Heater is floating in the air",
        "bimsync_issue_number": 1,
        "bimsync_assigned_to": {
            "user": {
                "ref": "f081f1857d124317b2e8f135d605f731",
                "email": "pawn@test.com",
                "name": "Pawn"
            },
            "team": {
                "ref": "fc9a1a7e2df143da887aeea27a90c400",
                "email": "team-h9TxeafTR6gWQXxF@bimsync.com",
                "name": "Chess mates"
            }
        }
    }
]

Return the topics. Default size is 100 items, max size is 500 items. Cannot return all issue boards, so a filter is required.

Filter, sort, skip and limit using OData

Odata filter parameters

ParameterTypeDescription
creation_authorstringuserId of the creation author (value from extensions)
modified_authorstringuserId of the modified author (value from extensions)
assigned_tostringuserId of the assigned person (value from extensions)
stagestringstage this topic is part of (value from extensions)
topic_statusstringstatus of a topic (value from extensions)
topic_typestringtype of a topic (value from extensions)
creation_datedatetimecreation date of a topic
modified_datedatetimemodification date of a topic
labelsarray (string)labels of a topic (value from extensions)

OData sort parameters

parameterdescription
creation_datecreation date of a topic
modified_datemodification date of a topic
indexindex of a topic

Odata example requests

Get topics that are open, assigned to Architect@example.com and created after December 5th 2015. Sort the result on last modified.

GET https://api.catenda.com/opencde/bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=assigned_to eq 'Architect@example.com' and status eq 'Open' and creation_date gt 2015-12-05T00:00:00+01:00&$orderby=modified_date desc

Get topics that have at least one of the labels 'Architecture', 'Structural' or 'Heating'.

GET https://api.catenda.com/opencde/bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=contains(labels, 'Architecture') or contains(labels, 'Structural') or contains(labels, 'Heating')

Get 50 topics and skip the first 100.

GET https://api.catenda.com/opencde/bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$top=50&$skip=100

Select

Example request with select

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics?$select=creation_date,modified_date,assigned_to

Example response with select

[
    {
        "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-06T12:31:58.018+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 12,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
    },
    {
        "guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-03T08:06:39.264+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 11,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:23.158+0000"
    }
]

Use $select as a query parameter to choose which properties to include in the response. guid and bimsync_issue_number are always returned in addition.

ParameterReturns
*all default fields
titletitle
descriptiondescription
indexindex
labelslabels
due_datedue_date
stagestage
creation_authorcreation_author, bimsync_creation_author
creation_datecreation_date, bimsync_imported_at
modified_datemodified_date
modified_authormodified_author
assigned_to, bimsync_assigned_toassigned_to, bimsync_assigned_to
topic_statustopic_status
topic_typetopic_type
topic_prioritytopic_priority
reference_linksreference_links
bim_snippetbim_snippet
bimsync_comments_sizebimsync_comments_size
bimsync_requesterbimsync_requester
bimsync_pointsbimsync_points

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics

Response schema

List of topic_GET.json

Get topic

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/ea7ca636-77e9-4e89-9188-aa5fe7f53036?includeAuthorization=true

Example response

{
    "guid": "ea7ca636-77e9-4e89-9188-aa5fe7f53036",
    "topic_type": "Error",
    "topic_status": "Open",
    "reference_links": [],
    "title": "Door issue",
    "labels": [],
    "creation_date": "2020-02-20T15:56:03.254+0000",
    "creation_author": "king@test.com",
    "modified_date": "2020-03-02T11:11:01.771+0000",
    "modified_author": "king@test.com",
    "assigned_to": "king@test.com",
    "description": "Door is misplaced",
    "authorization": {
        "topic_actions": [
            "createComment",
            "createViewpoint",
            "update",
            "delete",
            "updateRelatedTopics",
            "updateDocumentReferences"
        ],
        "topic_status": [
            "Open",
            "Closed"
        ]
    },
    "bimsync_issue_number": 2,
    "bimsync_assigned_to": {
        "user": {
            "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
            "email": "king@test.com",
            "name": "King"
        },
        "team": {
            "ref": "fc9a1a7e2df143da887aeea27a90c400",
            "email": "team-h9TxeafTR6gWQXxF@bimsync.com",
            "name": "Chess mates"
        }
    }
}

Return the topic.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
includeAuthorization boolean whether to return the authorization object Optional

Select

Example request with select

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics?$select=creation_date,modified_date,assigned_to

Example response with select

[
    {
        "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-06T12:31:58.018+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 12,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
    },
    {
        "guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-03T08:06:39.264+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 11,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:23.158+0000"
    }
]

Use $select as a query parameter to choose which properties to include in the response. guid and bimsync_issue_number are always returned in addition.

ParameterReturns
*all default fields
titletitle
descriptiondescription
indexindex
labelslabels
due_datedue_date
stagestage
creation_authorcreation_author, bimsync_creation_author
creation_datecreation_date, bimsync_imported_at
modified_datemodified_date
modified_authormodified_author
assigned_to, bimsync_assigned_toassigned_to, bimsync_assigned_to
topic_statustopic_status
topic_typetopic_type
topic_prioritytopic_priority
reference_linksreference_links
bim_snippetbim_snippet
bimsync_comments_sizebimsync_comments_size
bimsync_requesterbimsync_requester
bimsync_pointsbimsync_points

Response schema

topic_GET.json

Create topic

Example request

POST https://api.catenda.com/opencde/bcf/2.1/projects/c0784b27-5057-43f6-bdb3-3607f4da86b0/topics
{
    "topic_type": "Error",
    "topic_status": "Open",
    "title": "topic title",
    "labels": [
        "Arkitekt3"
    ],
    "creation_date": "2020-03-03T08:06:39.264+0000",
    "creation_author": "king@test.com",
    "bimsync_assigned_to": {
        "user": {
            "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
            "email": "king@test.com",
            "name": "King"
        },
        "team": null
    }
}

Example response

{
    "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
    "topic_type": "Error",
    "topic_status": "Open",
    "reference_links": [],
    "title": "title",
    "index": 2,
    "labels": [
        "Arkitekt3"
    ],
    "creation_date": "2020-03-03T08:06:39.264+0000",
    "creation_author": "king@test.com",
    "modified_date": "2020-03-03T08:06:39.264+0000",
    "assigned_to": "king@test.com",
    "bimsync_issue_number": 12,
    "bimsync_assigned_to": {
        "user": {
            "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
            "email": "king@test.com",
            "name": "King"
        },
        "team": null
    },
    "bimsync_creation_author": {
        "user": {
            "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
            "email": "king@test.com",
            "name": "King Kong"
        },
        "importedBy": null
    },
    "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
}

Create a topic.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
topic_type string type of the topic (valid values from /projects/{project_id}/extensions.topic_type) Optional, default first type from /projects/{project_id}/extensions.topic_type
topic_status string status of the topic (valid values from /projects/{project_id}/extensions.topic_status) Optional, default first open status from /projects/{project_id}/extensions.topic_status
reference_links list of string links to reference resources Optional, maximum 1
title string title of the topic Mandatory
priority string the priority of the topic (valid values from /projects/{project_id}/extensions.priority) Optional
index integer the index of the topic Optional
labels list of string the labels applied to the topic (valid values from /projects/{project_id}/extensions.topic_label) Optional
assigned_to string e-mail of the assigned user (valid values from /projects/{project_id}/extensions.user_id_type) Optional, default unassigned
stage string the stage this topic is part of (valid values from /projects/{project_id}/extensions.stage) Optional
description string description of the topic Optional
bim_snippet object contains: snippet_type, is_external, reference and reference_schema Optional
due_date string until when the issue needs to be resolved Optional
guid string guid of the topic Optional, cannot be an existing guid
bimsync_assigned_to object contains user and team Optional, overwrites assigned_to if set
bimsync_requester object contains user and team Optional
creation_date string the date of creation Optional
creation_author string the creation author Optional
includeAuthorization boolean whether to return the authorization object Optional

Select

Example request with select

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics?$select=creation_date,modified_date,assigned_to

Example response with select

[
    {
        "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-06T12:31:58.018+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 12,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
    },
    {
        "guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-03T08:06:39.264+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 11,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:23.158+0000"
    }
]

Use $select as a query parameter to choose which properties to include in the response. guid and bimsync_issue_number are always returned in addition.

ParameterReturns
*all default fields
titletitle
descriptiondescription
indexindex
labelslabels
due_datedue_date
stagestage
creation_authorcreation_author, bimsync_creation_author
creation_datecreation_date, bimsync_imported_at
modified_datemodified_date
modified_authormodified_author
assigned_to, bimsync_assigned_toassigned_to, bimsync_assigned_to
topic_statustopic_status
topic_typetopic_type
topic_prioritytopic_priority
reference_linksreference_links
bim_snippetbim_snippet
bimsync_comments_sizebimsync_comments_size
bimsync_requesterbimsync_requester

Request schema

topic_POST.json

Response schema

topic_GET.json

Update topic

Example request

PUT https://api.catenda.com/opencde/bcf/2.1/projects/c0784b27-5057-43f6-bdb3-3607f4da86b0/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96
{
    "topic_type": "Error",
    "topic_status": "Open",
    "title": "issue title",
    "labels": [
        "Arkitekt3"
    ],
    "creation_date": "2020-03-03T08:06:39.264+0000",
    "creation_author": "king@test.com",
    "bimsync_assigned_to": {
        "user": {
            "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
            "email": "king@test.com",
            "name": "King"
        },
        "team": null
    }
}

Example response

{
    "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
    "topic_type": "Error",
    "topic_status": "Open",
    "reference_links": [],
    "title": "issue title",
    "labels": [
        "Arkitekt3"
    ],
    "creation_date": "2020-03-03T08:06:39.264+0000",
    "creation_author": "king@test.com",
    "modified_date": "2020-03-03T13:11:34.380+0000",
    "modified_author": "king@test.com",
    "assigned_to": "king@test.com",
    "bimsync_issue_number": 12,
    "bimsync_assigned_to": {
        "user": {
            "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
            "email": "king@test.com",
            "name": "King"
        },
        "team": null
    },
    "bimsync_creation_author": {
        "user": {
            "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
            "email": "king@test.com",
            "name": "King Kong"
        },
        "importedBy": null
    },
    "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
}

Update the topic.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
topic_type string type of the topic (valid values from /projects/{project_id}/extensions.topic_type) Optional, default first type from /projects/{project_id}/extensions.topic_type
topic_status string status of the topic (valid values from /projects/{project_id}/extensions.topic_status) Optional, default first open status from /projects/{project_id}/extensions.topic_status
title string title of the topic Mandatory
priority string the priority of the topic (valid values from /projects/{project_id}/extensions.priority) Optional
index integer the index of the topic Optional
labels list of string the labels applied to the topic (valid values from /projects/{project_id}/extensions.topic_label) Optional
assigned_to string e-mail of the assigned user (valid values from /projects/{project_id}/extensions.user_id_type) Optional, default unassigned
stage string the stage this topic is part of (valid values from /projects/{project_id}/extensions.stage) Optional
description string description of the topic Optional
bim_snippet object contains: snippet_type, is_external, reference and reference_schema Optional
due_date string until when the issue needs to be resolved Optional
bimsync_assigned_to object contains user and team Optional, overwrites assigned_to if set
bimsync_requester object contains user and team Optional
includeAuthorization boolean whether to return the authorization object Optional

Select

Example request with select

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics?$select=creation_date,modified_date,assigned_to

Example response with select

[
    {
        "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-06T12:31:58.018+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 12,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
    },
    {
        "guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-03T08:06:39.264+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 11,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:23.158+0000"
    }
]

Use $select as a query parameter to choose which properties to include in the response. guid and bimsync_issue_number are always returned in addition.

ParameterReturns
*all default fields
titletitle
descriptiondescription
indexindex
labelslabels
due_datedue_date
stagestage
creation_authorcreation_author, bimsync_creation_author
creation_datecreation_date, bimsync_imported_at
modified_datemodified_date
modified_authormodified_author
assigned_to, bimsync_assigned_toassigned_to, bimsync_assigned_to
topic_statustopic_status
topic_typetopic_type
topic_prioritytopic_priority
reference_linksreference_links
bim_snippetbim_snippet
bimsync_comments_sizebimsync_comments_size
bimsync_requesterbimsync_requester

Request schema

topic_PUT.json

Response schema

topic_GET.json

Delete topic

Example request

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/ea7ca636-77e9-4e89-9188-aa5fe7f53036

Delete the topic. Does not return the topic.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/c0784b27-5057-43f6-bdb3-3607f4da86b0/topics/44405b7c-7bc1-4ea7-813b-e0ef156eb6db/related_topics

Example response

[
    {
        "related_topic_guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73"
    },
    {
        "related_topic_guid": "19d10dec-44dc-41f1-b63c-c6cd91c6037d"
    }
]

Get all topics related or linked to this topic in the same issue board.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/related_topics

Response schema

List of related_topic_GET.json

Catenda extension

By adding the query parameter "?includeBimsyncProjectTopics=true", related topics in different topic boards will be included in the response. The response entity will also include "bimsync_issue_board_ref" and "bimsync_issue_number"

Example request:

GET https://api.catenda.com/opencde/bcf/2.1/projects/c0784b27-5057-43f6-bdb3-3607f4da86b0/topics/44405b7c-7bc1-4ea7-813b-e0ef156eb6db/related_topics?includeBimsyncProjectTopics=true

Example response

[
    {
        "related_topic_guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73",
        "bimsync_issue_board_ref": "c0784b27-5057-43f6-bdb3-3607f4da86b0",
        "bimsync_issue_number": 1
    },
    {
        "related_topic_guid": "19d10dec-44dc-41f1-b63c-c6cd91c6037d",
        "bimsync_issue_board_ref": "c0784b27-5057-43f6-bdb3-3607f4da86b0",
        "bimsync_issue_number": 2
    }
    ,
    {
        "related_topic_guid": "68c091d8-586e-483e-b278-32e9f90dd1f7",
        "bimsync_issue_board_ref": "527a6b3a-5570-40ea-bc73-86c0bedd90e8",
        "bimsync_issue_number": 3
    }
]

Create topic relations

Example request

PUT https://api.catenda.com/opencde/bcf/2.1/projects/c0784b27-5057-43f6-bdb3-3607f4da86b0/topics/44405b7c-7bc1-4ea7-813b-e0ef156eb6db/related_topics
[
    {
        "related_topic_guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73"
    },
    {
        "related_topic_guid": "19d10dec-44dc-41f1-b63c-c6cd91c6037d"
    }
]

Example response

[
    {
        "related_topic_guid": "042bb22d-e5b3-4b8b-929c-0efa324c3655"
    },
    {
        "related_topic_guid": "83a4a803-b985-498b-8405-53a12ea85fd7"
    }
]

Create relation between the topic and all the supplied topics in the body

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/related_topics

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
related_topic_guid string the guid of the related topic Mandatory

Request schema

List of related_topic_PUT.json

Response schema

List of related_topic_GET.json

Delete topic relation

Example request

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/c0784b27-5057-43f6-bdb3-3607f4da86b0/topics/44405b7c-7bc1-4ea7-813b-e0ef156eb6db/related_topics/19d10dec-44dc-41f1-b63c-c6cd91c6037d

Delete relation between two topics. Note that if a topic is linked through a comment, this will not delete the actual comment. Does not return the deleted topic.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/related_topics/{related_topic_guid}

Get Catenda project topics

Example request

GET https://api.catenda.com/opencde/bcf/2.1/bimsync-projects/71b7cefda7574e73beb80f23496f18b8/topics/?$filter=bimsync_issue_board in ('c0784b27505743f6bdb33607f4da86b0')

Example response

[
    {
        "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
        "topic_type": "Error",
        "topic_status": "Open",
        "reference_links": [],
        "title": "topic title",
        "labels": [
            "Arkitekt3"
        ],
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "creation_author": "king@test.com",
        "modified_date": "2020-03-03T13:16:48.333+0000",
        "modified_author": "king@test.com",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 12,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_issue_board": {
            "name": "My topic board",
            "id": "c0784b27-5057-43f6-bdb3-3607f4da86b0"
        },
        "bimsync_creation_author": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King Kong"
            },
            "importedBy": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
    },
    {
        "guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73",
        "topic_type": "Error",
        "topic_status": "Open",
        "reference_links": [],
        "title": "title",
        "index": 2,
        "labels": [
            "Arkitekt3"
        ],
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "creation_author": "king@test.com",
        "modified_date": "2020-03-03T08:06:39.264+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 11,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_issue_board": {
            "name": "My topic board",
            "id": "c0784b27-5057-43f6-bdb3-3607f4da86b0"
        },
        "bimsync_creation_author": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King Kong"
            },
            "importedBy": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:23.158+0000"
    }
]

Filter, sort, skip and limit using OData

Odata filter parameters

ParameterTypeDescription
creation_authorstringuserId of the creation author (value from extensions)
modified_authorstringuserId of the modified author (value from extensions)
assigned_tostringuserId of the assigned person (value from extensions)
stagestringstage this topic is part of (value from extensions)
topic_statusstringstatus of a topic (value from extensions)
topic_typestringtype of a topic (value from extensions)
creation_datedatetimecreation date of a topic
modified_datedatetimemodification date of a topic
labelsarray (string)labels of a topic (value from extensions)

OData sort parameters

parameterdescription
creation_datecreation date of a topic
modified_datemodification date of a topic
indexindex of a topic

Odata example requests

Get topics that are open, assigned to Architect@example.com and created after December 5th 2015. Sort the result on last modified.

GET https://api.catenda.com/opencde/bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=assigned_to eq 'Architect@example.com' and status eq 'Open' and creation_date gt 2015-12-05T00:00:00+01:00&$orderby=modified_date desc

Get topics that have at least one of the labels 'Architecture', 'Structural' or 'Heating'.

GET https://api.catenda.com/opencde/bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$filter=contains(labels, 'Architecture') or contains(labels, 'Structural') or contains(labels, 'Heating')

Get 50 topics and skip the first 100.

GET https://api.catenda.com/opencde/bcf/2.1/projects/F445F4F2-4D02-4B2A-B612-5E456BEF9137/topics?$top=50&$skip=100

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics

Select

Example request with select

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics?$select=creation_date,modified_date,assigned_to

Example response with select

[
    {
        "guid": "44405b7c-7bc1-4ea7-813b-e0ef156eb6db",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-06T12:31:58.018+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 12,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:46.986+0000"
    },
    {
        "guid": "c720fd87-75ad-4ba6-ac26-9296b4f6ff73",
        "creation_date": "2020-03-03T08:06:39.264+0000",
        "modified_date": "2020-03-03T08:06:39.264+0000",
        "assigned_to": "king@test.com",
        "bimsync_issue_number": 11,
        "bimsync_assigned_to": {
            "user": {
                "ref": "e4d94d45f7194f1f9f7b29ed994d01e4",
                "email": "king@test.com",
                "name": "King"
            },
            "team": null
        },
        "bimsync_imported_at": "2020-03-03T11:10:23.158+0000"
    }
]

Use $select as a query parameter to choose which properties to include in the response. guid and bimsync_issue_number are always returned in addition.

ParameterReturns
*all default fields
titletitle
descriptiondescription
indexindex
labelslabels
due_datedue_date
stagestage
creation_authorcreation_author, bimsync_creation_author
creation_datecreation_date, bimsync_imported_at
modified_datemodified_date
modified_authormodified_author
assigned_to, bimsync_assigned_toassigned_to, bimsync_assigned_to
topic_statustopic_status
topic_typetopic_type
topic_prioritytopic_priority
reference_linksreference_links
bim_snippetbim_snippet
bimsync_comments_sizebimsync_comments_size
bimsync_requesterbimsync_requester

Response schema

List of topic_GET.json

Topic extensions

Get objects

Example

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/objects
[
    {
        "ifcGuid": "3BY5alwwL00QXHtY2qmHYZ"
    },
    {
        "ifcGuid": "0w1FD2e5L4LOvXHSZSTtLq"
    },
    {
        "ifcGuid": "0Arc0R2mf2Ow2ddxcQ40yG"
    }
]

Return a list of objects linked to a topic. Each object has 1 attribute. ifcGuid.

ifcGuid the ifcGuid of the object

Note: this resource is additional to the BCF-API standard, and may change in the future

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/objects

Create objects

Example

POST https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/objects
{
    "ifcGuids": ["3BY5alwwL00QXHtY2qmHYZ", "0w1FD2e5L4LOvXHSZSTtLq", "0Arc0R2mf2Ow2ddxcQ40yG"]
}
[
    {
        "ifcGuid": "3BY5alwwL00QXHtY2qmHYZ"
    },
    {
        "ifcGuid": "0w1FD2e5L4LOvXHSZSTtLq"
    },
    {
        "ifcGuid": "0Arc0R2mf2Ow2ddxcQ40yG"
    }
]

Links objects to a topic. Already linked objects will be ignored

Note: this resource is additional to the BCF-API standard, and may change in the future

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/objects

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
ifcGuids List of strings Each element is the "ifcGuid" of the object to link to the topic Required

Delete objects

Example

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/objects
{
    "ifcGuids": ["3BY5alwwL00QXHtY2qmHYZ", "0w1FD2e5L4LOvXHSZSTtLq", "0Arc0R2mf2Ow2ddxcQ40yG"]
}

Unlinks objects to from topic.

Note: this resource is additional to the BCF-API standard, and may change in the future

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/objects

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
ifcGuids List of strings Each element is the "ifcGuid" of the object to unlink from the topic Required

Get points

Example

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/points
[
    {
        "id": "7c34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 0,
        "y": 0,
        "z": 0
    },
    {
        "id": "2a34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 10.2,
        "y": -4.2,
        "z": -20.5
    }
]

Return a list of points in a topic. Each point has 4 attribute. id, x, y and z.

id the id of the point. x the x axis. y the y axis. z the z axis.

Note: this resource is additional to the BCF-API standard, and may change in the future

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/points

Create points

Example

POST https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/points
[
    {
        "x": 0,
        "y": 0,
        "z": 0
    },
    {
        "x": 10.2,
        "y": -4.2,
        "z": -20.5
    }
]
[
    {
        "id": "7c34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 0,
        "y": 0,
        "z": 0
    },
    {
        "id": "2a34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 10.2,
        "y": -4.2,
        "z": -20.5
    }
]

Creates points in a topic.

Note: this resource is additional to the BCF-API standard, and may change in the future

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/points

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
x number The x axis Required
y number The y axis Required
z number The z axis Required

Update points

Example

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/points
[
    {
        "id": "7c34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 0,
        "y": 0,
        "z": 0
    },
    {
        "id": "2a34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 10.2,
        "y": -4.2,
        "z": -20.5
    }
]

[
    {
        "id": "7c34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 0,
        "y": 0,
        "z": 0
    },
    {
        "id": "2a34c9b3-1b9b-4750-a4f3-0641d58fe48e",
        "x": 10.2,
        "y": -4.2,
        "z": -20.5
    }
]

Updates points in a topic.

Note: this resource is additional to the BCF-API standard, and may change in the future

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/points

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
id string The id of the point Required
x number The x axis Required
y number The y axis Required
z number The z axis Required

Delete points

Example

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/points
[
    {
        "id": "7c34c9b3-1b9b-4750-a4f3-0641d58fe48e"
    }
]

Deletes points in a topic.

Note: this resource is additional to the BCF-API standard, and may change in the future

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/points

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescription
id string The id of the point Required

Topic Event

Get all topic events

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/events

Example response

[
    {
        "topic_guid": "243a69aa-ef85-4b4e-9b56-d172818a9a37",
        "date": "2020-02-27T13:41:45.442+0000",
        "author": "user1@test.com",
        "actions": [
            {
                "type": "topic_created"
            },
            {
                "type": "title_updated",
                "value": "Hole in the wall"
            },
            {
                "type": "status_updated",
                "value": "Open"
            },
            {
                "type": "type_updated",
                "value": "Error"
            },
            {
                "type": "priority_removed"
            }
        ]
    },
    {
        "topic_guid": "243a69aa-ef85-4b4e-9b56-d172818a9a37",
        "date": "2020-02-27T13:42:01.939+0000",
        "author": "user1@test.com",
        "actions": [
            {
                "type": "type_updated",
                "value": "Info"
            }
        ]
    },
    {
        "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
        "date": "2020-02-21T14:59:48.828+0000",
        "author": "user1@test.com",
        "actions": [
            {
                "type": "topic_created"
            },
            {
                "type": "title_updated",
                "value": "new title"
            },
            {
                "type": "status_updated",
                "value": "Open"
            },
            {
                "type": "type_updated",
                "value": "Error"
            },
            {
                "type": "priority_removed"
            }
        ]
    }
]

Return all events for all topics for a given project.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/events

Response schema

List of topic_event_GET.json

Get topic events

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/events

Example response

[
    {
        "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
        "date": "2020-02-21T14:59:48.828+0000",
        "author": "user1@test.com",
        "actions": [
            {
                "type": "topic_created"
            },
            {
                "type": "title_updated",
                "value": "my changed title"
            },
            {
                "type": "status_updated",
                "value": "Open"
            },
            {
                "type": "type_updated",
                "value": "Error"
            },
            {
                "type": "priority_removed"
            }
        ]
    }
]

Return all events for the given topic.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/events

Response schema

topic_event_GET.json

Comment

Get comments

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/comments?includeAuthorization=true

Example response

[
    {
        "guid": "587bd028-33a1-4b7e-b450-3f39e42e86c5",
        "date": "2020-02-27T14:42:08.390+0000",
        "author": "king@test.com",
        "comment": "A comment!",
        "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
        "modified_date": "2020-02-27T14:42:14.760+0000",
        "modified_author": "king@test.com",
        "authorization": {
            "comment_actions": [
                "update"
            ]
        }
    },
    {
        "guid": "8609f137-c481-47af-819a-d139bb891265",
        "date": "2020-02-27T14:43:41.010+0000",
        "author": "king@test.com",
        "comment": "This is an edited comment",
        "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
        "modified_date": "2020-02-27T14:48:05.417+0000",
        "modified_author": "king@test.com",
        "authorization": {
            "comment_actions": [
                "update"
            ]
        }
    },
    {
        "guid": "ae2c9958-76d9-42e5-b400-547d0e735134",
        "date": "2020-02-27T14:44:03.152+0000",
        "author": "pawn@test.com",
        "comment": "There's a comment",
        "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
        "authorization": {
            "comment_actions": []
        }
    },
    {
        "guid": "e79ab6dd-6fd7-487c-87c0-9e3ca5b0cde2",
        "date": "2020-02-27T14:47:36.365+0000",
        "author": "king@test.com",
        "comment": "Hey",
        "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
        "viewpoint_guid": "c771d62e-0937-4164-b064-8c3b925ef70b",
        "authorization": {
            "comment_actions": [
                "update"
            ]
        }
    }
]

Return all comments for a given topic.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/comments

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
includeAuthorization boolean whether to return the authorization object Mandatory

Response schema

List of comment_GET.json

Get comment

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/comments/d13fd9fa-2f54-4bbd-b37d-15a975077cd3?includeAuthorization=true

Example response

{
    "guid": "d13fd9fa-2f54-4bbd-b37d-15a975077cd3",
    "date": "2017-06-02T09:57:44.438+0000",
    "author": "user2@test.com",
    "comment": "Check this",
    "topic_guid": "6411ce04-5391-40a6-97c2-be0ca45fcc96",
    "viewpoint_guid": "9d3b9d8e-68a8-4f15-bf1e-37fb6bbaf0d5",
    "reply_to_comment_guid": "e93582cc-fb27-4472-8d90-9db9a7a66780",
    "modified_date": "2018-03-14T15:45:34.448+0000",
    "modified_author": "user3@test2.com",
    "authorization": [
        "update"
    ]
}

Return the comment.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/comments/{comment_guid}

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
includeAuthorization boolean whether to return the authorization object Optional

Response schema

comment_GET.json

Create comment

Example request

POST https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/comments
{
    "comment": "will rework the heating model",
    "viewpoint_guid": "c771d62e-0937-4164-b064-8c3b925ef70b"
}

Example response

{
    "guid": "970e02db-75a8-4b95-a852-0d9ef583ef55",
    "date": "2020-02-28T09:33:27.299+0000",
    "author": "king@test.com",
    "comment": "will rework the heating model",
    "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
    "viewpoint_guid": "c771d62e-0937-4164-b064-8c3b925ef70b"
}

Create the comment.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/comments

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
comment string the comment Mandatory
viewpoint_guid string guid of an existing viewpoint Optional

Request schema

comment_POST.json

Response schema

comment_GET.json

Update comment

Example request

PUT https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/comments/587bd028-33a1-4b7e-b450-3f39e42e86c5
{
    {
        "comment": "updated the comment",
        "viewpoint_guid": ""
    }
}

Example response

{
    "guid": "587bd028-33a1-4b7e-b450-3f39e42e86c5",
    "date": "2020-02-27T14:42:08.390+0000",
    "author": "king@test.com",
    "comment": "updated the comment",
    "topic_guid": "c84392ec-065f-4c89-aa2b-644486ca8e34",
    "modified_date": "2020-02-28T09:38:16.750+0000",
    "modified_author": "king@test.com"
}

Edit the comment.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/comments

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
comment string the comment Mandatory
viewpoint_guid string guid of an existing viewpoint Optional

Request schema

comment_POST.json

Response schema

comment_GET.json

Delete comment

Example request

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/ea7ca636-77e9-4e89-9188-aa5fe7f53036/comments/d13fd9fa-2f54-4bbd-b37d-15a975077cd3

Delete the comment. Does not return the comment.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/comments/{comment_guid}

Document

Get documents

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/documents

Example response

[
    {
        "guid": "a3aaaee9-f14a-432e-a008-2feec907c2ba",
        "filename": "Myfile.txt"
    },
    {
        "guid": "d7b580eb-4f96-401a-b44b-1f0a495222a7",
        "filename": "Myfile.ifx"
    }
]

Return the documents.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/documents

Response schema

List of document_GET.json

Get document

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/documents/a3aaaee9-f14a-432e-a008-2feec907c2ba

Return the document file.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/documents/{document_guid}

Upload document

Example request

POST https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/documents
–header ‘Content-Disposition: attachment; filename="Myfile.xlxs"’


The document to upload    

Example response

{
    "guid": "cfd79b46-a394-48a9-ba45-75fe3719e173",
    "filename": "Myfile.xlsx"
}

Upload the document.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/documents

Request body

The document to be uploaded.

Response schema

document_GET.json

Document reference

Get document references

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/document_references

Example response

[
    {
        "guid": "31f76de2-ee4d-4faf-bd84-53a20a34084d",
        "url": "https://hub.catenda.com",
        "description": "Best BIM platform"
    },
    {
        "guid": "5bb373ef-bdd1-4f0f-b3fc-58d91fe4e7ce",
        "document_guid": "a96a7491-82a4-4404-b1bd-4ba20b6d8692",
        "description": "myfile.txt"
    }
]

Return all document references for the specified topic. The document_guid from the response points to the guid of the document.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/document_references

Response schema

List of document_reference_GET.json

Create document reference

Example request

POST https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/document_references
{
    "description": "new document reference",
    "document_guid": "ced73ed4-bd45-4eec-9779-9c3c619169c8"
}

Example response

{
    "guid": "45bb34da-8d03-41f6-a1fb-c707841a038f",
    "document_guid": "ced73ed4-bd45-4eec-9779-9c3c619169c8",
    "description": "new document reference"
}

Create the document reference between a topic and a document or url. Use either document_guid or url, not both.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/document_references

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
document_guid string guid of the existing document Optional
url string the referenced url Optional
description string description the reference to create Optional

Request schema

document_reference_POST.json

Response schema

document_reference_GET.json

Delete document reference

Example request

DELETE https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/document_references/31f76de2-ee4d-4faf-bd84-53a20a34084d

Delete the document reference. Does not return the deleted document reference.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/document_references/{document_reference_guid}

Update document reference

Example request

PUT https://api.catenda.com/opencde/bcf/2.1/projects/5af9e867-659d-4eee-ae56-2370aaf8aabe/topics/c84392ec-065f-4c89-aa2b-644486ca8e34/document_references/31f76de2-ee4d-4faf-bd84-53a20a34084d
{
    "description": "Updated document reference",
    "document_guid": "1ff36294-1480-48f2-a3c4-a35be645d7ed"
}

Example response

{
    "guid": "31f76de2-ee4d-4faf-bd84-53a20a34084d",
    "document_guid": "1ff36294-1480-48f2-a3c4-a35be645d7ed",
    "description": "Updated document reference"
}

Edit a document reference. Use either document_guid or url, not both.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/document_references/{document_reference_guid}

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
document_guid string guid of the existing document Optional
url string the referenced url Optional
description string description the reference to create Optional

Request schema

document_reference_PUT.json

Response schema

document_reference_GET.json

Viewpoint

Get viewpoints

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints

Example response

[
    {
        "guid": "82d00ffb-22aa-48b1-924f-dc59c487d585",
        "lines": [],
        "clipping_planes": [],
        "bitmaps": [],
        "snapshot": {
            "snapshot_type": "png"
        }
    },
    {
        "index": 2,
        "guid": "25777de1-b354-4432-88a9-fd45f0e4aea7",
        "perspective_camera": {
            "camera_view_point": {
                "x": -1.3757544290857453,
                "y": -14.084548687547457,
                "z": 15.77535220227417
            },
            "camera_direction": {
                "x": 0.48836276817323054,
                "y": 0.6442499485024906,
                "z": -0.5885947761547989
            },
            "camera_up_vector": {
                "x": 0.3555637551166773,
                "y": 0.4690610051624899,
                "z": 0.808428221602439
            },
            "field_of_view": 60.0
        },
        "lines": [],
        "clipping_planes": [],
        "bitmaps": [
            {
                "guid": "3a720dc7-2b3e-418c-82b4-42c129105ecc",
                "location": {
                    "x": 21.97304764097038,
                    "y": -24.86912390497038,
                    "z": 19.66912390497035
                },
                "normal": {
                    "x": -0.5773502691896258,
                    "y": 0.5773502691896258,
                    "z": -0.5773502691896258
                },
                "up": {
                    "x": -0.4082482904638631,
                    "y": 0.4082482904638631,
                    "z": 0.8164965809277261
                },
                "height": -1.0
            }
        ],
        "snapshot": {}
    }
]

Return the viewpoints.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints

Response schema

List of viewpoint_GET.json

Get viewpoint

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints/63fc95fa-0dcc-4e5b-b889-72db4a467113

Example response

{
    "index": 2,
    "guid": "63fc95fa-0dcc-4e5b-b889-72db4a467113",
    "perspective_camera": {
        "camera_view_point": {
            "x": -1.3757544290857453,
            "y": -14.084548687547457,
            "z": 15.77535220227417
        },
        "camera_direction": {
            "x": 0.48836276817323054,
            "y": 0.6442499485024906,
            "z": -0.5885947761547989
        },
        "camera_up_vector": {
            "x": 0.3555637551166773,
            "y": 0.4690610051624899,
            "z": 0.808428221602439
        },
        "field_of_view": 60.0
    },
    "lines": [],
    "clipping_planes": [],
    "bitmaps": [],
    "snapshot": {}
}

Return the viewpoint.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints/{viewpoint_guid}

Response schema

viewpoint_GET.json

Create viewpoint

Example request

POST https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints
{
    "index": 2,
    "components": {
        "selection": [{
            "ifc_guid": "3BY5alwwL00QXHtY2qmHYZ",
            "authoring_tool_id": "postman2"
        }],
        "coloring": [{
            "color": "#dddddd",
            "components": [{
                "ifc_guid": "3BY5alwwL00QXHtY2qmHYZ"
            }]
        }],
        "visibility": {
            "default_visibility": true,
            "exceptions": [{
                "ifc_guid": "0pQa7h_GLBZfPdI0XNo8Ru",
                "authoring_tool_id": "postman1"
            }],
            "view_setup_hints": {
                "spaces_visible": true,
                "space_boundaries_visible": true,
                "openings_visible": true
            }
        }
    },
    "perspective_camera": {
        "camera_view_point": {
            "x": -1.3757544290857453,
            "y": -14.084548687547457,
            "z": 15.77535220227417
        },
        "camera_direction": {
            "x": 0.48836276817323054,
            "y": 0.6442499485024906,
            "z": -0.5885947761547989
        },
        "camera_up_vector": {
            "x": 0.3555637551166773,
            "y": 0.4690610051624899,
            "z": 0.808428221602439
        },
        "field_of_view": 60.0
    },
    "lines": [],
    "clipping_planes": [],
    "bitmaps": [{
        "location": {
                "x": 21.97304764097038,
                "y": -24.86912390497038,
                "z": 19.66912390497035
        },
        "normal": {
            "x": -0.5773502691896258,
            "y": 0.5773502691896258,
            "z": -0.5773502691896258
        },
        "up": {
            "x": -0.4082482904638631,
            "y": 0.4082482904638631,
            "z": 0.8164965809277261
        },
        "bitmap_data": "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"
    }],
    "snapshot": {
        "snapshot_data": "R0lGODlhPQBEAPeoAJosM//AwO/AwHVYZ/z595kzAP/s7P+goOXMv8+fhw/v739/f+8PD98fH/8mJl+fn/9ZWb8/PzWlwv///6wWGbImAPgTEMImIN9gUFCEm/gDALULDN8PAD6atYdCTX9gUNKlj8wZAKUsAOzZz+UMAOsJAP/Z2ccMDA8PD/95eX5NWvsJCOVNQPtfX/8zM8+QePLl38MGBr8JCP+zs9myn/8GBqwpAP/GxgwJCPny78lzYLgjAJ8vAP9fX/+MjMUcAN8zM/9wcM8ZGcATEL+QePdZWf/29uc/P9cmJu9MTDImIN+/r7+/vz8/P8VNQGNugV8AAF9fX8swMNgTAFlDOICAgPNSUnNWSMQ5MBAQEJE3QPIGAM9AQMqGcG9vb6MhJsEdGM8vLx8fH98AANIWAMuQeL8fABkTEPPQ0OM5OSYdGFl5jo+Pj/+pqcsTE78wMFNGQLYmID4dGPvd3UBAQJmTkP+8vH9QUK+vr8ZWSHpzcJMmILdwcLOGcHRQUHxwcK9PT9DQ0O/v70w5MLypoG8wKOuwsP/g4P/Q0IcwKEswKMl8aJ9fX2xjdOtGRs/Pz+Dg4GImIP8gIH0sKEAwKKmTiKZ8aB/f39Wsl+LFt8dgUE9PT5x5aHBwcP+AgP+WltdgYMyZfyywz78AAAAAAAD///8AAP9mZv///wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH5BAEAAKgALAAAAAA9AEQAAAj/AFEJHEiwoMGDCBMqXMiwocAbBww4nEhxoYkUpzJGrMixogkfGUNqlNixJEIDB0SqHGmyJSojM1bKZOmyop0gM3Oe2liTISKMOoPy7GnwY9CjIYcSRYm0aVKSLmE6nfq05QycVLPuhDrxBlCtYJUqNAq2bNWEBj6ZXRuyxZyDRtqwnXvkhACDV+euTeJm1Ki7A73qNWtFiF+/gA95Gly2CJLDhwEHMOUAAuOpLYDEgBxZ4GRTlC1fDnpkM+fOqD6DDj1aZpITp0dtGCDhr+fVuCu3zlg49ijaokTZTo27uG7Gjn2P+hI8+PDPERoUB318bWbfAJ5sUNFcuGRTYUqV/3ogfXp1rWlMc6awJjiAAd2fm4ogXjz56aypOoIde4OE5u/F9x199dlXnnGiHZWEYbGpsAEA3QXYnHwEFliKAgswgJ8LPeiUXGwedCAKABACCN+EA1pYIIYaFlcDhytd51sGAJbo3onOpajiihlO92KHGaUXGwWjUBChjSPiWJuOO/LYIm4v1tXfE6J4gCSJEZ7YgRYUNrkji9P55sF/ogxw5ZkSqIDaZBV6aSGYq/lGZplndkckZ98xoICbTcIJGQAZcNmdmUc210hs35nCyJ58fgmIKX5RQGOZowxaZwYA+JaoKQwswGijBV4C6SiTUmpphMspJx9unX4KaimjDv9aaXOEBteBqmuuxgEHoLX6Kqx+yXqqBANsgCtit4FWQAEkrNbpq7HSOmtwag5w57GrmlJBASEU18ADjUYb3ADTinIttsgSB1oJFfA63bduimuqKB1keqwUhoCSK374wbujvOSu4QG6UvxBRydcpKsav++Ca6G8A6Pr1x2kVMyHwsVxUALDq/krnrhPSOzXG1lUTIoffqGR7Goi2MAxbv6O2kEG56I7CSlRsEFKFVyovDJoIRTg7sugNRDGqCJzJgcKE0ywc0ELm6KBCCJo8DIPFeCWNGcyqNFE06ToAfV0HBRgxsvLThHn1oddQMrXj5DyAQgjEHSAJMWZwS3HPxT/QMbabI/iBCliMLEJKX2EEkomBAUCxRi42VDADxyTYDVogV+wSChqmKxEKCDAYFDFj4OmwbY7bDGdBhtrnTQYOigeChUmc1K3QTnAUfEgGFgAWt88hKA6aCRIXhxnQ1yg3BCayK44EWdkUQcBByEQChFXfCB776aQsG0BIlQgQgE8qO26X1h8cEUep8ngRBnOy74E9QgRgEAC8SvOfQkh7FDBDmS43PmGoIiKUUEGkMEC/PJHgxw0xH74yx/3XnaYRJgMB8obxQW6kL9QYEJ0FIFgByfIL7/IQAlvQwEpnAC7DtLNJCKUoO/w45c44GwCXiAFB/OXAATQryUxdN4LfFiwgjCNYg+kYMIEFkCKDs6PKAIJouyGWMS1FSKJOMRB/BoIxYJIUXFUxNwoIkEKPAgCBZSQHQ1A2EWDfDEUVLyADj5AChSIQW6gu10bE/JG2VnCZGfo4R4d0sdQoBAHhPjhIB94v/wRoRKQWGRHgrhGSQJxCS+0pCZbEhAAOw=="
    }
}

Example response

{
    "index": 2,
    "guid": "fb7354fc-3ddf-4bb6-92d0-30ede4ee1718",
    "perspective_camera": {
        "camera_view_point": {
            "x": -1.3757544290857453,
            "y": -14.084548687547457,
            "z": 15.77535220227417
        },
        "camera_direction": {
            "x": 0.48836276817323054,
            "y": 0.6442499485024906,
            "z": -0.5885947761547989
        },
        "camera_up_vector": {
            "x": 0.3555637551166773,
            "y": 0.4690610051624899,
            "z": 0.808428221602439
        },
        "field_of_view": 60.0
    },
    "lines": [],
    "clipping_planes": [],
    "bitmaps": [
        {
            "guid": "1d819f39-4ee4-4b6d-96e3-de2078df10b3",
            "location": {
                "x": 21.97304764097038,
                "y": -24.86912390497038,
                "z": 19.66912390497035
            },
            "normal": {
                "x": -0.5773502691896258,
                "y": 0.5773502691896258,
                "z": -0.5773502691896258
            },
            "up": {
                "x": -0.4082482904638631,
                "y": 0.4082482904638631,
                "z": 0.8164965809277261
            },
            "height": -1.0
        }
    ],
    "snapshot": {}
}

Create the viewpoint.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
index integer parameter for sorting Optional
orthogonal camera Orthogonal camera orthogonal camera view Optional
perspective camera Perspective camera perspective view of the camera Optional
lines array of Line graphical line Optional
clipping_planes array of Clipping Plane clipping planes for the model view Optional
bitmaps array of Bitmap embedded pictures in the viewpoint Optional
snapshot Snapshot snapshot image of the viewpoint Optional
components Components Components in the viewpoint Optional

Point

NameTypeDescriptionRequired
x number x point Mandatory
y number y point Mandatory
z number z point Mandatory

Direction

NameTypeDescriptionRequired
x number x direction Mandatory
y number y direction Mandatory
z number z direction Mandatory

Orthogonal camera

NameTypeDescriptionRequired
camera_view_point Direction viewpoint of the camera Mandatory
camera_direction Direction direction of the camera Mandatory
camera_up_vector Direction direction of camera up Mandatory
view_to_world_scale number proportion of camera view to model Mandatory

Perspective camera

NameTypeDescriptionRequired
camera_view_point Point viewpoint of the camera Mandatory
camera_direction Direction direction of the camera Mandatory
camera_up_vector Direction direction of camera up Mandatory
field_of_view number field of view Mandatory

Line

NameTypeDescriptionRequired
start_point Point start point of the line Mandatory
end_point Point end point of the line (Treated as point if start_point and end_point is the same) Mandatory

Clipping plane

NameTypeDescriptionRequired
location Point origin of the clipping plane Mandatory
direction Direction direction of the clipping plane Mandatory

Bitmap

NameTypeDescriptionRequired
bitmap_type enum (string) format of the bitmap. Predefined values png or jpg Mandatory
bitmap_data base64 encoded string The bitmap image data Mandatory
location Point location of the center of the bitmap in world coordinates (point) Mandatory
normal Direction normal vector of the bitmap (vector) Mandatory
up Direction up vector of the bitmap (vector) Mandatory
height number height of bitmap in the scene Mandatory

Snapshot

NameTypeDescriptionRequired
snapshot_type enum (string) format of the snapshot. Predefined values png or jpg Mandatory
snapshot_data base64 encoded string The snapshot image data Mandatory

Components

NameTypeDescriptionRequired
selection array of Component Selected components Optional
coloring array of Coloring Colored components Optional
visibility Visibility Visibility of components Mandatory

Component

NameTypeDescriptionRequired
ifc_guid string IFC guid of the component Optional
originating_system string originating system of the component Optional
authoring_tool_id string internal id for the authoring tool of the component Optional

Coloring

NameTypeDescriptionRequired
color string Color of the components Mandatory
components array of Component Colored components Mandatory
The color is given in ARGB format. Colors are represented as 6 or 8 hexadecimal digits. If 8 digits are present, the first two represent the alpha (transparency) channel. For example, 40E0D0 would be the color Turquoise.

Visibility

NameTypeDescriptionRequired
default_visibility boolean If true: Show all components, and hide the exceptions. If false: Hide all components and show exceptions Optional, default false
exceptions array of Component Components to hide/show determined by default_visibility Optional
view_setup_hints View setup hints Hints about the setup of the viewer Optional

View setup hints

NameTypeDescriptionRequired
spaces_visible boolean If true: Show all components, and hide the exceptions. If false: Hide all components and show exceptions Optional, default false
space_boundaries_visible boolean Visibility of space_boundaries Optional, default false
openings_visible boolean Hints about the setup of the viewer Optional

Request schema

viewpoint_POST.json

Response schema

viewpoint_GET.json

Get snapshot

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints/747f2fe6-b690-471f-8e45-618a4bc9a63c/snapshot

Return the binary snapshot file.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints/{viewpoint_guid}/snapshot

Get selection

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints/747f2fe6-b690-471f-8e45-618a4bc9a63c/selection

Example response

{
    "selection": [
        {
            "ifc_guid": "3BY5alwwL00QXHtY2qmHYZ",
            "authoring_tool_id": "postman2"
        }
    ]
}

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints/{viewpoint_guid}/selection

Response schema

selection_GET.json

Get coloring

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints/747f2fe6-b690-471f-8e45-618a4bc9a63c/coloring

Example response

{
    "coloring": [
        {
            "color": "#dddddd",
            "components": [
                {
                    "ifc_guid": "1UzL$dBE97XRfnA7PumPU0"
                },
                {
                    "ifc_guid": "3YrfmETbIM30URCkluiGNV"
                }
            ]
        }
    ]
}

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints/{viewpoint_guid}/coloring

Response schema

coloring_GET.json

Get visibility

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints/747f2fe6-b690-471f-8e45-618a4bc9a63c/visibility

Example response

{
    "visibility": {
        "default_visibility": true,
        "exceptions": [
            {
                "ifc_guid": "0pQa7h_GLBZfPdI0XNo8Ru",
                "authoring_tool_id": "postman1"
            }
        ],
        "view_setup_hints": {
            "spaces_visible": true,
            "space_boundaries_visible": true,
            "openings_visible": true
        }
    }
}

Return the snapshot file.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints/{viewpoint_guid}/visibility

Response schema

visibility_GET.json

Viewpoint extensions

Get viewpoint models

Example request

GET https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints/63fc95fa-0dcc-4e5b-b889-72db4a467113/models

Example response

[
    {
        "modelRef": "3a8a62f0226b4a1da994481730de6adf",
        "revisionRef": "a21ed391-f9e0-46a2-bb2b-c879c48f1d48"
    },
    {
        "modelRef": "b8beba1a10fb44c8a67fefb2d182f3e4",
        "revisionRef": "4e8e119a-dbdf-4ce7-bf54-6de38cd171f9"
    }
]

Return the viewpoint models.

The initial value is calculated when the viewpoint is created.

Each element has 2 attributes. modelRef and revisionRef. modelRef A reference to the model. revisionRef A reference to the model revision.

Note: this resource is additional to the BCF-API standard

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints/{viewpoint_guid}/models

Update viewpoint models

Example request

PUT https://api.catenda.com/opencde/bcf/2.1/projects/3c34c9b3-1b9b-4750-a4f3-0641d58fe48e/topics/6411ce04-5391-40a6-97c2-be0ca45fcc96/viewpoints/63fc95fa-0dcc-4e5b-b889-72db4a467113/models
[
    {
        "modelRef": "3a8a62f0226b4a1da994481730de6adf"
    },
    {
        "modelRef": "b8beba1a10fb44c8a67fefb2d182f3e4",
        "revisionRef": "4e8e119a-dbdf-4ce7-bf54-6de38cd171f9"
    }
]

Example response

[
    {
        "modelRef": "3a8a62f0226b4a1da994481730de6adf",
        "revisionRef": "a21ed391-f9e0-46a2-bb2b-c879c48f1d48"
    },
    {
        "modelRef": "b8beba1a10fb44c8a67fefb2d182f3e4",
        "revisionRef": "4e8e119a-dbdf-4ce7-bf54-6de38cd171f9"
    }
]

Update the viewpoint models.

The models in the request must exist in the same Catenda project. If revisionRef is omitted, the model must have at least one revision.

Resource URL

https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/topics/{topic_guid}/viewpoints/{viewpoint_guid}/models

Parameters

JSON encoded body using the "application/json" content type.

NameTypeDescriptionRequired
modelRef string the model reference Mandatory
revisionRef string the reference to the model revision Optional, default the last revision of the model