Uploading files with the Dock API

Creating an asset from a file is a two-step process: upload the file, then create the asset from it. Link and embed assets skip the upload entirely — create them directly with a url (or customCode).

1. Create a file and upload the bytes

Call Create a file with the file’s name and MIME type. The response contains the file id and a presigned upload target:

curl -X POST https://api.dock.us/v1/files \
  -H "Authorization: Bearer $DOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName": "sales-deck.pdf", "mimeType": "application/pdf"}'

{
  "data": {
    "file": {
      "id": "f9Ghw2n0Ju3D",
      "uploadStatus": "in_progress",
      "url": null
    },
    "upload": {
      "url": "https://storage.googleapis.com/...",
      "method": "PUT",
      "headers": { "Content-Type": "application/pdf" },
      "expiresAt": "<one hour after the file was created>"
    }
  }
}

Then PUT the raw bytes directly to upload.url with the returned Content-Type header, before expiresAt (1 hour):

curl -X PUT "<upload.url>" \
  -H "Content-Type: application/pdf" \
  --data-binary @sales-deck.pdf

The Content-Type header on the PUT request must exactly match the mimeType the file was created with, or Google Cloud Storage rejects the upload.

2. Create the asset

Call Create an asset with the file id. Dock verifies the upload completed, marks the file ready, and creates the asset — optionally tagged with existing tags:

curl -X POST https://api.dock.us/v1/assets \
  -H "Authorization: Bearer $DOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pdf",
    "name": "Sales deck",
    "fileId": "f9Ghw2n0Ju3D",
    "tagIds": ["RiHO4e0Ju3DS"]
  }'

Calling this before the bytes are uploaded returns a 400 — retry after the PUT completes. A file can back exactly one asset.

Supported asset types

`type`	Source	Notes
`pdf`	`fileId`	Page count and document metadata extracted automatically
`image`	`fileId`	Dimensions extracted automatically
`video`	`fileId`	Pass `metadata.width/height/duration` if available
`audio`	`fileId`	Pass `metadata.duration` if available
`docx`	`fileId`	Converted to PDF; returned as `microsoftWordEmbedPdf`
`ppt`	`fileId`	Converted to PDF; returned as `microsoftPowerPointEmbedPdf`
`xlsx`	`fileId`	Converted to PDF; returned as `microsoftExcelEmbedPdf`
`htmlPage`	`fileId`	Standalone HTML file rendered as a page
`link`	`url`	Link preview metadata resolved automatically
`embed`	`url` or `customCode`	Exactly one of the two

Office documents convert asynchronously

Uploaded office documents (docx, ppt, xlsx) are rendered to PDF in the background. The asset is created immediately, but its backing file reports uploadStatus: "in_progress" until conversion finishes. Poll Retrieve a file with properties[]=uploadStatus to track it.

API Reference

Clients

Workspaces

Library

General

Uploading files

1. Create a file and upload the bytes

2. Create the asset

Supported asset types

Office documents convert asynchronously

​1. Create a file and upload the bytes

​2. Create the asset

​Supported asset types

​Office documents convert asynchronously

1. Create a file and upload the bytes

2. Create the asset

Supported asset types

Office documents convert asynchronously