---
title: Models and Revisions
slug: model-api/models-and-revisions
docTags: 
createdAt: 2026-09-11T14:49:23.882Z
---

# Upload a model revision

Use the create revision endpoint to upload an IFC file.

Valid file formats are:

- `IFC`
- `IFCZIP`

The upload parameters can be sent either in the `Bimsync-Params` request header or as a part of the request body.

**Prepare upload parameters**

Set the necessary fields of the JSON object.

```json
{
  "comment": "Comment describing the revision",
  "filename": "FileName.ifc",
  "model": "67a33d878bj7461f4352a64e1aef961h"
}
```

**Optional callback URI**

If you want to receive a notification when the revision is processed, set the `callbackUri` field.

```json
{
  "callbackUri": "https://example.com/callback",
  "comment": "Comment describing the revision",
  "filename": "FileName.ifc",
  "model": "67a33d878bj7461f4352a64e1aef961h"
}
```

Catenda will issue an HTTP GET request to the callback URI with the following query parameters.

- `token` contains a revision status id.
- `result` with value **success** or **error**.

**Make request with the parameters in the header**

Set the value to the `Bimsync-Params` request header, attach the file to the request and set the `Content-Type` header to `application/ifc`.

```curl
curl -X POST \
  'https://api.catenda.com/v2/projects/{project-id}/revisions/' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/ifc' \
  --header 'Bimsync-Params: {"callbackUri":"https://example.com/callback","comment":"Optional comment describing the revision","filename":"FileName.ifc","model":"67a33d878bj7461f4352a64e1aef961h"}' \
  --data-binary '@/path/to/FileName.ifc'
```

Non-ASCII characters in `filename` and `comment` can be sent as raw UTF-8 — a `filename` of `Blåbær.ifc` and a `comment` of `Blåbær 建物` are read correctly, with no percent-encoding.

Do **not** percent-encode individual field values on this route: `filename` is percent-decoded but `comment` is not, so a percent-encoded `comment` is stored as its encoded text (`Bl%C3%A5b%C3%A6r`), and a `filename` that genuinely contains a percent sign is altered (`100%20final.ifc` is read as `100 final.ifc`). To send a value that must contain a literal percent sign, pass the parameters in the request body instead.

**Make request with the parameters in the body**

Send the parameters as a `Bimsync-Params` part and the file as a `file` part, with the `Content-Type` header set to `multipart/form-data`. Part bodies are read as UTF-8, so filenames and comments containing non-ASCII characters can be sent as they are — no percent-encoding. Values are taken verbatim on this route, so a filename that genuinely contains a percent sign, such as `100%20final.ifc`, is stored exactly as written. On the header route the same filename would be read as `100 final.ifc`.

Order matters: send the `Bimsync-Params` part **before** the `file` part. The upload is streamed straight through rather than held in memory, so parameters arriving after the file cannot be read and the request is rejected with a 400. Clients that build the request in the order shown below get this for free.

```curl
curl -X POST \
  'https://api.catenda.com/v2/projects/{project-id}/revisions/' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'Bimsync-Params={"comment":"Blåbær 建物","filename":"Blåbær.ifc","model":"67a33d878bj7461f4352a64e1aef961h"};type=application/json' \
  --form 'file=@/path/to/Blåbær.ifc'
```

Note that `curl` sets `Content-Type: multipart/form-data` and its boundary itself when `--form` is used, so do not set that header yourself.

# Download a model revision

Use the get revision endpoint to download a model revision.

**Make request**

Set the `Accept` header to `application/ifc`.

```curl
curl -X GET \
  'https://api.catenda.com/v2/projects/{project-id}/revisions/{revision-id}' \
  --header 'Accept: application/ifc' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```