---
title: "Initiate the upload flow"
method: POST
path: "/upload-documents"
tags: ["Upload"]
---

# Initiate the upload flow

`POST /upload-documents`

The client will call this endpoint to initiate the flow of uploading documents to the CDE.

## Request body

- UploadDocuments
  - `callback` CallbackLink, required
    - `url` string, required — The server will web-browser-redirect to this URL once the user has completed selecting documents or entering documenet metadata on the CDE
    - `expires_in` integer, required — The expiry period for the URL, in seconds
  - `server_context` string, nullable — A CDE controlled identifier recording the user's context on the CDE. For example which project and folder the user was on. If the client provides the `server_context` in subsequent calls then the CDE will attemp to load the UI at the same place.
  - `files` FileToUpload[], required
    - `file_name` string, required — The CDE UI will display this value to the User when entering document metadata
    - `session_file_id` string, required — This is a client provided id to differentiate between multiple files that are being uploaded in the same session
    - `document_id` string — When present, indicates that this upload is a new version of an existing document

## Response `200`

The CDE returns a URL for the client to open in a local browser. The user will then be presented with the CDE UI to enter document metadata

- DocumentUploadSessionInitialization
  - `upload_ui_url` string, required — A CDE UI URL for the client to open in a local browser. The user would enter document metadata directly in the CDE
  - `expires_in` integer, required — `upload_ui_url` expiry in seconds
  - `max_size_in_bytes` integer, required — The maximum file size supported by the CDE. Attempts to upload a larger file will fail

## Changes

- **2022-08-11** `2d09dcd8ade2` — 1 info
  - api operation id `/upload-documents` was added
- **2022-03-21** `504148fb6f8f` — 1 warning, 1 info
  - removed the request property `upload_context`
  - added the new optional request property `server_context`
- **2022-02-16** `30259031e29d` — 1 info
  - api tag `Upload` added
- **2022-02-14** `3eaa30d597fd` — 1 warning, 3 info
  - removed the request property `server_context`
  - api operation id `/upload-documents` removed and replaced with ``
  - api tag `Upload` removed
  - added the new optional request property `upload_context`

[Change history](https://skmtc.dev/buildingsmart/apis/opencde-documents-api/changes/upload-documents/post.md)

---

[API](https://skmtc.dev/buildingsmart/apis/opencde-documents-api.md) · [All operations](https://skmtc.dev/buildingsmart/apis/opencde-documents-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/buildingsmart/opencde-documents-api/revisions/b6d5b5ee5da6/schema)