---
title: "API · Assets · Create a persistent asset from a remote URL or a local file"
method: POST
path: "/api/v1/assets/from-url"
tags: ["assets"]
---

# API · Assets · Create a persistent asset from a remote URL or a local file

`POST /api/v1/assets/from-url`

## Request

- Base URL: `https://api.simplified.com`
- URL: `https://api.simplified.com/api/v1/assets/from-url`
- Auth: API key in header `Authorization`

Create a persistent workspace asset from a remote `url` the server
downloads.

To add a file from your own machine, do not call this tool — use
`signAssetUpload`, PUT the bytes to the signed URL it returns, then
`registerAsset`. (`path` exists for the `smp` command-line tool only;
it cannot work over MCP, where the file is on a different machine.)

Processing is async (download + thumbnail via Celery), usually a few
seconds. The returned UUID is usable immediately in `data.assets[]`,
but the 201 response is not the file: its `thumbnail` is empty and not
usable, and `import_state` is `pending`. Poll `getAsset` and read its
`import_state`:
- `"stored"`: `file_url` is the stored CDN file and ready to use.
- `"failed"`: the import failed; `import_error` says why (`http_<status>`,
  `timeout`, `unreachable`, `not_an_image`, `import_failed`).
- `"pending"` / `"importing"`: still importing, `file_url` is empty
  until stored. Check again on a later step; if it is still not
  stored after about a minute, treat it as failed.

Common use: persist a transient AI-generated image (from `generateImage`)
so it can be saved to a project, published, or opened in the editor.

## Request body

- union: Create a persistent workspace asset from EITHER a remote URL (server downloads it) or a local file path (toolkit uploads via a signed URL to a temporary bucket, then registers the asset). Pass exactly one of `url` or `path`.
  - unknown
  - unknown

## Response `201`

Asset created — processing asynchronously

- unknown

## Other responses

- `400`: Invalid URL or unsupported image format
- `401`: Unauthorized

---

[API](https://skmtc.dev/simplified/apis/platform.md) - [All operations](https://skmtc.dev/simplified/apis/platform/llms.txt) - [OpenAPI document](https://skmtc.dev/simplified/apis/platform/revisions/0815a1ba1e4e?raw)