### Server-Provided Endpoint Examples

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/api-overview.md

Illustrates examples of server-provided URLs for various operations, which clients use to retrieve selections, download files, get metadata, and manage uploads.

```text
- `/server-provided-path-selected-documents-url` - Retrieve selections
- `/server-provided-path-document-download` - Download file
- `/server-provided-path-document-metadata` - Get metadata
- `/server-provided-path-document-versions` - List versions
- `/server-provided-path-document-version` - Get version info
- `/server-provided-path-upload-documents-url` - Get upload instructions
- `/server-provided-path-document-upload-file-part` - Upload file part (PUT or POST)
- `/server-provided-path-document-upload-completion` - Complete upload
- `/server-provided-path-document-upload-cancellation` - Cancel upload
```

--------------------------------

### Python Requests Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/MANIFEST.txt

Illustrates how to make an HTTP request using the Python requests library. Ensure the library is installed (`pip install requests`).

```python
import requests

response = requests.get("https://api.example.com/data")
print(response.json())
```

--------------------------------

### HTTP GET Request Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/MANIFEST.txt

A raw HTTP GET request example. This shows the basic structure of a request sent over HTTP.

```http
GET /resource/123 HTTP/1.1
Host: api.example.com
Accept: application/json
```

--------------------------------

### Example of Delegating to Cloud Storage for Dynamic URLs

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/implementation-notes.md

This option leverages cloud storage services like S3 for direct resource access. It requires proper authentication and authorization setup.

```shell
GET https://s3.amazonaws.com/bucket/doc-12345-v1.ifc
PUT https://s3.amazonaws.com/bucket/upload/xyz/part1?token=signed
```

--------------------------------

### DocumentVersion Links Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/api-overview.md

Provides an example of the named links available within a DocumentVersion response, indicating possible operations.

```text
Example: DocumentVersion.links contains:
- `document_version` - get fresh version info
- `document_version_download` - download file
- `document_version_metadata` - get metadata
- `document_versions` - list all versions
- `document_details` - view in browser
```

--------------------------------

### HTTP POST Request Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/MANIFEST.txt

A raw HTTP POST request example. This includes a request body, typically in JSON format.

```http
POST /resource HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "new item"
}
```

--------------------------------

### Example of Query Parameters for Dynamic URLs

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/implementation-notes.md

This option utilizes query parameters to specify resource identifiers and actions. It can be useful for simpler resource structures.

```shell
GET /download?doc=doc-12345&version=1
POST /upload?session=xyz&part=1
```

--------------------------------

### CDE Callback URL Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

This URL is provided by the CDE after a user enters document metadata. The client calls this URL to get upload instructions.

```url
http://localhost:8080/cde-callback-example?upload_documents_url=https%3A%2F%2Fcde.example.com%2Fupload-instructions%3Fupload_session%3Dee56b8f3-8f93-4819-976e-46a45a5a996f
```

--------------------------------

### Calculate Part Boundaries for Multipart Upload

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/implementation-notes.md

Example calculation for determining byte ranges for multipart upload parts based on file size and desired part size.

```text
Example: 10MB file, want 5MB parts
  Part 1: bytes 0-5242879 (5MB)
  Part 2: bytes 5242880-10485759 (5MB)

Example: 100MB file, want 10MB parts
  Part 1: bytes 0-10485759
  Part 2: bytes 10485760-20971519
  ... etc
```

--------------------------------

### POST /select-documents

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/endpoints.md

Initiates the document selection workflow. The client sends this request to start the process of selecting documents for download.

```APIDOC
## POST /select-documents

### Description
Initiates the document selection workflow. The client sends this request to start the process of selecting documents for download.

### Method
POST

### Endpoint
/select-documents

### Parameters
#### Request Body
- **callback** (CallbackLink) - Required - Callback URL configuration for the CDE to redirect the user back to the client
- **server_context** (string or null) - Optional - CDE-controlled identifier recording the user's context (e.g., project/folder). CDE will attempt to load UI at the same place if provided in subsequent calls
- **supported_file_extensions** (array of string) - Optional - Array of accepted file extensions with dot separator (e.g., `[".ifc", ".ifczip"]`). CDE should attempt to filter files by these extensions but is not required to guarantee compliance

### Response
#### Success Response (200)
- **select_documents_url** (string) - A CDE UI URL for the client to open in a local browser where the user searches and selects documents
- **expires_in** (integer (int32)) - `select_documents_url` expiry time in seconds

### Response Example
```json
{
  "select_documents_url": "https://cde.example.com/select?session_id=12345",
  "expires_in": 3600
}
```
```

--------------------------------

### BCF API Project File Information Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

This JSON structure represents project file information from a BCF API server. The 'reference' field indicates how to access the document version using the Documents API, specifying 'open-cde-documents://' as the protocol for BCF API and 'https://' for the Documents API.

```json
{
  "display_information": [
    {
      "field_display_name": "Model Name",
      "field_value": "ARCH-Z100-051"
    }
  ],
  "file": {
    "ifc_project": "0J$yPqHBD12v72y4qF6XcD",
    "file_name": "OfficeBuilding_Architecture_0001.ifc",
    "reference": "open-cde-documents://<document_version_url>"
  }
}
```

--------------------------------

### Download Selection and Retrieval Flow

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/REFERENCE.md

Initiate document selection, retrieve a list of selected documents, and download their binary content. The process involves client-initiated POST to /select-documents, followed by GET requests to retrieve the selected documents and their content.

```http
POST /select-documents
  ↓
  Returns: DocumentDiscoverySessionInitialization with UI URL
  
User selects documents in browser UI
  ↓
Browser redirects to callback with query parameter
  ↓
Client queries:
  GET /server-provided-path-selected-documents-url
  ↓
  Returns: SelectedDocuments with list of DocumentVersion

For each selected document:
  GET /server-provided-path-document-download
  ↓
  Returns: Binary file content (application/octet-stream)
```

--------------------------------

### Example of Opaque Tokens for Dynamic URLs

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/implementation-notes.md

This option uses opaque tokens in the URL, abstracting the underlying resource location. It can enhance security by not exposing direct paths.

```shell
GET /resource/abc123xyz
PUT /upload/token-xyz-abc-123
```

--------------------------------

### Example of Resource IDs in Path for Dynamic URLs

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/implementation-notes.md

This option uses resource IDs directly within the URL path to identify resources. It is a common RESTful approach.

```shell
GET /documents/doc-12345/download
POST /uploads/session-xyz/parts
```

--------------------------------

### List Document Versions Request

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

Use this GET request to retrieve all available versions of a specific document. The response contains a list of document versions, each with a version index.

```http
GET /server-provided-path-document-versions HTTP/1.1
Host: cde.example.com
```

--------------------------------

### Download Document File Request

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

Initiate a GET request to download the binary content of a document file. The 'Range' header can be used for partial downloads.

```http
GET /server-provided-path-document-download HTTP/1.1
Host: cde.example.com
Range: bytes=0-1048575
```

--------------------------------

### Client Initiates Download Request

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

Use this POST request to initiate a download workflow. Include a callback URL for CDE notifications and optionally specify supported file extensions.

```http
POST /select-documents HTTP/1.1
Host: cde.example.com
Content-Type: application/json

{
  "callback": {
    "url": "http://localhost:8080/cde-callback-example",
    "expires_in": 3600
  },
  "server_context": null,
  "supported_file_extensions": [".ifc", ".ifczip"]
}
```

--------------------------------

### Client Requests Upload Instructions

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

Send a POST request with file size information to obtain signed upload URLs and endpoints for completion/cancellation. Ensure the 'files' array contains 'session_file_id' and 'size_in_bytes'.

```http
POST /server-provided-path-upload-documents-url HTTP/1.1
Host: cde.example.com
Content-Type: application/json

{
  "files": [
    {
      "session_file_id": "file-001",
      "size_in_bytes": 5242880
    },
    {
      "session_file_id": "file-002",
      "size_in_bytes": 10485760
    }
  ]
}
```

```json
{
  "server_context": "711c0744-0a92-489f-8ca1-13813aa2dee7",
  "documents_to_upload": [
    {
      "session_file_id": "file-001",
      "upload_file_parts": [
        {
          "url": "https://storage.example.com/upload?part=1&token=abc",
          "http_method": "PUT",
          "content_range_start": 0,
          "content_range_end": 5242879,
          "include_authorization": false
        }
      ],
      "upload_completion": {
        "url": "https://cde.example.com/upload/complete/abc123"
      },
      "upload_cancellation": {
        "url": "https://cde.example.com/upload/cancel/abc123"
      }
    },
    {
      "session_file_id": "file-002",
      "upload_file_parts": [
        {
          "url": "https://storage.example.com/upload?part=1&token=def",
          "http_method": "PUT",
          "content_range_start": 0,
          "content_range_end": 5242879,
          "include_authorization": false
        },
        {
          "url": "https://storage.example.com/upload?part=2&token=def",
          "http_method": "PUT",
          "content_range_start": 5242880,
          "content_range_end": 10485759,
          "include_authorization": false
        }
      ],
      "upload_completion": {
        "url": "https://cde.example.com/upload/complete/def456"
      },
      "upload_cancellation": {
        "url": "https://cde.example.com/upload/cancel/def456"
      }
    }
  ]
}
```

--------------------------------

### DocumentVersions

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/types.md

Represents a container for all versions of a single document. It is used in the response from GET /server-provided-path-document-versions.

```APIDOC
## DocumentVersions

### Description
Container for all versions of a single document.

### Response Body Example
```json
{
  "documents": [
    {...DocumentVersion...},
    {...DocumentVersion...},
    {...DocumentVersion...}
  ]
}
```

### Fields
- **documents** (array of [DocumentVersion](#documentversion)) - Required - All versions of the document, ordered by version_index.
```

--------------------------------

### Client Queries Upload Instructions

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

The client sends a POST request to the server-provided upload_documents_url to receive instructions for uploading files. This includes details for each file part, such as the URL, HTTP method, headers, and multipart form data.

```APIDOC
## POST /upload-instructions

### Description
Requests instructions for uploading files to the CDE.

### Method
POST

### Endpoint
`https://cde.example.com/upload-instructions?upload_session={upload_session_id}`

### Parameters
#### Query Parameters
- **upload_session** (string) - Required - The ID of the upload session.

#### Request Body
- **files** (array) - Required - A list of files to upload.
  - **size_in_bytes** (string) - Required - The size of the file in bytes.
  - **session_file_id** (string) - Required - The unique identifier for the file within the session.

### Request Example
```json
{
  "files": [
    {
      "size_in_bytes": "1048576",
      "session_file_id": "76ec9d91-0731-4405-b3c4-9bf945f9955b"
    }
  ]
}
```

### Response
#### Success Response (200)
- **server_context** (string) - Context for the server.
- **documents_to_upload** (array) - A list of documents to be uploaded.
  - **session_file_id** (string) - The unique identifier for the file within the session.
  - **upload_file_parts** (array) - Details for uploading parts of the file.
    - **url** (string) - The URL to upload the file part to.
    - **http_method** (string) - The HTTP method to use for the upload (e.g., PUT).
    - **additional_headers** (object) - Additional headers required for the upload.
      - **values** (array) - List of header name-value pairs.
        - **name** (string) - The header name.
        - **value** (string) - The header value.
    - **multipart_form_data** (object) - Data for multipart form uploads.
      - **prefix** (string) - The prefix for the multipart form data.
      - **suffix** (string) - The suffix for the multipart form data.
    - **include_authorization** (boolean) - Whether to include authorization headers.
    - **content_range_start** (integer) - The start of the content range for the upload.
    - **content_range_end** (integer) - The end of the content range for the upload.
  - **upload_completion** (object) - Information about completing the upload.
    - **url** (string) - The URL to notify about upload completion.
  - **upload_cancellation** (object) - Information about cancelling the upload.
    - **url** (string) - The URL to notify about upload cancellation.

### Response Example
```json
{
  "server_context": "ee56b8f3-8f93-4819-976e-46a45a5a996f",
  "documents_to_upload": [
    {
      "session_file_id": "76ec9d91-0731-4405-b3c4-9bf945f9955b",
      "upload_file_parts": [
        {
          "url": "https://cde-storage.example.com/8d9f94b5-125c-4f88-afbb-494bd9cd3356",
          "http_method": "PUT",
          "additional_headers": {
            "values": [
              {
                "name": "Content-Length",
                "value": "524288"
              }
            ]
          },
          "multipart_form_data": {
            "prefix": "U0VSVkVSX1NUQVJU",
            "suffix": "U0VSVkVSX0VORA=="
          },
          "include_authorization": false,
          "content_range_start": 0,
          "content_range_end": 524287
        },
        {
          "url": "https://cde-storage.example.com/2271db11-e24b-4b8c-9622-3ed63dc38e48",
          "http_method": "PUT",
          "additional_headers": {
            "values": [
              {
                "name": "Content-Length",
                "value": "524310"
              }
            ]
          },
          "multipart_form_data": {
            "prefix": "U0VSVkVSX1NUQVJU",
            "suffix": "U0VSVkVSX0VORA=="
          },
          "include_authorization": false,
          "content_range_start": 524288,
          "content_range_end": 1048575
        }
      ],
      "upload_completion": {
        "url": "https://cde.example.com/upload-completion?upload_session=ee56b8f3-8f93-4819-976e-46a45a5a996f"
      },
      "upload_cancellation": {
        "url": "https://cde.example.com/upload-cancellation?upload_session=ee56b8f3-8f93-4819-976e-46a45a5a996f"
      }
    }
  ]
}
```
```

--------------------------------

### DocumentVersions Object Structure

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/types.md

Represents a collection of all versions for a specific document. It is returned by the GET /server-provided-path-document-versions endpoint.

```json
{
  "documents": [
    {...DocumentVersion...},
    {...DocumentVersion...},
    {...DocumentVersion...}
  ]
}
```

--------------------------------

### Initiate Document Selection

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/Diagrams/Document_Download.txt

The client application initiates the document selection process by sending a POST request to the /select-documents endpoint. This request includes a callback URL and an expiration time for the selection process.

```json
{
  "callback": {
    "url": "http://<local_callback_url>",
    "expires_in": 3600
  }
}
```

--------------------------------

### DocumentMetadata Object Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/types.md

Represents a container for document metadata entries. This object is typically retrieved via a document_version_metadata link.

```json
{
  "metadata": [
    {
      "name": "Author",
      "value": ["John Doe"],
      "data_type": "string"
    },
    {
      "name": "CreationDate",
      "value": ["2024-01-15"],
      "data_type": "date"
    },
    {
      "name": "IsApproved",
      "value": ["true"],
      "data_type": "boolean"
    }
  ]
}
```

--------------------------------

### Upload a File using Python

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/QUICK-START.md

Initiates an upload process, prompts the user to enter metadata, and then uploads the file in parts. Requires the 'requests' and 'os' libraries.

```python
import requests
import os

# 1. Initiate upload
response = requests.post('https://cde.com/upload-documents', json={
    'callback': {'url': 'http://localhost:8080/callback', 'expires_in': 3600},
    'files': [
        {'file_name': 'model.ifc', 'session_file_id': 'file-1'}
    ]
})
upload_ui_url = response.json()['upload_ui_url']

# 2. User opens ui_url in browser, enters metadata
# 3. Browser redirects to callback with upload_documents_url parameter

# 4. Get upload instructions
file_size = os.path.getsize('model.ifc')
instructions = requests.post('https://cde.com/server-provided-path-upload-documents-url', json={
    'files': [{'session_file_id': 'file-1', 'size_in_bytes': file_size}]
}).json()

# 5. Upload file parts
doc_upload = instructions['documents_to_upload'][0]
with open('model.ifc', 'rb') as f:
    for part in doc_upload['upload_file_parts']:
        start = part['content_range_start']
        end = part['content_range_end']
        
        f.seek(start)
        content = f.read(end - start + 1)
        
        requests.request(
            part['http_method'],
            part['url'],
            data=content
        )

# 6. Complete upload
result = requests.post(doc_upload['upload_completion']['url'])
document_id = result.json()['document_id']
```

--------------------------------

### JSON Response Body Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/MANIFEST.txt

A sample JSON object representing a response body. This format is used for receiving data from the API.

```json
{
  "status": "success",
  "data": {
    "id": "abc-123"
  }
}
```

--------------------------------

### JSON Request Body Example

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/MANIFEST.txt

A sample JSON object representing a request body. This format is used for sending data to the API.

```json
{
  "key": "value",
  "number": 123
}
```

--------------------------------

### Initiate Document Upload Request

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

Send a POST request to initiate the document upload process. This request includes callback information and a list of files to be uploaded, each with a name and a client-generated ID.

```json
POST /upload-documents HTTP/1.1
Host: cde.example.com
Content-Type: application/json

{
  "callback": {
    "url": "http://localhost:8080/cde-callback-example",
    "expires_in": 3600
  },
  "server_context": null,
  "files": [
    {
      "file_name": "ProjectModel.ifc",
      "session_file_id": "file-001"
    },
    {
      "file_name": "ProjectModel_v2.ifc",
      "session_file_id": "file-002",
      "document_id": "doc-12345"
    }
  ]
}
```

--------------------------------

### GET /server-provided-path-selected-documents-url

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/endpoints.md

Retrieves the documents selected by the user in the CDE UI. The URL is provided by the CDE as a query parameter in the callback redirect.

```APIDOC
## GET /server-provided-path-selected-documents-url

### Description
Retrieves the documents selected by the user in the CDE UI. The URL is provided by the CDE as a query parameter in the callback redirect.

### Method
GET

### Endpoint
/server-provided-path-selected-documents-url (server-provided, dynamic)

### Response
#### Success Response (200)
- **server_context** (string or null) - CDE-controlled context identifier from the user's session on the CDE
- **documents** (array of [DocumentVersion](#documentversion)) - Array of documents selected by the user

### Response Example
```json
{
  "server_context": "project-123",
  "documents": [
    {
      "document_version_id": "doc-v1",
      "name": "Example Document.ifc",
      "size": 1024000,
      "created_at": "2023-01-01T10:00:00Z",
      "modified_at": "2023-01-01T10:00:00Z",
      "links": {
        "document_version_download": "https://cde.example.com/download/doc-v1",
        "document_version_metadata": "https://cde.example.com/metadata/doc-v1",
        "document_versions": "https://cde.example.com/versions/doc-v1"
      }
    }
  ]
}
```
```

--------------------------------

### Request Document Versions from CDE

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

Use this GET request to fetch user-selected documents from the CDE after a callback. The session ID is required for authentication.

```http
GET https://cde.example.com/download-instructions?session_id=b59dab23-79a4-4e66-a1a7-8837871604fa
```

--------------------------------

### Initiate Document Download Request

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

Client sends a POST request to the CDE's /select-documents endpoint to initiate a document download. Includes callback URL, expiration, and supported file extensions.

```json
POST /select-documents
Body:
{
  "server_context": "711c0744-0a92-489f-8ca1-13813aa2dee7",
  "callback": {
    "url": "http://localhost:8080/cde-callback-example",
    "expires_in": 3600
  },
  "supported_file_extensions": [
    ".ifc",
    ".ifczip"
  ]
}
```

--------------------------------

### Download a File using Python

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/QUICK-START.md

Initiates a document selection process, prompts the user to select files, and then downloads the selected documents. Requires the 'requests' library.

```python
import requests
from json import loads

# 1. Initiate selection
response = requests.post('https://cde.com/select-documents', json={
    'callback': {
        'url': 'http://localhost:8080/callback',
        'expires_in': 3600
    }
})
ui_url = response.json()['select_documents_url']

# 2. User opens ui_url in browser, selects documents
# 3. Browser redirects to callback with selected_documents_url parameter

# 4. Query selections
selections_response = requests.get('https://cde.com/server-provided-path-selected-documents-url')
documents = selections_response.json()['documents']

# 5. Download each document
for doc in documents:
    download_url = doc['links']['document_version_download']['url']
    file_response = requests.get(download_url)
    
    # Save file
    with open(doc['file_description']['name'], 'wb') as f:
        f.write(file_response.content)
```

--------------------------------

### Download Document Binary

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/Diagrams/Document_Download.txt

The client application downloads the binary content of a specific document version by making a GET request to the document_version_download URL.

```APIDOC
## GET https://<document_version_download_url>

### Description
Downloads the binary content of a specific document version.

### Method
GET

### Endpoint
https://<document_version_download_url>

### Response
#### Success Response (200)
- **Body**: Binary file content.

#### Response Example
(Binary file content)

### Redirect Handling
If the response status code is 303 (See Other), the client should follow the redirect without the 'Authorization' header.
```

--------------------------------

### Initiate Document Upload

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/Diagrams/Document_Upload.txt

The client application initiates the document upload process by sending a POST request to the /upload-documents endpoint. This request includes callback information and details about the files to be uploaded.

```APIDOC
## POST /upload-documents

### Description
Initiates the document upload process, providing callback details and file information.

### Method
POST

### Endpoint
/upload-documents

### Parameters
#### Request Body
- **callback** (object) - Required - Callback information including URL and expiration time.
  - **url** (string) - Required - The local callback URL to trigger upon upload completion.
  - **expires_in** (integer) - Required - The expiration time for the callback in seconds.
- **files** (array) - Required - A list of files to be uploaded.
  - **file_name** (string) - Required - The name of the file.
  - **session_file_id** (string) - Required - A unique identifier for the file session.

### Response
#### Success Response (200)
- **upload_ui_url** (string) - The URL for the upload UI.
- **expires_in** (integer) - The expiration time for the upload UI URL in seconds.
- **max_size_in_bytes** (integer) - The maximum allowed file size in bytes.

### Request Example
{
  "callback": {
    "url": "http://<local_callback_url>",
    "expires_in": 3600
  },
  "files": [
    {
      "file_name": "model.ifc",
      "session_file_id": "76ec9d91-0731-4405-b3c4-9bf945f9955b"
    }
  ]
}

### Response Example
{
  "upload_ui_url": "https://<upload_ui_url>",
  "expires_in": 60,
  "max_size_in_bytes": 1073741824
}
```

--------------------------------

### Document Upload Initialization

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/endpoints.md

Initiates the document upload workflow by providing a callback URL and file details. Returns a URL for the user to enter metadata.

```APIDOC
## POST /upload-documents

### Description
Initiates the document upload workflow. The client sends this request to start the process of uploading documents with metadata entry by the user.

### Method
POST

### Endpoint
/upload-documents

### Parameters
#### Request Body
- **callback** (CallbackLink) - Required - Callback URL configuration for the CDE to redirect the user back to the client
- **server_context** (string or null) - Optional - CDE-controlled identifier recording the user's context (e.g., project/folder)
- **files** (array of FileToUpload) - Required - List of files to upload

### Response
#### Success Response (200)
- **upload_ui_url** (string) - A CDE UI URL for the client to open in a browser where the user enters document metadata
- **expires_in** (integer (int32)) - `upload_ui_url` expiry time in seconds
- **max_size_in_bytes** (integer (int64)) - Maximum file size the CDE accepts. Larger files will fail
```

--------------------------------

### Binary File Upload Part Instructions

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

This JSON object details how to upload a specific part of a binary file, including the URL, HTTP method, headers, and multipart form data.

```json
{
  "url": "https://cde-storage.example.com/8d9f94b5-125c-4f88-afbb-494bd9cd3356",
  "http_method": "PUT",
  "additional_headers": {
    "values": [
      {
        "name": "Content-Length",
        "value": "524310"
      }
    ]
  },
  "multipart_form_data": {
    "prefix": "U0VSVkVSX1NUQVJU",
    "suffix": "U0VSVkVSX0VORA=="
  },
  "include_authorization": false,
  "content_range_start": 0,
  "content_range_end": 524287
}
```

--------------------------------

### Client Queries Selected Documents

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

After receiving the `selected_documents_url` from the callback, the client makes a GET request to this URL to retrieve the list of selected documents and their details.

```http
GET /server-provided-path-selected-documents-url HTTP/1.1
Host: cde.example.com
```

--------------------------------

### Bulk Download Multiple Versions

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

Iterate through a list of document versions, extract download URLs and document IDs, and save the binary content locally. This is useful for retrieving multiple specific versions of documents.

```pseudocode
For each DocumentVersion in response:
  1. Extract document_version_download URL
  2. Extract document_id
  3. GET binary content from document_version_download
  4. Save with document_id in filename for tracking
```

--------------------------------

### Initiate Document Selection

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/Diagrams/Document_Download.txt

The client application initiates the document selection process by sending a POST request to the /select-documents endpoint. This request includes a callback URL and an expiration time for the selection process.

```APIDOC
## POST /select-documents

### Description
Initiates the document selection process and provides a URL for the user to select documents.

### Method
POST

### Endpoint
/select-documents

### Request Body
- **callback** (object) - Required - Contains the callback URL and expiration time.
  - **url** (string) - Required - The URL to be called back once documents are selected.
  - **expires_in** (integer) - Required - The time in seconds until the callback expires.

### Request Example
{
  "callback": {
    "url": "http://<local_callback_url>",
    "expires_in": 3600
  }
}

### Response
#### Success Response (200)
- **select_documents_url** (string) - The URL for the browser to navigate to for document selection.
- **expires_in** (integer) - The time in seconds until the select_documents_url expires.

#### Response Example
{
  "select_documents_url": "https://<select_documents_url>",
  "expires_in": 60
}
```

--------------------------------

### Complete Download Flow Diagram

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/REFERENCE.md

A data flow diagram illustrating the complete client-server interaction for downloading selected documents, from initiation to binary file content retrieval.

```text
┌──────────┐                                    ┌─────────┐
│  Client  │                                    │   CDE   │
└──────────┘                                    └─────────┘
     │                                               │
     │─── POST /select-documents ────────────────→  │
     │                                               │
     │  ← DocumentDiscoverySessionInitialization ──│
     │                                               │
     │  (Client opens URL in browser)
     │  (User selects documents in CDE UI)
     │                                               │
     │ ← Browser redirect: ?selected_documents_url │
     │                                               │
     │─── GET /selected-documents-url ────────────→ │
     │                                               │
     │  ← SelectedDocuments (array of versions) ──│
     │                                               │
     │─── GET /document-download ─────────────────→ │
     │                                               │
     │  ← Binary file content ────────────────────│
     │                                               │
     │─── [Optional] GET /document-metadata ──────→ │
     │                                               │
     │  ← DocumentMetadata ────────────────────────│
     │
    [Done]
```

--------------------------------

### Request Upload Instructions

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/workflow-guide.md

The client sends a POST request with file size information to obtain signed URLs for uploading file parts. The server validates sizes, calculates part boundaries, and generates upload URLs.

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

### Description
Requests instructions for uploading files, including signed URLs for individual file parts.

### Method
POST

### Endpoint
/server-provided-path-upload-documents-url

### Request Body
- **files** (array) - Required - An array of file objects to be uploaded.
  - **session_file_id** (string) - Required - Unique identifier for the file within the session.
  - **size_in_bytes** (integer) - Required - The total size of the file in bytes.

### Request Example
```json
{
  "files": [
    {
      "session_file_id": "file-001",
      "size_in_bytes": 5242880
    },
    {
      "session_file_id": "file-002",
      "size_in_bytes": 10485760
    }
  ]
}
```

### Response
#### Success Response (200)
- **server_context** (string) - A server-side context identifier for the upload session.
- **documents_to_upload** (array) - An array of objects, each detailing how to upload a specific file.
  - **session_file_id** (string) - The identifier for the file.
  - **upload_file_parts** (array) - An array of objects, each representing a part of the file to be uploaded.
    - **url** (string) - The URL to upload the file part to.
    - **http_method** (string) - The HTTP method to use for uploading the part (e.g., PUT).
    - **content_range_start** (integer) - The starting byte index for this part.
    - **content_range_end** (integer) - The ending byte index for this part.
    - **include_authorization** (boolean) - Whether authorization headers are required for this part.
  - **upload_completion** (object) - Information for completing the upload of the file.
    - **url** (string) - The URL to signal upload completion.
  - **upload_cancellation** (object) - Information for cancelling the upload of the file.
    - **url** (string) - The URL to signal upload cancellation.

#### Response Example
```json
{
  "server_context": "711c0744-0a92-489f-8ca1-13813aa2dee7",
  "documents_to_upload": [
    {
      "session_file_id": "file-001",
      "upload_file_parts": [
        {
          "url": "https://storage.example.com/upload?part=1&token=abc",
          "http_method": "PUT",
          "content_range_start": 0,
          "content_range_end": 5242879,
          "include_authorization": false
        }
      ],
      "upload_completion": {
        "url": "https://cde.example.com/upload/complete/abc123"
      },
      "upload_cancellation": {
        "url": "https://cde.example.com/upload/cancel/abc123"
      }
    },
    {
      "session_file_id": "file-002",
      "upload_file_parts": [
        {
          "url": "https://storage.example.com/upload?part=1&token=def",
          "http_method": "PUT",
          "content_range_start": 0,
          "content_range_end": 5242879,
          "include_authorization": false
        },
        {
          "url": "https://storage.example.com/upload?part=2&token=def",
          "http_method": "PUT",
          "content_range_start": 5242880,
          "content_range_end": 10485759,
          "include_authorization": false
        }
      ],
      "upload_completion": {
        "url": "https://cde.example.com/upload/complete/def456"
      },
      "upload_cancellation": {
        "url": "https://cde.example.com/upload/cancel/def456"
      }
    }
  ]
}
```
```

--------------------------------

### Client Queries Document Versions

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

After receiving a callback from the CDE UI, the client sends a request to get the user-selected documents from the CDE. The response includes document metadata and links for further actions.

```APIDOC
## GET /download-instructions

### Description
Retrieves a list of selected document versions from the CDE based on a session ID.

### Method
GET

### Endpoint
https://cde.example.com/download-instructions

### Query Parameters
- **session_id** (string) - Required - The session ID obtained from the CDE UI callback.

### Response
#### Success Response (200)
- **server_context** (string) - Optional - A context string for future sessions.
- **documents** (array) - A list of document versions.
  - **links** (object) - Contains URLs for related resources.
    - **document_version** (object) - URL to the document version object.
    - **document_version_metadata** (object) - URL to the document version metadata.
    - **document_version_download** (object) - URL to download the document version content.
    - **document_versions** (object) - URL to a list of all versions for the parent document.
    - **document_details** (object) - Optional URL to view the document version in the CDE UI.
  - **version_number** (string) - The version number of the document.
  - **version_index** (integer) - The index of the document version.
  - **creation_date** (string) - The date and time the document version was created.
  - **title** (string) - The title of the document.
  - **file_description** (object) - Information about the document file.
    - **name** (string) - The name of the file.
    - **size_in_bytes** (integer) - The size of the file in bytes.
  - **document_id** (string) - The unique identifier for the document.

### Response Example
```json
{
  "server_context": "5a0b9c95-481c-4eb0-b564-0d04837c669d",
  "documents": [
    {
      "links": {
        "document_version": {
          "url": "https://cde.example.com/documents/bf546064-6b97-4730-a094-c21ab929c91a/versions/v3.0"
        },
        "document_version_metadata": {
          "url": "https://cde.example.com/documents/bf546064-6b97-4730-a094-c21ab929c91a/versions/v3.0/metadata"
        },
        "document_version_download": {
          "url": "https://cde.example.com/documents/bf546064-6b97-4730-a094-c21ab929c91a/versions/v3.0/download"
        },
        "document_versions": {
          "url": "https://cde.example.com/documents/bf546064-6b97-4730-a094-c21ab929c91a/versions"
        },
        "document_details": {
          "url": "https://cde.example.com/ui/projects/12485/documents/bf546064-6b97-4730-a094-c21ab929c91a/v3.0"
        }
      },
      "version_number": "v3.0",
      "version_index": 3,
      "creation_date": "2022-03-09T08:02:53.866Z",
      "title": "Sample Document",
      "file_description": {
        "name": "model.ifc",
        "size_in_bytes": 1048576
      },
      "document_id": "bf546064-6b97-4730-a094-c21ab929c91a"
    }
  ]
}
```
```

--------------------------------

### Download Document Binary Data

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/Diagrams/Document_Download.txt

The client application downloads the actual binary content of a specific document version by making a GET request to the document_version_download URL obtained in the previous step.

```http
GET https://<document_version_download_url>
```

--------------------------------

### Callback Server Minimal Implementation

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/implementation-notes.md

A minimal implementation for a callback server endpoint that handles responses from selection operations. It extracts query parameters to determine the next step or identify cancellation.

```http
GET /cde-callback
  ?selected_documents_url=/path1
  OR ?user_cancelled_selection=true
```

--------------------------------

### Retrieve Selected Documents

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/Diagrams/Document_Download.txt

After the user selects documents in the browser UI and the client's local callback URL is triggered, the client application makes a GET request to the server-provided URL to retrieve the list of selected documents.

```APIDOC
## GET https://<server_selected_docs_url>

### Description
Retrieves the list of documents selected by the user.

### Method
GET

### Endpoint
https://<server_selected_docs_url>

### Response
#### Success Response (200)
- **server_context** (string) - A server context identifier.
- **documents** (array) - A list of selected documents.
  - **links** (object) - Links related to the document version.
    - **document_version** (object) - Link to the document version.
      - **url** (string) - URL for the document version.
    - **document_version_metadata** (object) - Link to the document version metadata.
      - **url** (string) - URL for the document version metadata.
    - **document_version_download** (object) - Link to download the document version.
      - **url** (string) - URL for downloading the document version.
    - **document_versions** (object) - Link to all document versions.
      - **url** (string) - URL for document versions.
    - **document_details** (object) - Link to document details.
      - **url** (string) - URL for document details.
  - **version_number** (string) - The version number of the document.
  - **version_index** (integer) - The index of the document version.
  - **creation_date** (string) - The creation date of the document version.
  - **title** (string) - The title of the document.
  - **file_description** (object) - Description of the file.
    - **name** (string) - The name of the file.
    - **size_in_bytes** (integer) - The size of the file in bytes.
  - **document_id** (string) - The unique identifier for the document.

#### Response Example
{
  "server_context": "<server_context>",
  "documents": [
    {
      "links": {
        "document_version": {
          "url": "https://<document_version_url>"
        },
        "document_version_metadata": {
          "url": "https://<document_version_metadata_url>"
        },
        "document_version_download": {
          "url": "https://<document_version_download_url>"
        },
        "document_versions": {
          "url": "https://<document_versions_url>"
        },
        "document_details": {
          "url": "https://<document_details_url>"
        }
      },
      "version_number": "v3.0",
      "version_index": 3,
      "creation_date": "2022-02-14T08:02:53.866Z",
      "title": "Sample Document",
      "file_description": {
        "name": "sample.pdf",
        "size_in_bytes": 286142
      },
      "document_id": "bf546064-6b97-4730-a094-c21ab929c91a"
    }
  ]
}
```

--------------------------------

### Initiate Document Upload

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/README.md

Client initiates document upload by sending a POST request to the CDE's /upload-documents endpoint. Includes callback URL, session ID, and file name.

```json
POST /upload-documents
Body:
{
  "server_context": "7188a2be-6c4e-4e3b-b7e7-cd27f0d4ad67",
  "callback": {
    "url": "http://localhost:8080/cde-callback-example",
    "expires_in": 3600
  },
  "files": [
    {
      "file_name": "model.ifc",
      "session_file_id": "76ec9d91-0731-4405-b3c4-9bf945f9955b"
    }
  ]
}
```

--------------------------------

### Download Selection and Retrieval

Source: https://github.com/buildingsmart/documents-api/blob/release_1_0/_autodocs/REFERENCE.md

Initiate document selection, retrieve a discovery session, allow user selection via a UI, and then download the selected documents.

```APIDOC
## Download Selection and Retrieval

### Description
Initiates a document selection process, returning a UI URL for user interaction. After the user selects documents, the client can query for the selected documents and then download them.

### Method
POST

### Endpoint
/select-documents

### Request Body
(Not specified in source)

### Response
#### Success Response (200)
- **DocumentDiscoverySessionInitialization** (object) - Contains a UI URL for document selection.

### Method
GET

### Endpoint
/server-provided-path-selected-documents-url

### Request Body
(Not specified in source)

### Response
#### Success Response (200)
- **SelectedDocuments** (object) - Contains a list of selected document versions.

### Method
GET

### Endpoint
/server-provided-path-document-download

### Request Body
(Not specified in source)

### Response
#### Success Response (200)
- **Binary file content** (application/octet-stream) - The content of the requested document.
```