> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simplified.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simplified.com/_mcp/server.

# 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

| Asset status | Meaning           |
| ------------ | ----------------- |
| `0`          | Not started       |
| `1`          | In progress       |
| `2`          | Processing failed |
| `3`          | Thumbnail failed  |
| `4`          | Done              |
| `10`         | Not processed     |

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.