Issue, task or topic?
The same thing has more than one name here, depending on which surface you are looking at. This page is the translation. It is worth two minutes if you are going to use the API or an AI assistant, and skippable if you only use the web app.
The short version
The web app says issue. This help says issue throughout.
The BCF standard - and therefore the API - says topic. The
AI assistant tools say task in their names and hand back
fields called topic_something.
All three mean the same record.
The full table
| In the web app | In the BCF API | Notes |
|---|---|---|
| Issue | topic | Also called a task in the AI tool names. |
| Status | topic_status | |
| Type | topic_type | |
| Milestone | stage | The one that catches people out. Same field, different word. |
| Priority | priority | |
| Labels | topic_label | |
| Deadline | due_date | |
| Assigned to | assigned_to | An email address in the API, a name in the app. |
| Comments | comments | |
| A screenshot on a comment | a viewpoint snapshot | Images from other BIM tools arrive as viewpoints. |
| Activity | topic events | The AI tool for it is called read_topic_history. |
| The number in the address bar | not the same thing | See below. |
Two identifiers for one project
In the web app a project is a number: /projects/12.
In the API a project is a GUID - a long string like
02cb8156-a4b3-4782-b8f6-1b232d306ece. The two are not interchangeable, and the API will
not accept the number.
Issues have the same split: the app shows a short reference, the API uses a GUID. The GUID is the one that survives a trip through a BCF file into somebody else's software, which is why it is the identity that matters for exchange.
Why it is like this
Not because anybody wanted three names. The app grew a web interface first, using ordinary English words for ordinary things. Later it grew an API that implements the buildingSMART BCF standard properly - and the standard has its own vocabulary, which is not negotiable if the file is going to open in somebody else's tool.
Where the two disagree, the API follows the standard and the app keeps the word on the button.
This is a known rough edge rather than a design decision anybody is proud of, and it may be tidied up in the app itself. If that happens, this page shrinks.
If an AI assistant says something odd
An assistant reading the API will talk about topics and stages. It is not confused and neither are you - it is reading the standard's names. Translate with the table above, or just ask it to use the words the app uses.