Skip to main content
Use connection setup for authentication and request conventions. Use a write-capable user key with access to the destination. The example uploads a local PDF named form.pdf.

​
Choose the destination

  • personal://Documents: your personal Documents folder.
  • team://Documents: the team’s Documents folder, subject to your access.
  • @mc/Documents: the Documents folder in an authorized scope. Include scope: "mc:<UUID or stable slug>".
Send scope only for @mc destinations, in the request body. For artifact:// writes, use a storage root ID plus a relative path, not an ordinary folder ID. Alternatively, provide sessionId instead of targetUri to upload to a session folder. Location and record ownership are separate. To create a record-owned document, include ownerType and ownerId on each file. For filings, use the filing destination and ownership example then continue at Upload the file.

​
Prepare the request

Initialize an upload to your team’s Documents folder. Replace 12345 with the file’s actual byte count. For a filing document, use the linked filing-specific request instead.
The response contains targetUri and files[] with path, signedUrl, optional headers, expiresAt, and uploadToken. rename preserves an existing file with the same name; it does not replace that file or its version. If you choose onConflict: "fail", inspect conflicts[]: those files are excluded from the PUT instructions.

​
Upload the file

Send the PDF bytes to files[0].signedUrl, using exactly the returned files[0].headers. The body is the raw file, not JSON or multipart form data:
Do not send the Effective bearer credential to storage. Continue only after the PUT succeeds. Complete the upload using files[0].uploadToken from initialization:
Check every results[].success, even when HTTP status is 200. A successful result contains uri and artifact (the stored file details). Save artifact.id to reference the file and artifact.name for its stored name, which may differ from the requested name. A failed result contains error.code and error.message. For example, NOT_FOUND means the uploaded file was not found; EXPIRED means the token expired. Do not use a failed upload as a file reference. The token carries the owner fields from initialization; do not resend them or scope in the completion body. Both API calls accept batches of up to 100 files and JSON bodies up to 1 MiB. File bytes go in the PUT, not the JSON. Complete before the token expires after one hour, and use the signed URL before its returned expiresAt. Neither initialization nor completion is idempotent. After a lost response, inspect the destination folder before retrying: repeating completion can create another version. Completion schedules indexing; it does not wait for searchable text. Upload completion creates or updates the stored file. It does not create application records such as filing items. To add a completed file to a filing, continue with Add a filing item. See the full initialization and completion API references for schemas.