Skip to main content
Upload a file, then choose whether to attach it once or save it in the Vault for reuse. Start the upload and send each part. Finalize the upload to mark it complete before creating content.

Before you start

Ask the user to authorize your app with vault:write, which lets your app upload files. Use the returned token and select a linked account the user shared. Keep the original filename and file type, such as image/png. Install the TypeScript SDK version 4. Create a client on your server:
Use this client for the rest of this guide. It sends the access token and linked account ID for API calls.

Start an upload

Call client.access.uploads.start() with the original filename, size, file type, and MD5 hash. The SDK’s md5Hex() calculates the hash from the file bytes. The example below includes all four values. The response has one of two statuses: Each part includes partNumber, uploadUrl, and byteRange.start and byteRange.end. Include the last byte in each range. Use the returned URL for each part. If creation returns already_exists, use media.id. If it returns needs_upload, PUT every returned byte range, finalize even a single-part upload, and use uploadId once. If the file already exists, use its Vault media ID without uploading bytes. Finalize every new upload, even if it has only one part. To save the file for reuse, include the Vault options when you finalize.

Upload the parts and finish

Add this code after the client setup in a TypeScript file. Run it with the PNG path as its first argument. Set ACCESS_TOKEN and LINKED_ACCOUNT_ID in your environment. For another file type, change contentType to match, such as image/jpeg. The SDK starts and finalizes the upload. The PUT requests send the file bytes to the returned upload URLs.
Send raw bytes in each PUT. Do not wrap them in JSON, base64, or multipart form data. Keep the same bearer token and linked account headers for the upload URLs. Finalization is required even for single-part uploads. POST /v3/access/uploads/finalize accepts 1 to 10 uploadIds. Without Vault options, it returns { "uploadIds": [...] }. Use the completed upload reference in mediaItems when you create content.

Keep a reusable Vault ID

To save the file in the Vault, use these finalization options in place of the finalization call above. Set uploadId to the new upload’s ID. Do not finalize the same upload twice:
Use a valid target user ID for the linked account. listId is optional. Saving an upload in the Vault uses a temporary scheduled message. Its response contains uploads, each with uploadId, mediaId, and media, plus optional listId and messageId. Save uploads[].mediaId to use the file again. Optional mediaIds can include up to 10 existing IDs when adding the finalized media to a Vault list. To upload several files, send POST /v3/access/vault/uploads. Include details for 1 to 10 files in files, along with the required vaultUpload options. Read batch status with GET /v3/access/vault/uploads/:batchId. See the API reference for each file’s status fields.

Use the result

Use completed references in posts, messages, and mass messages. Stories accept exactly one non-GIF image. A temporary upload reference works for one successful post, message, or story. You can reuse numeric Vault IDs. See Media references.

Recover from an interrupted upload

Save the start response and finish the upload before expiresAt. If a part fails, retry the same bytes at the same part URL before the upload expires. If you do not know whether a post, message, or story was created, check for it before trying again. Follow the response’s recovery instructions. At upload start, OFAuth checks the file hash and size for a matching Vault item. Use the returned parts and byte ranges for any new upload.