---
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 from 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/b6d5b5ee5da6/schema)