Assets and uploads

A file attached to an assistant conversation is not necessarily a persistent Simplified asset. Import or upload it before using tools that require a workspace asset ID.

List or search existing assets

Call api_listAssets without a search term to list the connected workspace’s assets, newest first, or with one to find assets by name or tag. Add asset_type: 0 to return images, or asset_type: 2 for videos — that filter works with or without a search term. Use space_id to select an accessible teamspace.

Results include asset UUIDs in id; use these IDs as media when creating social drafts. Call api_getAsset for full details or fresh file URLs. Keep the same search and filters while incrementing page to retrieve additional pages; page_size requests the number of results per page.

A search term includes matching assets inside folders, but does not match folder names or retrieve all contents of a named folder. It matches text in asset names and tags, not objects visible in an image.

Import a remote file

1. Give the assistant a downloadable file URL.
2. Call api_createAsset with the URL and a useful name.
3. Save the returned asset UUID.
4. Call api_getAsset until processing finishes before relying on stored file URLs.

The server must be able to retrieve the URL. A web page, a login-only link, or a file that has already expired is not a downloadable asset.

Upload a local file

The hosted connector cannot read a path on your computer. A capable client can upload it directly:

1. Read the local file and determine its filename and MIME type.
2. Generate a resource UUID and call api_signAssetUpload with the required metadata.
3. PUT the file bytes to the returned signed URL using the declared content type. Do not send the Simplified authorization header to storage.
4. After the upload succeeds, call api_registerAsset. Carry the signing response’s registration fields unchanged and use the original filename as asset_name.
5. Keep the returned asset ID and check it with api_getAsset.

Your client needs file access and an HTTP upload capability for the byte transfer. If it lacks either, upload the file in Simplified or provide a downloadable URL instead.

Check processing

Wait for 4 before depending on finished URLs. Investigate failed states rather than polling indefinitely.

Use IDs and URLs correctly

Use the asset UUID for fields that require asset references, such as social media attachments or project item assets. Use a downloadable URL only where the destination tool asks for one.

file_url and thumbnail links can expire. Retrieve the asset again for a fresh URL instead of treating a signed link as a permanent identifier. If generation returns only a temporary image URL, import it before saving it as a reusable project asset.