Getting started with the Connection API

The Connection API lets your application read and manage issues in a BIMcollab space. This article explains the key concepts, shows how issue data is organized, and guides you through your first requests on the Playground.

💡 Tip: New to APIs? Read API and SDK basics for beginners first.

What is the Connection API?

The Connection API is part of the BIMcollab API. It is an extended version of the BCF-API, an open standard by buildingSMART for exchanging issue data between applications.

BIMcollab applications, such as BIMcollab Zoom and the BIMcollab BCF Managers, use the Connection API to exchange issues with BIMcollab. Your application can use it in the same way.

With the Connection API, your application can:

Read projects and issues.
Create and update issues.
Add comments and viewpoints to issues.
Read and write custom fields.
Retrieve activity logs and user access logs.

Common things people build with it:

Issue synchronization: keep issues aligned between BIMcollab and your own project management or ticketing system.
BIM tool plug-ins: let users create and open BIMcollab issues, with viewpoints, directly in your modeling or review application.
Automatic issue creation: turn the results of a model check, such as clashes or rule violations, into BIMcollab issues with a viewpoint for each problem.
Reporting/dashboards: show open issues per milestone, status, or custom field, and track progress over time with the activity logs.
Notifications: inform your team in your own tools when issues are created, assigned, or resolved.

📝 Note: You can also use the Connection API together with the BIMcollab SDK (Connector with full GUI). For example, use the SDK to show the issue interface in your Windows application, and the Connection API for tasks such as reporting or synchronization. See BIMcollab developers options overview for more details.

What is BCF?

BCF (BIM Collaboration Format) is an open standard for communicating about issues in BIM models. A BCF issue describes a problem and points to the exact location in the model: the camera position, the related components, and a snapshot.

BCF exists in two forms:

BCF files (.bcfzip): issues that you export and import as a file.
BCF-API: issues that applications exchange directly over the internet, without files.

The Connection API uses the second form. Changes are available right away to everyone who works on the project.

How issue data is organized

In the API, an issue is called a topic. Data is organized from top to bottom:

BIMcollab space
└── Project
    ├── Extensions (the allowed values for this project)
    └── Topic (an issue)
        ├── Comments
        └── Viewpoints (camera, components, snapshot)

API term	What it is
Project	A BIMcollab project. Every request for issue data starts with a project.
Extensions	The settings of a project: the allowed types, statuses, priorities, labels, milestones, users, and custom fields.
Topic	An issue.
Comment	A message on an issue. A comment can refer to a viewpoint.
Viewpoint	A saved view of the model: camera position, visible and selected components, clipping planes, and a snapshot.

⚠️ Attention: The BCF-API standard by buildingSMART also defines document services and event services. The Connection API doesn't support these services. Requests to them return empty data. For details and alternatives, see Connection API behavior compared to the BCF-API standard.

BIMcollab terms and API fields

Some fields have a different name in the API than in BIMcollab:

In BIMcollab	In the API
Issue	`topic`
Type	`topic_type`
Status	`topic_status`
Priority	`priority`
Labels	`labels`
Milestone	`stage`
Area	`area`
Assigned to	`assigned_to`
Deadline	`due_date`

Choose a version

Every request includes a version in the URL. BIMcollab supports two versions:

Version	What it is	When to use it
`bc_2.1`	The Connection API, with BIMcollab extensions such as custom fields and areas.	You want to use all BIMcollab data.
`2.1`	The generic BCF-API, without BIMcollab extensions.	Your application must also work with other BCF-API servers.

This article uses bc_2.1.

📝 Note: The log endpoints use a different version in the URL: 2.0.0 (/data_analysis/2.0.0/...). See Retrieving activity logs and user access logs.

Before you begin

Make sure you have:

A BIMcollab user account on the Playground. To get one, apply for a developer account.
An access token. See How to authenticate with the BIMcollab API.
A tool to send requests, such as Postman or cURL.

Send your first requests

All examples use the Playground. Choose the option that suits you:

Option A: Postman: the collection you created during authorization adds the access token to every request.
Option B: cURL: replace <access-token> with your access token.

The base URL for all requests is:

https://playground.bimcollab.com/bcf

Get your projects

Option A: Postman

Go to the collection you created in How to authenticate with the BIMcollab API.
Create a new GET request.
Paste the endpoint below in the URL field:

https://playground.bimcollab.com/bcf/bc_2.1/projects

Click Send.

Option B: cURL

curl -X GET "https://playground.bimcollab.com/bcf/bc_2.1/projects" \
  -H "Authorization: Bearer <access-token>"

The response lists the projects that you are a member of:

[
   {
    "projectId": "<project_id>",
    "name": "Example Project",
    "authorization": {
      "actions": [
        0
      ]
    },
]

Copy the <project_id>. You need it for the next requests.

Get the project extensions

The extensions tell you the Issues fields you can use in this project, for example, the available statuses and types.

⚠️ Attention: You can't modify or create extensions with the API. These can only be set manually on the BIMcollab project's settings page.

Option A: Postman

Create a new GET request in your collection.
Paste the endpoint below in the URL field. Replace the placeholders with your IDs:

https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/extensions

Click Send.

Option B: cURL

curl -X GET "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/extensions" \
  -H "Authorization: Bearer <access-token>"

📝 Note: When you create or update an issue, use only values that appear in the extensions. If you use other values, the request can fail.

Get the issues of the project

Option A: Postman

Create a new GET request in your collection.
Paste the endpoint below in the URL field. Replace the placeholders with your IDs:

https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics

Click Send.

Option B: cURL

curl -X GET "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics" \
  -H "Authorization: Bearer <access-token>"

The response lists the issues in the project. Each issue has a <globalId>, its unique ID.

Get one issue

Option A: Postman

Create a new GET request in your collection.
Paste the endpoint below in the URL field. Replace the placeholders with your IDs:

https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<globalId>

Click Send.

Option B: cURL

curl -X GET "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics/<globalId>" \
  -H "Authorization: Bearer <access-token>"

Create an issue

The request body below contains the details of the new issue:

{
  "title": "Beam inside wall",
  "topic_type": "Issue",
  "topic_status": "Active",
  "description": "The beam intersects the wall on level 2."
}

Replace the values for <topic_type> and <topic_status> with values from the extensions of your project.

Option A: Postman

Create a new POST request in your collection.
Paste the endpoint below in the URL field. Replace the placeholder with your project ID:

https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics

Go to the Body tab and select raw and JSON.
Paste the request body.
Click Send.

Option B: cURL

curl -X POST "https://playground.bimcollab.com/bcf/bc_2.1/projects/<project-id>/topics" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Beam inside wall",
    "topic_type": "Issue",
    "topic_status": "Active",
    "description": "The beam intersects the wall on level 2."
  }'

The response contains the new issue, including its <globalId>.

💡 Tip: Open the project in the BIMcollab web app to see the new issue.

Common tasks

Task	Method and endpoint
Get projects	`GET /bc_2.1/projects`
Get project settings	`GET /bc_2.1/projects/{project_id}/extensions`
Get issues	`GET /bc_2.1/projects/{project_id}/topics`
Get one issue	`GET /bc_2.1/projects/{project_id}/topics/{topic_guid}`
Create an issue	`POST /bc_2.1/projects/{project_id}/topics`
Update an issue	`PUT /bc_2.1/projects/{project_id}/topics/{topic_guid}`
Get comments	`GET /bc_2.1/projects/{project_id}/topics/{topic_guid}/comments`
Add a comment	`POST /bc_2.1/projects/{project_id}/topics/{topic_guid}/comments`
Get viewpoints	`GET /bc_2.1/projects/{project_id}/topics/{topic_guid}/viewpoints`
Add a viewpoint	`POST /bc_2.1/projects/{project_id}/topics/{topic_guid}/viewpoints`

All endpoints start with the base URL: https://<space-name>.bimcollab.com/bcf.

Documentation

BCF-API documentation on GitHub: explains how the BCF-API works, with many examples. Start here if the BCF-API is new to you.
Connection API reference guide: lists all endpoints and fields of the Connection API.

Troubleshooting

Problem	Possible cause	Solution
`401 Unauthorized`	The access token is missing or expired.	Refresh the access token. See How to authenticate with the BIMcollab API.
The project list is empty.	Your user account isn't a member of any project.	Ask the project leader to add you to a project.
`404 Not found`	The project ID, topic GUID, or version in the URL is wrong.	Check the IDs and use `bc_2.1` or `2.1`.
`400 Bad request` when you create an issue	A value isn't allowed in this project, or a required field is missing.	Check the extensions and the required fields.

Getting started with the Connection API

What is the Connection API?

What is BCF?

How issue data is organized

BIMcollab terms and API fields

Choose a version

Before you begin

Send your first requests

Get your projects

Option A: Postman

Option B: cURL

Get the project extensions

Option A: Postman

Option B: cURL

Get the issues of the project

Option A: Postman

Option B: cURL

Get one issue

Option A: Postman

Option B: cURL

Create an issue

Option A: Postman

Option B: cURL

Common tasks

Documentation

Troubleshooting

Next steps