> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/tools/assets.md).

# Asset tools

Reference for the FLORA MCP tools that upload files by URL or signed upload, finish uploads, and place assets on a canvas.

These [FLORA MCP](https://flora.ai/mcp) tools bring your own images, video, audio and PDFs into a workspace and onto a canvas. Pass a public HTTPS URL and FLORA fetches it, or pass `source: "signed-url"` for a local file, upload it, and finish with [`flora_complete_asset`](#flora_complete_asset). Never send file bytes as base64.

For all three upload paths step by step, see [Upload your own images, video and files](https://docs.flora.ai/mcp/recipes/upload-files.md).

| Tool                                            | What it does                                                                                                    | Labels    |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------- |
| [`flora_create_asset`](#flora_create_asset)     | Bring files into a workspace from a public URL, or reserve a signed upload for a local file. Up to 25 per call. | writes    |
| [`flora_complete_asset`](#flora_complete_asset) | Finish a signed-url upload once the file's bytes are uploaded, or finish up to 25 at once.                      | writes    |
| [`flora_attach_asset`](#flora_attach_asset)     | Place an existing asset on a project canvas as a node.                                                          | writes    |
| [`flora_get_asset`](#flora_get_asset)           | Read one asset's metadata, or turn up to 100 asset IDs into URLs in one call.                                   | read-only |
| [`flora_list_assets`](#flora_list_assets)       | List the assets in a workspace or project, with an optional name filter.                                        | read-only |

## flora\_create\_asset <a href="#flora_create_asset" id="flora_create_asset"></a>

Bring files into a workspace from a public URL, or reserve a signed upload for a local file. Up to 25 per call.

**Labels:** writes

**Shown in clients as:** Create asset

**Use when:** The user has a file to use in FLORA: a public HTTPS URL, a file they shared in Claude or ChatGPT (already hosted, so pass its URL), or a file on their machine.

**Don't use when:** You'd send the bytes as base64, or retry a URL that returned `401`, `403` or `404`: use `source: "signed-url"` instead. SVG isn't accepted; convert it to PNG first.

**Arguments**

| Argument                 | Type            | Required | Notes                                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`           | string          | yes      | Workspace to own the asset (ws\_…).                                                                                                                                                                                                                                                                                                   |
| `source`                 | string          | no       | An HTTPS URL that serves the media bytes directly — an HTML page or player that merely displays them is rejected, and the content type is read from the response or the URL's file extension — or the literal "signed-url" to reserve an upload slot. If an anonymous fetch returns HTTP 401/403/404, do not retry; use "signed-url". |
| `project_id`             | string          | no       | Attach the asset to this project canvas (prj\_…). The project must belong to the workspace named by workspace\_id. Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>.                                                                       |
| `file_name`              | string          | no       | File name, required for signed-url uploads.                                                                                                                                                                                                                                                                                           |
| `content_type`           | string          | no       | MIME type, required for signed-url uploads. Must be one of the allowed types in the tool description.                                                                                                                                                                                                                                 |
| `size_bytes`             | integer         | no       | Exact file size in bytes; required for signed GLB uploads. Minimum 1.                                                                                                                                                                                                                                                                 |
| `folder`                 | string          | no       | Destination folder. With sources, this is the default for entries that do not set their own.                                                                                                                                                                                                                                          |
| `sources`                | array of object | no       | Batch upload: up to 25 entries, each an object with a source (an HTTPS URL or "signed-url"); file\_name and content\_type are required on "signed-url" entries, size\_bytes is required for GLB signed uploads, folder optional. Pass this OR the top-level source, not both. Up to 25 items.                                         |
| `sources[].source`       | string          | yes      | An HTTPS URL FLORA fetches, or the literal "signed-url".                                                                                                                                                                                                                                                                              |
| `sources[].file_name`    | string          | no       | File name, required for "signed-url" entries.                                                                                                                                                                                                                                                                                         |
| `sources[].content_type` | string          | no       | MIME type, required for "signed-url" entries. Must be one of the allowed types in the tool description.                                                                                                                                                                                                                               |
| `sources[].size_bytes`   | integer         | no       | Exact file size in bytes; required for signed GLB uploads. Minimum 1.                                                                                                                                                                                                                                                                 |
| `sources[].folder`       | string          | no       | Destination folder for this entry only.                                                                                                                                                                                                                                                                                               |

**Returns:** Each asset's `asset_id` (`asset_…`). A `signed-url` entry also gets an `upload_page` link (valid 15 minutes) to give the user and an `upload` descriptor for clients with a shell. With `sources`, `{assets}` has one entry per file, and a failed entry never stops the rest.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_workspaces`](https://docs.flora.ai/mcp/tools/workspaces-and-projects.md#flora_list_workspaces)

**Usually comes before:** [`flora_complete_asset`](#flora_complete_asset), [`flora_attach_asset`](#flora_attach_asset)

**Example prompt:** "Upload this product photo and my logo file to the Spring campaign project."

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "project_id": "prj_abc",
  "sources": [
    {
      "source": "https://example.com/product.jpg"
    },
    {
      "source": "signed-url",
      "file_name": "logo.png",
      "content_type": "image/png"
    }
  ]
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Bring a file into a workspace. To bring in several files in one call, pass sources instead of source: an array of up to 25 entries, each {source, file_name, content_type, size_bytes, folder}, returning {assets} where every entry echoes its index and source and carries either the create response (an asset_… asset_id, and for "signed-url" entries its own upload descriptor and upload_page link) or {ok:false, error} — one failed entry never stops the rest. Prefer one sources call over several calls in parallel: every call counts against the workspace's shared API rate limit, and a sources call reserves all its signed-url entries in one request. workspace_id, project_id and folder apply to every entry. Pass source as a public HTTPS URL and FLORA fetches it server-side. Hosts that return 401/403/404 to FLORA's anonymous fetch (for example, hotlink-protected or login-gated hosts) must not be retried; download the file and use source="signed-url" instead. Pass source="signed-url" for a file that exists only on the user's machine: the response carries an upload_page link for the user to open in a browser, and an upload descriptor for clients with a shell. Follow upload.method and upload.headers: POST descriptors use the multipart form fields verbatim with file bytes last; PUT descriptors send the raw file bytes to upload.url. GLB uploads (model/gltf-binary) require project_id. For a signed-url GLB, also provide size_bytes equal to the local file size; URL uploads are measured from the fetched bytes. Do not hardcode endpoints or fields; they depend on the storage backend. Bytes upload only through the descriptor or upload_page — never from a code sandbox, which has no outbound network. Either way, finish the asset with flora_complete_asset (asset_ids finishes a sources batch in one call); if it reports the bytes missing after the user submitted or the link expired, call flora_create_asset again for a fresh reservation rather than reusing the old link. Only these content types upload: image/jpeg, image/png, image/webp, image/gif, image/avif, image/heic, image/heif, video/mp4, video/webm, video/quicktime, audio/mpeg, audio/wav, audio/ogg, audio/mp4, application/pdf, model/gltf-binary (image/jpg, audio/x-m4a and application/x-pdf normalize onto the list). Unsupported types are rejected; rasterize SVG to PNG rather than retrying it.
```

{% endcode %}

</details>

## flora\_complete\_asset <a href="#flora_complete_asset" id="flora_complete_asset"></a>

Finish a signed-url upload once the file's bytes are uploaded, or finish up to 25 at once.

**Labels:** writes

**Shown in clients as:** Complete asset upload

**Use when:** The user submitted the `upload_page` form, or your shell finished the multipart POST to `upload.url`.

**Don't use when:** The file came from a public URL that FLORA fetched. If it reports the bytes missing or the link expired, call [`flora_create_asset`](#flora_create_asset) again for a fresh reservation instead of reusing the old link.

**Arguments**

| Argument    | Type            | Required | Notes                                                                                                |
| ----------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `asset_id`  | string          | no       | Asset to finalize: the asset\_… id flora\_create\_asset returned.                                    |
| `asset_ids` | array of string | no       | Finish several signed-url assets (asset\_… ids) in one call — pass this OR asset\_id. 1 to 25 items. |

**Returns:** The asset's final URL and status. With `asset_ids`, `{assets}` with `ok` and either status `ready` or `failed` (with `failure_message`) for each entry.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_create_asset`](#flora_create_asset)

**Usually comes before:** [`flora_attach_asset`](#flora_attach_asset)

**Example prompt:** "I've uploaded the logo. Finish it."

**Example call:**

```json
{
  "asset_id": "asset_123"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Finish a signed-url asset after its bytes have been uploaded. Returns the asset's final URL. To finish several, pass asset_ids instead (up to 25) — the asset_… ids one sources call reserved — in one call. It returns {assets}: every entry echoes its index and asset_id with ok, then either status ready or failed with failure_message, as a single completion reports, or an error when that asset could not be completed. One failed entry never stops the rest.
```

{% endcode %}

</details>

## flora\_attach\_asset <a href="#flora_attach_asset" id="flora_attach_asset"></a>

Place an existing asset on a project canvas as a node.

**Labels:** writes

**Shown in clients as:** Attach asset

**Use when:** An uploaded asset should appear on a canvas. The asset must be `ready` and in the project's workspace.

**Don't use when:** The asset is still `pending_upload` or `failed`: check it with [`flora_get_asset`](#flora_get_asset) first. To place media from a URL without uploading it, use [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas) with `content_url`.

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                                |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `asset_id`   | string | yes      | Asset to place: an asset\_… id as returned by flora\_create\_asset or flora\_list\_assets, in the project's workspace.                                                               |
| `project_id` | string | yes      | Project canvas to place it on (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>. |

**Returns:** The canvas node it created. Its node ID (`api_asset_…`) works in later canvas calls such as [`flora_arrange_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_arrange_canvas).

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_complete_asset`](#flora_complete_asset), [`flora_get_asset`](#flora_get_asset)

**Usually comes before:** [`flora_arrange_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_arrange_canvas)

**Example prompt:** "Put the logo I uploaded on the Spring campaign canvas."

**Example call:**

```json
{
  "asset_id": "asset_123",
  "project_id": "prj_abc"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Put an existing asset onto a project canvas as a node. This is how an asset created by flora_create_asset becomes visible in a project. The asset must report status "ready" — attaching a pending_upload or failed asset is rejected — so after flora_create_asset / flora_complete_asset, check the returned status or poll flora_get_asset until it is ready before calling this. The asset and the project must live in the same workspace.
```

{% endcode %}

</details>

## flora\_get\_asset <a href="#flora_get_asset" id="flora_get_asset"></a>

Read one asset's metadata, or turn up to 100 asset IDs into URLs in one call.

**Labels:** read-only

**Shown in clients as:** Get asset

**Use when:** You need an asset's URL or status, or want to know why an upload failed.

**Don't use when:** You're browsing: use [`flora_list_assets`](#flora_list_assets). Pass an `asset_…` ID, never a node ID or URL.

**Arguments**

| Argument    | Type            | Required | Notes                                                                                                           |
| ----------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `asset_id`  | string          | no       | Asset to read: an asset\_… id as returned by flora\_create\_asset or flora\_list\_assets, not a node id or URL. |
| `asset_ids` | array of string | no       | Resolve several asset\_… ids to their URLs in one call — pass this OR asset\_id. 1 to 100 items.                |

**Returns:** The asset's metadata, including its status and `failure_message` when the upload didn't finish. With `asset_ids`, one entry per ID with its `url` or `not_found: true`.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_create_asset`](#flora_create_asset), [`flora_complete_asset`](#flora_complete_asset)

**Usually comes before:** [`flora_attach_asset`](#flora_attach_asset)

**Example prompt:** "Is the video I uploaded ready yet?"

**Example call:**

```json
{
  "asset_id": "asset_123"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Get one asset's metadata, including failure_message when its upload did not finish. flora_list_assets covers the rest. Pass asset_ids instead (up to 100) to resolve a batch of ids to their URLs in one call — the asset_ids a generation's inputs report — each entry echoes the id with its url or not_found:true.
```

{% endcode %}

</details>

## flora\_list\_assets <a href="#flora_list_assets" id="flora_list_assets"></a>

List the assets in a workspace or project, with an optional name filter.

**Labels:** read-only

**Shown in clients as:** List assets

**Use when:** The user wants to reuse a file they uploaded before.

**Don't use when:** You have asset IDs and need their URLs: use [`flora_get_asset`](#flora_get_asset) with `asset_ids`.

**Arguments**

| Argument       | Type   | Required | Notes                                                                                                                                                                    |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workspace_id` | string | no       | Filter by workspace (ws\_…).                                                                                                                                             |
| `project_id`   | string | no       | Filter by project (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>. |
| `query`        | string | no       | Filter by asset name.                                                                                                                                                    |
| `limit`        | number | no       | Max items to return (default 20).                                                                                                                                        |
| `cursor`       | string | no       | Pagination cursor from a previous call's meta.next\_cursor.                                                                                                              |

**Returns:** A page of assets with their IDs (`asset_…`) and URLs, and `meta.next_cursor`.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_workspaces`](https://docs.flora.ai/mcp/tools/workspaces-and-projects.md#flora_list_workspaces)

**Usually comes before:** [`flora_attach_asset`](#flora_attach_asset), [`flora_get_asset`](#flora_get_asset)

**Example prompt:** "Find the logo files I uploaded to FLORA."

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "query": "logo"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
List assets in a workspace or project.
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/tools/assets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
