Skip to main content

The BCF API

Issuetracker implements the buildingSMART BCF REST API, so other software can read and write issues here directly - without anybody exporting a file, emailing it, and importing it at the other end.

This page is an orientation. The complete reference - every endpoint, every field, with examples you can try - is generated from the code and lives in the app itself at /api/docs.

Screenshot to come: the generated API reference.

When you would use it​

A BIM tool that already speaks BCF. Point it at this server and it works with the issues live, rather than through files. Whether your tool can do that is a question for its documentation, not this one.

Something you are building yourself - a dashboard, a report, a sync with another system.

If you just need to move issues between two tools once, a BCF file is simpler and needs no setup.

Versions​

Both 2.1 and 3.0 are supported for reading and writing.

Note the asymmetry with files: the API handles both versions, but file export writes 2.1 only.

Signing in​

The API uses your ordinary Issuetracker account, and you get exactly the permissions your account has in the app - the same rules as Who may do what. There is no separate API role, and no key that bypasses membership.

/api/docs covers the authentication flow in detail.

The vocabulary is not the app's​

This is where most first attempts go wrong. The API follows the BCF standard's names, not the ones on the buttons:

  • an issue is a topic
  • Milestone is stage
  • Deadline is due_date
  • a project is identified by a GUID, not the number in the address bar

The full table is on Issue, task or topic?. Read it before you write any code against this.

Which values it will accept​

For Status, Type, Priority, Milestone and Labels, the API accepts your project's own lists - the same values the dropdowns offer, which you control under Project options.

If a value is rejected, the project has not been configured to allow it. The fix is in the project settings, not in your request. Do not work around it by picking the nearest-looking value: that produces a tracker nobody can filter.

Fields with an empty list accept free text, so whatever you send becomes that project's de-facto vocabulary. Worth being deliberate about.

Two limits to design around​

Board order is not exposed. The manual order of cards inside a column is browser-only. If ordering matters to your integration, use priority.

Comment history is not recorded. Changes to comments are not written to the event log, so the comment events endpoint returns nothing on a real project. Topic field changes are recorded and readable.

What it does not replace​

The API is a way in for software. If what you actually want is an assistant that answers questions and raises issues in ordinary language, that is Connecting an AI assistant, which sits on top of the same data.