---
title: "Import an asset from a URL (or keep it as a live link)"
method: POST
path: "/v1/vault/assets/import-url"
tags: ["Vault"]
---

# Import an asset from a URL (or keep it as a live link)

`POST /v1/vault/assets/import-url`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/vault/assets/import-url`
- Auth: HTTP bearer

Default: fetch the URL once through the SSRF-guarded seam
(scheme allowlist, host validation, redirect re-checks, byte-capped
stream) and store the exact bytes as an encrypted asset — import-and-
encrypt is the default because a live `https://` embed would re-fetch
on every view. `keepAsLiveLink: true` is the explicit per-link
alternative: the URL is only validated, nothing is fetched or stored,
and the response carries `imported: false` so the editor inserts a
visibly-marked external-link node.

## Request body

- WireVaultAssetImportUrlRequest: URL import request. Default fetches once and stores encrypted; `keepAsLiveLink: true` validates only and stores nothing.
  - `url` string, required: The http(s) URL to import (or keep as a live link).
  - `keepAsLiveLink` boolean: Validate only; the editor renders the live URL with a visible external marker.

## Response `200`

The import outcome (`asset` is null for a kept live link)

- WireVaultAssetImportUrlResponse
  - `imported` boolean, required: False when keepAsLiveLink was honored (nothing fetched or stored).
  - `asset` WireVaultAssetImportResponse, required: An imported (or dedup-matched) vault asset's identity. The id is the `sha256:<hex>` of the exact plaintext bytes (content-addressed); embed tokens serialize as `vault://asset/<id>`.
    - `id` string, required: Content id (`sha256:<hex>`) of the exact bytes.
    - `mimeType` string, required
    - `byteLength` integer, required: Exact plaintext byte count.

## Other responses

- `400`: Invalid request
- `413`: The fetched asset exceeds the per-asset size ceiling
- `423`: The vault is locked (no VMK loaded). Unlock natively in ToolPiper — there is no unlock route. The body is the standard nested error envelope with type `vault_locked`.
- `502`: The URL could not be fetched
- `503`: Vault service unavailable

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)