Skip to main content

Create asset

POST 
/asset.create

Creates a file Asset and returns instructions for uploading its bytes directly to the resumable-uploads service. Unlike item.upload, the file bytes never pass through the API itself, so this endpoint supports much larger files (up to 5 GiB).

Upload Flow​

  1. Call this endpoint with the file's name (and optionally its size in bytes).
  2. Upload the raw file bytes in a single request: replay uploadMethod against uploadUrl, send every entry of uploadHeaders, and put the file in the request body.
  3. Processing starts automatically once the bytes land — there is no separate "complete" call.
  4. Reference the assetId:
    • purpose: "file" (default) — attach to a chat message via chat.post's assetIds field.
    • purpose: "story" — post as a story via story.post.

A freshly-uploaded asset may take a few seconds to process (videos take longer). Endpoints that consume the asset return a 400 with a "still processing" message until processing completes.

Purposes​

PurposeUseAccess
file (default)Chat message attachmentsOrganization and Personal
storyStory media (photo or video)Personal only

Story assets are owned by the authenticated user (stories are posted as you, not as a bot) and expire about 48 hours after creation. Because the media must outlive the story's 24-hour lifetime, call story.post within about 23 hours of creating the asset; after that the asset is rejected and a new one must be created.

Access: Organization and Personal. purpose: "story" is Personal only.

Required scope: item:write (for purpose: "file"), chat:send_message or chat:write (for purpose: "story")

OpenAPI Spec: openapi.json

Request​

Responses​

Upload instructions for the created asset.