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
- All supported API-methods, with some extensions
- bimsync terms
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
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
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
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
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | Required |
---|---|---|---|
name | string | new name of the topic board | Mandatory |
Request schema
Response schema
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
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
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
name | string | name of the status | Mandatory |
Resource URL
https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/statuses
Link topic board extension status
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.
Name | Type | Description | |
---|---|---|---|
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
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
name | string | name of the type | Mandatory |
Resource URL
https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/types
Link topic board extension type
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.
Name | Type | Description | |
---|---|---|---|
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
Name | Type | Description | |
---|---|---|---|
include-unlinked | boolean | Should include unlinked users | Optional |
Resource URL
https://api.catenda.com/opencde/bcf/{version_id}/projects/{project_id}/extensions/users
Link topic board extension user
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.
Name | Type | Description | |
---|---|---|---|
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
Parameter | Type | Description | |
---|---|---|---|
creation_author | string | userId of the creation author (value from extensions) | |
modified_author | string | userId of the modified author (value from extensions) | |
assigned_to | string | userId of the assigned person (value from extensions) | |
stage | string | stage this topic is part of (value from extensions) | |
topic_status | string | status of a topic (value from extensions) | |
topic_type | string | type of a topic (value from extensions) | |
creation_date | datetime | creation date of a topic | |
modified_date | datetime | modification date of a topic | |
labels | array (string) | labels of a topic (value from extensions) |
OData sort parameters
parameter | description |
---|---|
creation_date | creation date of a topic |
modified_date | modification date of a topic |
index | index 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.
Parameter | Returns |
---|---|
* | all default fields |
title | title |
description | description |
index | index |
labels | labels |
due_date | due_date |
stage | stage |
creation_author | creation_author, bimsync_creation_author |
creation_date | creation_date, bimsync_imported_at |
modified_date | modified_date |
modified_author | modified_author |
assigned_to, bimsync_assigned_to | assigned_to, bimsync_assigned_to |
topic_status | topic_status |
topic_type | topic_type |
topic_priority | topic_priority |
reference_links | reference_links |
bim_snippet | bim_snippet |
bimsync_comments_size | bimsync_comments_size |
bimsync_requester | bimsync_requester |
bimsync_points | bimsync_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.
Name | Type | Description | Required |
---|---|---|---|
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.
Parameter | Returns |
---|---|
* | all default fields |
title | title |
description | description |
index | index |
labels | labels |
due_date | due_date |
stage | stage |
creation_author | creation_author, bimsync_creation_author |
creation_date | creation_date, bimsync_imported_at |
modified_date | modified_date |
modified_author | modified_author |
assigned_to, bimsync_assigned_to | assigned_to, bimsync_assigned_to |
topic_status | topic_status |
topic_type | topic_type |
topic_priority | topic_priority |
reference_links | reference_links |
bim_snippet | bim_snippet |
bimsync_comments_size | bimsync_comments_size |
bimsync_requester | bimsync_requester |
bimsync_points | bimsync_points |
Response schema
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.
Name | Type | Description | Required |
---|---|---|---|
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.
Parameter | Returns |
---|---|
* | all default fields |
title | title |
description | description |
index | index |
labels | labels |
due_date | due_date |
stage | stage |
creation_author | creation_author, bimsync_creation_author |
creation_date | creation_date, bimsync_imported_at |
modified_date | modified_date |
modified_author | modified_author |
assigned_to, bimsync_assigned_to | assigned_to, bimsync_assigned_to |
topic_status | topic_status |
topic_type | topic_type |
topic_priority | topic_priority |
reference_links | reference_links |
bim_snippet | bim_snippet |
bimsync_comments_size | bimsync_comments_size |
bimsync_requester | bimsync_requester |
Request schema
Response schema
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.
Name | Type | Description | Required |
---|---|---|---|
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.
Parameter | Returns |
---|---|
* | all default fields |
title | title |
description | description |
index | index |
labels | labels |
due_date | due_date |
stage | stage |
creation_author | creation_author, bimsync_creation_author |
creation_date | creation_date, bimsync_imported_at |
modified_date | modified_date |
modified_author | modified_author |
assigned_to, bimsync_assigned_to | assigned_to, bimsync_assigned_to |
topic_status | topic_status |
topic_type | topic_type |
topic_priority | topic_priority |
reference_links | reference_links |
bim_snippet | bim_snippet |
bimsync_comments_size | bimsync_comments_size |
bimsync_requester | bimsync_requester |
Request schema
Response schema
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}
Get related topics
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.
Name | Type | Description | Required |
---|---|---|---|
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
Parameter | Type | Description | |
---|---|---|---|
creation_author | string | userId of the creation author (value from extensions) | |
modified_author | string | userId of the modified author (value from extensions) | |
assigned_to | string | userId of the assigned person (value from extensions) | |
stage | string | stage this topic is part of (value from extensions) | |
topic_status | string | status of a topic (value from extensions) | |
topic_type | string | type of a topic (value from extensions) | |
creation_date | datetime | creation date of a topic | |
modified_date | datetime | modification date of a topic | |
labels | array (string) | labels of a topic (value from extensions) |
OData sort parameters
parameter | description |
---|---|
creation_date | creation date of a topic |
modified_date | modification date of a topic |
index | index 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.
Parameter | Returns |
---|---|
* | all default fields |
title | title |
description | description |
index | index |
labels | labels |
due_date | due_date |
stage | stage |
creation_author | creation_author, bimsync_creation_author |
creation_date | creation_date, bimsync_imported_at |
modified_date | modified_date |
modified_author | modified_author |
assigned_to, bimsync_assigned_to | assigned_to, bimsync_assigned_to |
topic_status | topic_status |
topic_type | topic_type |
topic_priority | topic_priority |
reference_links | reference_links |
bim_snippet | bim_snippet |
bimsync_comments_size | bimsync_comments_size |
bimsync_requester | bimsync_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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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.
Name | Type | Description | |
---|---|---|---|
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
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.
Name | Type | Description | Required |
---|---|---|---|
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
Parameters
JSON encoded body using the "application/json" content type.
Name | Type | Description | Required |
---|---|---|---|
includeAuthorization | boolean | whether to return the authorization object | Optional |
Response schema
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.
Name | Type | Description | Required |
---|---|---|---|
comment | string | the comment | Mandatory |
viewpoint_guid | string | guid of an existing viewpoint | Optional |
Request schema
Response schema
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.
Name | Type | Description | Required |
---|---|---|---|
comment | string | the comment | Mandatory |
viewpoint_guid | string | guid of an existing viewpoint | Optional |
Request schema
Response schema
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 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.
Name | Type | Description | Required |
---|---|---|---|
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
Response schema
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.
Name | Type | Description | Required |
---|---|---|---|
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
Response schema
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
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": "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"
}
}
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.
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
x | number | x point | Mandatory |
y | number | y point | Mandatory |
z | number | z point | Mandatory |
Direction
Name | Type | Description | Required |
---|---|---|---|
x | number | x direction | Mandatory |
y | number | y direction | Mandatory |
z | number | z direction | Mandatory |
Orthogonal camera
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
location | Point | origin of the clipping plane | Mandatory |
direction | Direction | direction of the clipping plane | Mandatory |
Bitmap
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
selection | array of Component | Selected components | Optional |
coloring | array of Coloring | Colored components | Optional |
visibility | Visibility | Visibility of components | Mandatory |
Component
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
color | string | Color of the components | Mandatory |
components | array of Component | Colored components | Mandatory |
Visibility
Name | Type | Description | Required |
---|---|---|---|
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
Name | Type | Description | Required |
---|---|---|---|
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
Response schema
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
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
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
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.
- For viewpoints created from BCF-API or BCF file import, the models is a "best guess", based on components being marked as selected or visible.
- For viewpoints created inside arena, the models are the visible models at the time the viewpoint was 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.
Name | Type | Description | Required |
---|---|---|---|
modelRef | string | the model reference | Mandatory |
revisionRef | string | the reference to the model revision | Optional, default the last revision of the model |