---
title: Create revision
slug: model-api/create-revision
docTags: 
createdAt: 2024-06-10T16:48:45.445Z
---

{
  "id": "IdzKaGTMk3J9vmSMz8-wP",
  "type": "api-oas-v2",
  "data": {
    "method": "POST",
    "url": "https://api.catenda.com/v2/projects/{project-id}/revisions",
    "servers": [
      {
        "url": "https://api.catenda.com/v2/projects/{project-id}/revisions"
      }
    ],
    "name": "Create revision",
    "description": "<p>Upload a new model revision.</p>\n<p>There are two ways to upload the IFC file:</p>\n<ul>\n<li><strong>Content-Type: application/ifc</strong> — the file is the entire request body and the upload parameters are sent in the <code>Bimsync-Params</code> header. Non-ASCII characters in <code>filename</code> and <code>comment</code> can be sent as raw UTF-8. Do not percent-encode individual field values: <code>filename</code> is percent-decoded on this route but <code>comment</code> is not, so a percent-encoded <code>comment</code> is stored as its encoded text, and a <code>filename</code> that genuinely contains a percent sign is altered.</li>\n<li><strong>Content-Type: multipart/form-data</strong> — the upload parameters are sent as a <code>Bimsync-Params</code> part and the file as a <code>file</code> part. Part bodies are read as UTF-8, so filenames and comments containing non-ASCII characters can be sent as they are, and a literal percent sign is left alone rather than decoded. <strong>Send the <code>Bimsync-Params</code> part before the <code>file</code> part</strong> — the upload is streamed rather than held in memory, so parameters that arrive after the file are rejected with a 400.</li>\n</ul>\n<p><strong>Note:</strong> The code examples for this method may have incorrect headers.</p>",
    "contentType": "application/ifc",
    "request": {
      "pathParameters": [
        {
          "kind": "required",
          "name": "project-id",
          "type": "string",
          "example": "af2d8af0fa54465b89bf26dd3d92cfd0",
          "description": "Catenda project id"
        }
      ],
      "headerParameters": [
        {
          "name": "accept",
          "type": "string",
          "kind": "optional",
          "description": "Generated from available response content types",
          "enum": [
            "application/json"
          ],
          "default": "application/json"
        },
        {
          "kind": "optional",
          "name": "Bimsync-Params",
          "type": "object",
          "description": "<p>Upload parameters, as a JSON object.</p>\n<p>Required when uploading with <strong>Content-Type: application/ifc</strong>, <code>application/ifczip</code>, <code>application/ifcxml</code> or <code>application/octet-stream</code>. Non-ASCII characters in <code>filename</code> and <code>comment</code> can be sent as raw UTF-8. Do not percent-encode individual field values: <code>filename</code> is percent-decoded on this route but <code>comment</code> is not. To send a value containing a literal percent sign, pass the parameters in the request body instead by uploading with <strong>Content-Type: multipart/form-data</strong>.</p>",
          "customType": "model-revision-upload-params",
          "schema": [
            {
              "name": "callbackUri",
              "kind": "optional",
              "type": "string",
              "description": "<p>Pass a URI to be notified when the revision is processed.</p>\n<p>Catenda will issue an HTTP GET request with the query parameter token set to revision status id and result set to either <strong>success</strong> or <strong>error</strong>.</p>",
              "example": "https://example.com"
            },
            {
              "name": "comment",
              "kind": "required",
              "type": "string",
              "description": "<p>Text describing the revision, limited to 64K characters</p>",
              "example": "Revision description"
            },
            {
              "name": "filename",
              "kind": "required",
              "type": "string",
              "description": "<p>The original name of the IFC file.</p>\n<p>The name is used in format detection and should have the extension .ifc, .ifcZIP or .ifcXML.</p>",
              "example": "ARCH.ifc"
            },
            {
              "name": "model",
              "kind": "required",
              "type": "string",
              "description": "Id of the model the revision should be added to.",
              "example": "37024671cbd642a9b7d84808b4d509f5"
            }
          ],
          "modelRef": "#/components/schemas/model-revision-upload-params"
        }
      ],
      "queryParameters": [],
      "bodyDataParameters": [],
      "formDataParameters": [
        {
          "name": "Bimsync-Params",
          "kind": "required",
          "type": "object",
          "description": "",
          "modelRef": "#/components/schemas/model-revision-upload-params",
          "customType": "model-revision-upload-params",
          "schema": [
            {
              "name": "callbackUri",
              "kind": "optional",
              "type": "string",
              "description": "<p>Pass a URI to be notified when the revision is processed.</p>\n<p>Catenda will issue an HTTP GET request with the query parameter token set to revision status id and result set to either <strong>success</strong> or <strong>error</strong>.</p>",
              "example": "https://example.com"
            },
            {
              "name": "comment",
              "kind": "required",
              "type": "string",
              "description": "<p>Text describing the revision, limited to 64K characters</p>",
              "example": "Revision description"
            },
            {
              "name": "filename",
              "kind": "required",
              "type": "string",
              "description": "<p>The original name of the IFC file.</p>\n<p>The name is used in format detection and should have the extension .ifc, .ifcZIP or .ifcXML.</p>",
              "example": "ARCH.ifc"
            },
            {
              "name": "model",
              "kind": "required",
              "type": "string",
              "description": "Id of the model the revision should be added to.",
              "example": "37024671cbd642a9b7d84808b4d509f5"
            }
          ]
        },
        {
          "name": "file",
          "kind": "required",
          "type": "string<binary>",
          "description": "The contents of the IFC file.",
          "format": "binary"
        }
      ],
      "oAuthParameters": [
        {
          "id": "Bearer",
          "name": "Bearer",
          "kind": "optional",
          "type": "http",
          "scheme": "bearer"
        }
      ],
      "cookieParameters": []
    },
    "responses": [
      {
        "statusCode": "200",
        "description": "OK",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "model-revision-status",
            "schema": [
              {
                "name": "callbackUri",
                "kind": "optional",
                "type": "string",
                "description": "The callback URI specified when uploading the revision",
                "example": "https://example.com"
              },
              {
                "name": "filename",
                "kind": "optional",
                "type": "string",
                "description": "The filename specified when uploading the revision",
                "example": "ARC.ifc"
              },
              {
                "name": "id",
                "kind": "optional",
                "type": "string",
                "description": "<p>A unique identifier for the status, represented as compacted UUID using 32 hexadecimal characters</p>",
                "example": "fcbb72736862483f89d44890d47ec112"
              },
              {
                "name": "model",
                "kind": "optional",
                "type": "object",
                "description": "<p>Represents an IFC model as a set of Revisions.</p>\n<p>A large building project can contain multiple IFC models.</p>\n<p>They are often divided by domain (architecture, electrical, etc.)</p>",
                "modelRef": "#/components/schemas/model",
                "customType": "model",
                "schema": [
                  {
                    "name": "id",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>A unique identifier for a model, represented as compacted UUID using 32 hexadecimal characters</p>",
                    "example": "47024671cbd642a9c7c84808d4d509f5"
                  },
                  {
                    "name": "name",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>The name of the model, limited to 512 characters</p>",
                    "example": "Model name"
                  }
                ]
              },
              {
                "name": "processing",
                "kind": "optional",
                "type": "object",
                "description": "Represents the processing status of a pending revision",
                "example": "",
                "schema": [
                  {
                    "name": "progress",
                    "kind": "optional",
                    "type": "number",
                    "description": "Processing progress as a number between 0.0 and 1.0",
                    "example": 0
                  },
                  {
                    "name": "status",
                    "kind": "optional",
                    "type": "string<waiting | processing | success | failure>",
                    "description": "<p>Valid values are \"waiting\", \"processing\", \"success\" or \"failure\"</p>",
                    "example": "waiting",
                    "enum": [
                      "waiting",
                      "processing",
                      "success",
                      "failure"
                    ]
                  },
                  {
                    "name": "error",
                    "kind": "optional",
                    "type": "object",
                    "description": "",
                    "modelRef": "#/components/schemas/error",
                    "customType": "error",
                    "schema": [
                      {
                        "name": "code",
                        "kind": "optional",
                        "type": "integer",
                        "description": "The error code"
                      },
                      {
                        "name": "message",
                        "kind": "optional",
                        "type": "string",
                        "description": "The error message"
                      }
                    ]
                  }
                ]
              },
              {
                "name": "revision",
                "kind": "optional",
                "type": "object",
                "description": "Represents a revision of a Model.\n\nA new revision is created by uploading an IFC model.\n",
                "modelRef": "#/components/schemas/model-revision",
                "customType": "model-revision",
                "schema": [
                  {
                    "name": "comment",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>Text describing the revision, limited to 64K characters</p>",
                    "example": "Revision description"
                  },
                  {
                    "name": "createdAt",
                    "kind": "optional",
                    "type": "string",
                    "description": "The date and time the revision was created in ISO 8601 format",
                    "example": "2016-09-26T14:45:20.000Z"
                  },
                  {
                    "name": "extendedVersion",
                    "kind": "optional",
                    "type": "object",
                    "description": "Extended version of the revision",
                    "example": "",
                    "schema": [
                      {
                        "name": "major",
                        "kind": "optional",
                        "type": "number",
                        "description": "Major version of the revision",
                        "example": 1
                      },
                      {
                        "name": "minor",
                        "kind": "optional",
                        "type": "string",
                        "nullable": true,
                        "description": "Minor version of the revision",
                        "example": 1
                      }
                    ]
                  },
                  {
                    "name": "id",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>A unique identifier for the revision, represented as compacted UUID using 32 hexadecimal characters.</p>",
                    "example": "924809076a694255c489d236517a55da"
                  },
                  {
                    "name": "model",
                    "kind": "optional",
                    "type": "object",
                    "description": "<p>Represents an IFC model as a set of Revisions.</p>\n<p>A large building project can contain multiple IFC models.</p>\n<p>They are often divided by domain (architecture, electrical, etc.)</p>",
                    "modelRef": "#/components/schemas/model",
                    "customType": "model",
                    "schema": [
                      {
                        "name": "id",
                        "kind": "optional",
                        "type": "string",
                        "description": "<p>A unique identifier for a model, represented as compacted UUID using 32 hexadecimal characters</p>",
                        "example": "47024671cbd642a9c7c84808d4d509f5"
                      },
                      {
                        "name": "name",
                        "kind": "optional",
                        "type": "string",
                        "description": "<p>The name of the model, limited to 512 characters</p>",
                        "example": "Model name"
                      }
                    ]
                  },
                  {
                    "name": "user",
                    "kind": "optional",
                    "type": "object",
                    "description": "<p>Represents a User, Organization or Team.</p>\n<p>A User is someone with a Catenda account, commonly representing a person.</p>\n<p>An Organization represents a company, project organization or an application. Organizations do not have a username and cannot sign in to Catenda.</p>\n<p>A Team represents a group of users within a project. Teams do not have a username and cannot sign in to Catenda.</p>",
                    "modelRef": "#/components/schemas/user",
                    "customType": "user",
                    "schema": [
                      {
                        "name": "id",
                        "kind": "optional",
                        "type": "string",
                        "description": "Represented as compacted UUID using 32 hexadecimal characters",
                        "example": "524809076a694255b989d236517a55da"
                      },
                      {
                        "name": "name",
                        "kind": "optional",
                        "type": "string",
                        "description": "<p>The name of the user, limited to 128 characters</p>",
                        "example": "John Doe"
                      },
                      {
                        "name": "username",
                        "kind": "optional",
                        "type": "string",
                        "nullable": true,
                        "description": "<p>The handle the user identifies with.</p>\n<p>Commonly the username will be in email address format. Usernames are unique but subject to change, we recommend using the id field to reference users instead.</p>\n<p>If the user represents an organization or a team the value is always null.</p>\n<p>Limited to 50 characters.</p>",
                        "example": "john@doe.com"
                      },
                      {
                        "name": "email",
                        "kind": "optional",
                        "type": "string",
                        "description": "Email address of the User",
                        "example": "john@doe.com"
                      },
                      {
                        "name": "createdAt",
                        "kind": "optional",
                        "type": "string",
                        "description": "The date and time the user was created in ISO 8601 format",
                        "example": "2016-09-20T14:55:22.000Z"
                      },
                      {
                        "name": "avatarUrl",
                        "kind": "optional",
                        "type": "string",
                        "description": "The URL for the user avatar",
                        "example": "https://api.catenda.com/v2/avatar/397t0ccd8f74516096c738de15dc6512"
                      },
                      {
                        "name": "type",
                        "kind": "optional",
                        "type": "string<user | organization | team>",
                        "description": "<p>The type of user, valid values are:</p>\n<ul>\n<li>user</li>\n<li>organization</li>\n<li>team</li>\n</ul>",
                        "example": "user",
                        "enum": [
                          "user",
                          "organization",
                          "team"
                        ]
                      }
                    ]
                  },
                  {
                    "name": "version",
                    "kind": "optional",
                    "type": "integer",
                    "description": "A number that is incremented for each new revision of a model",
                    "example": 1
                  }
                ]
              },
              {
                "name": "user",
                "kind": "optional",
                "type": "object",
                "description": "<p>Represents a User, Organization or Team.</p>\n<p>A User is someone with a Catenda account, commonly representing a person.</p>\n<p>An Organization represents a company, project organization or an application. Organizations do not have a username and cannot sign in to Catenda.</p>\n<p>A Team represents a group of users within a project. Teams do not have a username and cannot sign in to Catenda.</p>",
                "modelRef": "#/components/schemas/user",
                "customType": "user",
                "schema": [
                  {
                    "name": "id",
                    "kind": "optional",
                    "type": "string",
                    "description": "Represented as compacted UUID using 32 hexadecimal characters",
                    "example": "524809076a694255b989d236517a55da"
                  },
                  {
                    "name": "name",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>The name of the user, limited to 128 characters</p>",
                    "example": "John Doe"
                  },
                  {
                    "name": "username",
                    "kind": "optional",
                    "type": "string",
                    "nullable": true,
                    "description": "<p>The handle the user identifies with.</p>\n<p>Commonly the username will be in email address format. Usernames are unique but subject to change, we recommend using the id field to reference users instead.</p>\n<p>If the user represents an organization or a team the value is always null.</p>\n<p>Limited to 50 characters.</p>",
                    "example": "john@doe.com"
                  },
                  {
                    "name": "email",
                    "kind": "optional",
                    "type": "string",
                    "description": "Email address of the User",
                    "example": "john@doe.com"
                  },
                  {
                    "name": "createdAt",
                    "kind": "optional",
                    "type": "string",
                    "description": "The date and time the user was created in ISO 8601 format",
                    "example": "2016-09-20T14:55:22.000Z"
                  },
                  {
                    "name": "avatarUrl",
                    "kind": "optional",
                    "type": "string",
                    "description": "The URL for the user avatar",
                    "example": "https://api.catenda.com/v2/avatar/397t0ccd8f74516096c738de15dc6512"
                  },
                  {
                    "name": "type",
                    "kind": "optional",
                    "type": "string<user | organization | team>",
                    "description": "<p>The type of user, valid values are:</p>\n<ul>\n<li>user</li>\n<li>organization</li>\n<li>team</li>\n</ul>",
                    "example": "user",
                    "enum": [
                      "user",
                      "organization",
                      "team"
                    ]
                  }
                ]
              }
            ],
            "modelRef": "#/components/schemas/model-revision-status",
            "isExpanded": true
          }
        ]
      }
    ],
    "hasXCodeSamples": false,
    "examples": {
      "languages": [
        {
          "id": "BR_v8dHY1ZO6eMLCO9AJr",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request POST \\\n     --url https://api.catenda.com/v2/projects/{project-id}/revisions \\\n     --header 'accept: application/json' \\\n     --header 'content-type: application/ifc' \\\n     --header 'bimsync-params: {\"comment\":\"string\",\"filename\":\"string\",\"model\":\"string\"}' \\\n     --form 'Bimsync-Params=\"{\\\"comment\\\":\\\"string\\\",\\\"filename\\\":\\\"string\\\",\\\"model\\\":\\\"string\\\"}\"' \\\n     --form 'file=@\"/path/to/file\"'"
        },
        {
          "id": "XD0YeJmelVEcsXwAu1rva",
          "language": "javascript",
          "label": "javascript",
          "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/ifc\");\nmyHeaders.append(\"bimsync-params\", \"{\\\"comment\\\":\\\"string\\\",\\\"filename\\\":\\\"string\\\",\\\"model\\\":\\\"string\\\"}\");\n\nvar formdata = new FormData();\nformdata.append(\"Bimsync-Params\", \"{\\\"comment\\\":\\\"string\\\",\\\"filename\\\":\\\"string\\\",\\\"model\\\":\\\"string\\\"}\");\nformdata.append(\"file\", fileInput.files[0], \"file\");\n\nvar requestOptions = {\n   method: 'POST',\n   headers: myHeaders,\n   body: formdata,\n   redirect: 'follow'\n};\n\nfetch(\"https://api.catenda.com/v2/projects/{project-id}/revisions\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "mEnAEZcLUA1tHS7tKMtG-",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.catenda.com/v2/projects/{project-id}/revisions\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/ifc\"\nrequest[\"bimsync-params\"] = \"{\\\"comment\\\":\\\"string\\\",\\\"filename\\\":\\\"string\\\",\\\"model\\\":\\\"string\\\"}\"\nform_data = [['Bimsync-Params', File.open('undefined')],['file', File.open('/path/to/file')]]\nrequest.set_form form_data, 'multipart/form-data'\nresponse = https.request(request)\nputs response.read_body\n"
        },
        {
          "id": "aZ36Fn912UquYhibz4NjT",
          "language": "python",
          "label": "Python",
          "code": "import requests\n\nurl = \"https://api.catenda.com/v2/projects/{project-id}/revisions\"\n\npayload = {}\nfiles=[\n   ('file',('file',open('/path/to/file','rb'),'application/octet-stream'))\n]\nheaders = {\n   'accept': 'application/json',\n   'content-type': 'application/ifc',\n   'bimsync-params': '{\"comment\":\"string\",\"filename\":\"string\",\"model\":\"string\"}'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload, files=files)\n\nprint(response.text)\n"
        }
      ],
      "selectedLanguageId": "BR_v8dHY1ZO6eMLCO9AJr"
    },
    "results": {
      "languages": [
        {
          "id": "response-0-200",
          "language": "200",
          "code": "// OK\n{\n  \"callbackUri\": \"https://example.com\",\n  \"filename\": \"ARC.ifc\",\n  \"id\": \"fcbb72736862483f89d44890d47ec112\",\n  \"model\": {\n    \"id\": \"47024671cbd642a9c7c84808d4d509f5\",\n    \"name\": \"Model name\"\n  },\n  \"processing\": {\n    \"progress\": 0,\n    \"status\": \"waiting\",\n    \"error\": {\n      \"code\": 0,\n      \"message\": \"\"\n    }\n  },\n  \"revision\": {\n    \"comment\": \"Revision description\",\n    \"createdAt\": \"2016-09-26T14:45:20.000Z\",\n    \"extendedVersion\": {\n      \"major\": 1,\n      \"minor\": 1\n    },\n    \"id\": \"924809076a694255c489d236517a55da\",\n    \"model\": {\n      \"id\": \"47024671cbd642a9c7c84808d4d509f5\",\n      \"name\": \"Model name\"\n    },\n    \"user\": {\n      \"id\": \"524809076a694255b989d236517a55da\",\n      \"name\": \"John Doe\",\n      \"username\": \"john@doe.com\",\n      \"email\": \"john@doe.com\",\n      \"createdAt\": \"2016-09-20T14:55:22.000Z\",\n      \"avatarUrl\": \"https://api.catenda.com/v2/avatar/397t0ccd8f74516096c738de15dc6512\",\n      \"type\": \"user\"\n    },\n    \"version\": 1\n  },\n  \"user\": {\n    \"id\": \"524809076a694255b989d236517a55da\",\n    \"name\": \"John Doe\",\n    \"username\": \"john@doe.com\",\n    \"email\": \"john@doe.com\",\n    \"createdAt\": \"2016-09-20T14:55:22.000Z\",\n    \"avatarUrl\": \"https://api.catenda.com/v2/avatar/397t0ccd8f74516096c738de15dc6512\",\n    \"type\": \"user\"\n  }\n}"
        }
      ],
      "selectedLanguageId": "response-0-200"
    }
  },
  "children": [
    {
      "text": ""
    }
  ]
}