Skip to main content

Getting started with the Documents API

The Documents API lets your application read and manage files in a BIMcollab space. This article explains the key concepts, shows how document data is organized, and guides you through your first requests on the Playground, from your first request to finding the IDs you need to upload files.

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

What is the Documents API?

The Documents API is part of the BIMcollab API. It gives your application access to the most common actions for the document management system (DMS) of your BIMcollab space.

The Documents API is a REST API. Your application sends web requests (GET, POST, PUT, PATCH) and receives responses in JSON format.

With the Documents API, your application can:

  • Read the space structure: location groups, locations, projects, and project phases you have access to, as well as companies and disciplines.

  • Get document details: read all information about the documents in your projects or project phases, including document sets, linked files, and document versions.

  • Download files: download the latest version of a document, or a specific document version.

  • Upload new files: add a new document or a new document version.

  • Update document metadata: add or change the document number, label, status, author, custom fields, and more.

  • Retrieve To-do data: get a list of all questions, reviews, revisions, or tasks in a project or project phase.

Common things people build with it:

  • Automatic publishing: push models, drawings, or reports from your own system straight into BIMcollab.

  • Bulk upload: send many files at once instead of dragging them in one by one.

  • Automatic syncing: keep files in external CDEs and in BIMcollab aligned.

  • Reporting/dashboards: read the project structure and document data to feed your own tools.

📝 Note: Combine both APIs; use the Documents API to get file data and the Connection API to monitor issues. See BIMcollab developers options overview for more details.

How document data is organized

Every request starts with a space. Inside the space, every project is created inside a location. Documents can belong to a project, or a project phase:

BIMcollab space (space ID)
├── Location groups
│   └── Locations
│       ├── Documents
│       │   └── Document versions
│       └── Projects
│           ├── Documents
│           │   └── Document versions
│           └── Project phases
│               └── Documents
│                   └── Document versions
└── Companies and disciplines

BIMcollab term

What it is

Space

Your BIMcollab space. Every request includes its ID.

Location group and location

Your BIMcollab space. Every request includes its ID.

Project

A BIMcollab project inside a location. Documents can belong directly to a project.

Project phase

A phase of a project. Documents can also belong to a specific phase.

Document

A file with its metadata, such as document number, status, and author.

Document version

A version of a document. Each upload of a new file for the same document creates a new version.

Document set

A group of documents.

To-do

A question, review, revision, or task linked to a project or project phase.

Company and discipline

Lists used in document metadata.

Endpoints and space ID

Base URL

All Documents API requests use this base URL:

https://api.eu.bimcollab.com/spaces/<space-id>/documents

On the Playground, this is:

https://api.eu.bimcollab.com/spaces/8e3136c4-2e93-4819-a44e-227c59de8f02/documents

Every endpoint is built from the same parts:

Part

Example

Base URL

https://api.eu.bimcollab.com/spaces/<space-id>/documents

Version

/v1

Path

/project-structure

Full endpoint

https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/project-structure

Space ID

Unlike the Connection API, the Documents API needs the space ID in almost every request. The space ID is the unique ID (GUID) of your BIMcollab space.

On the Playground, the space ID is 8e3136c4-2e93-4819-a44e-227c59de8f02.

When you request client credentials for your own space, you also receive its space ID.

📝 Note: You only need to read the space ID from your access token if you connect to another private space and don't have its ID. See Find your space ID in "How to authenticate with the BIMcollab API".

Before you begin

Make sure you have:

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.

In both options, replace <space-id> with your space ID. On the Playground, this is 8e3136c4-2e93-4819-a44e-227c59de8f02.

Get your project structure

This is the recommended first request. It returns an overview of everything you have access to in the space: location groups, locations, projects, and project phases.

The response contains the project IDs and project phase IDs that you need for many other Documents API requests.

Option A: Postman

  1. Go to the collection you created in How to authenticate with the BIMcollab API.

  2. Create a new GET request.

  3. Paste the endpoint below in the URL field. Replace the placeholder with your <space-id>:

    https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/project-structure

  4. Click Send.

Option B: cURL

curl -X GET "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/project-structure" \
  -H "Authorization: Bearer <access-token>"

The response lists the projects and project phases you have access to. Each project has a projectId, and each project phase has a projectPhaseId. 

{
    "locationGroups": [],
    "locations": [
        {
            "locationId": "13eb7a11-aae1-4b36-8695-26ddb71be879",
            "name": "Default",
            "code": "L00",
            "projects": [
                {
                    "projectId": "bfdbbdb4-a61a-46cb-bbc1-0f52a7a3cf8e",
                    "name": "Example Project",
                    "code": "DCX",
                    "projectPhases": []
                }
            ]
        }
    ]
}

Copy the ID of the project or project phase you want to work with. You need it for the next requests.

Get projects or project phases separately

If you only need projects or only project phases, you can request them separately. These endpoints return the results in pages.

Option A: Postman

  1. Create a new GET request in your collection.

  2. Paste one of the endpoints below in the URL field. Replace the placeholder with your <space-id>.

    1. To get all projects:

      https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects?limit=100&offset=0

    2. To get all project phases:

      https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/project-phases?limit=100&offset=0

  3. Click Send.

Option B: cURL

To get all projects:

curl -X GET "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects?limit=100&offset=0" \
  -H "Authorization: Bearer <access-token>"

To get all project phases:

curl -X GET "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/project-phases?limit=100&offset=0" \
  -H "Authorization: Bearer <access-token>"

About pages: limit and offset

Endpoints that return a list, such as projects, documents, or disciplines, return the results in pages. Two query parameters control this:

  • limit (required): how many items to return. Example: limit=10.

  • offset (optional): how many items to skip before starting. The default is 0. Example: offset=0 for the first page, offset=10 for the second page when limit=10.

⚠️ Attention: Always add limit to requests for a list. Without it, the request fails with 400 Bad request.

Get the documents of a project or project phase

Use your project ID or project phase ID from above.

Option A: Postman

  1. Create a new GET request in your collection.

  2. Paste one of the endpoints below in the URL field. Replace the placeholders with your IDs.

    1. To get the documents of a project:

      https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects/<project-id>/documents?limit=10&offset=0

    2. To get the documents of a project phase:

      https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/project-phases/<project-phase-id>/documents?limit=10&offset=0

  3. Click Send.

Option B: cURL

To get the documents of a project:

curl -X GET "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects/<project-id>/documents?limit=10&offset=0" \
  -H "Authorization: Bearer <access-token>"

To get the documents of a project phase:

curl -X GET "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/project-phases/<project-phase-id>/documents?limit=10&offset=0" \
  -H "Authorization: Bearer <access-token>"

The response lists the first 10 documents. To get the next 10, change the offset to offset=10. Copy the <document-id> the next step.

Filtering documents

You can add optional filters to the request. Some useful filters:

Filter

What it does

Example

searchText

Returns only documents where the document number, description, manufacturer, discipline, label, or work package code contains the text.

searchText=facade

newVersionSinceDateTime

Returns only documents with a new version since this date and time. Useful to sync only what changed.

newVersionSinceDateTime=2026-10-01T00:00:00Z

publishedOnly

Returns only documents with a published (approved) version.

publishedOnly=true

documentSetId

Returns only documents in this document set.

documentSetId=12

includeArchived

Also returns archived documents. Archived documents are left out by default.

includeArchived=true

Add filters to the end of the URL with &. Example:

https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects/<project-id>/documents?limit=10&offset=0&publishedOnly=true

💡 Tip: Use newVersionSinceDateTime to build a sync. Save the date and time of your last sync, and only request documents that changed after it.

Get one document and its versions

Option A: Postman

  1. Create a new GET request in your collection.

  2. Paste one of the endpoints below in the URL field. Replace the placeholders with your IDs.

    To get the document:

    https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/documents/<document-id>

    To get all versions of the document:

    https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/documents/<document-id>/document-versions

  3. Click Send.

Option B: cURL

To get the document:

curl -X GET "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/documents/<document-id>" \
  -H "Authorization: Bearer <access-token>"

To get all versions of the document:

curl -X GET "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/documents/<document-id>/document-versions" \
  -H "Authorization: Bearer <access-token>"

📝 Note: The list of versions of one document doesn't use limit and offset. It always returns all versions.

💡 Tip: To download the file of the latest version, use:

 GET <https://api.eu.bimcollab.com/spaces/<space-id>>/documents/v1/documents/<document-id>/download.

Upload your first document

Using the Documents API, you can only upload documents to a project or a project phase. Once you have the project ID or project phase ID, uploading a document takes three requests:

  1. Request an upload token for that project or project phase.

  2. Upload the file to the upload URL in the response.

  3. Create or update the document and its version in BIMcollab.

For all details, see Uploading documents with the Documents API.

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

Common tasks

Task

Method and endpoint

Get the project structure

GET /project-structure

Get projects

GET /projects?limit={limit}

Get project phases

GET /project-phases?limit={limit}

Get the documents of a project

GET /projects/{project-id}/documents?limit={limit}

Get the documents of a project phase

GET /project-phases/{project-phase-id}/documents?limit={limit}

Find a document by document number

GET /projects/{project-id}/documents/number?documentNumber={number}

Get one document

GET /documents/{document-id}

Update document metadata

PATCH /documents/{document-id}

Download the latest version of a document

GET /documents/{document-id}/download

Get all versions of a document

GET /documents/{document-id}/document-versions

Download a specific version

GET /document-versions/{document-version-id}/download

Get the document sets of a project

GET /projects/{project-id}/document-sets?limit={limit}

Request an upload token for a project

POST /projects/{project-id}/documents/upload-tokens

Request an upload token for a project phase

POST /project-phases/{project-phase-id}/documents/upload-tokens

Create or update a document in a project

PUT /projects/{project-id}/documents

Create or update a document in a project phase

PUT /project-phases/{project-phase-id}/documents

Request an upload token for a new version

POST /documents/{document-id}/document-versions/upload-tokens

Add a new version to an existing document

PUT /documents/{document-id}/document-versions

Get the questions of a project

GET /projects/{project-id}/questions?limit={limit}

Get companies, disciplines, labels, or custom fields

GET /companies, /disciplines, /labels or /custom-fields, with ?limit={limit}

💡 Tip: Most project endpoints also exist for project phases. For it, replace /projects/{project-id} with /project-phases/{project-phase-id}.

Documentation

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.

403 Forbidden

Your client credentials or user account don't have permission for this space, project, or project phase.

Check that you use the right space, and that your user account is a member of the project.

404 Not found

The space ID, project ID, or endpoint path is wrong.

Check the IDs and the URL. Make sure the URL includes /v1/spaces/<space-id>.

400 Bad request

A required parameter is missing or invalid. For example, limit is missing from a request for a list.

Add limit to the request, and check the other parameters.

The project structure is empty.

Your user account isn't a member of any project in this space.

Ask the project leader to add you to a project.

📝 Note: Error responses include a body with more details about the error. Check it to find the cause.

Next steps

Related Articles
Did this answer your question?