---
title: "Retrieve upload instructions after the user has entered document metadata on the CDE"
method: POST
path: "/server-provided-path-upload-documents-url"
tags: ["Upload"]
---

# Retrieve upload instructions after the user has entered document metadata on the CDE

`POST /server-provided-path-upload-documents-url`

This endpoint returns the document upload information. The client retrieves this url via the callback url from the server after the user's completion of the upload metadata entry. The url of this endpoint is retrieved from the callback sent to the client in a query parameter named upload_documents_url. In case when the user cancels the upload on the CDE UI, this callback will still be called, but the upload_documents_url query parameter will not be present, instead the server will provide a query parameter called user_cancelled_upload=true.

## Request body

- UploadFileDetails — This object holds information about files to be uploaded. Each file in the array needs a file size so that the server can calculate the needed parts for a multipart upload. The session_file_id is used to identify the file.
  - `files` UploadFileDetail[], required
    - `size_in_bytes` integer, required — The uploaded file size
    - `session_file_id` string, required — This is a client provided id to differentiate between multiple files that are being uploaded in the same session

## Response `200`

- DocumentsToUpload
  - `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.
  - `documents_to_upload` DocumentToUpload[], required
    - `session_file_id` string, required — A client-provided identifier that allows matching the specification with the correct file on the user's machine
    - `upload_file_parts` UploadFilePartInstruction[], required — An array of request specifications detailing how to split the file to parts and upload each part to the CDE
      - `url` string, required
      - `http_method` 'POST' | 'PUT', required
      - `additional_headers` Headers — An array of required HTTP headers
        - `values` HeaderValue[], required
          - `name` string, required
          - `value` string, required
      - `include_authorization` boolean — Whether or not to include the authorization request header in the file upload request. Including the authorization header with some cloud storage providers might fail the request
      - `multipart_form_data` MultipartFormData — Multipart Form Data descriptor. If the CDE provided custom data here to be used in multipart requests then it is very likely that the CDE will also set a custom Content-Type header with the multipart/form-data type and a server-provided boundary
        - `prefix` string, byte, required — This is a server provided value. Its value must be prefixed to the binary content body when uploading this part
        - `suffix` string, byte, required — This is a server provided value. Its value must be suffixed to the binary content body when uploading this part. Typically, this is the end boundary for a multipart/form-data request
      - `content_range_start` integer, required — The inclusive, zero index based start for this part
      - `content_range_end` integer, required — The inclusive, zero index based end for this part
    - `upload_completion` LinkData, required
      - `url` string, required
    - `upload_cancellation` LinkData, required
      - `url` string, required

## Other responses

- `400` — This error may be returned if the file size exceeds the maximum length supported by the server.

## Changes

- **2022-08-11** `2d09dcd8ade2` — 1 info
  - api operation id `/server-provided-path-upload-documents-url` was added
- **2022-03-21** `504148fb6f8f` — 1 warning, 1 info
  - removed the optional property `upload_context` from the response with the `200` status
  - added the optional property `server_context` to the response with the `200` status
- **2022-02-16** `30259031e29d` — 1 info
  - api tag `Upload` added
- **2022-02-14** `3eaa30d597fd` — 1 warning, 3 info
  - removed the optional property `server_context` from the response with the `200` status
  - api operation id `/server-provided-path-upload-documents-url` removed and replaced with ``
  - api tag `Upload` removed
  - added the optional property `upload_context` to the response with the `200` status

[Change history](https://skmtc.dev/buildingsmart/apis/opencde-documents-api/changes/server-provided-path-upload-documents-url/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/2d09dcd8ade2/schema)