---
title: "Import raw bytes as a typed Asset"
method: POST
path: "/v1/assets/import"
tags: ["Assets"]
---

# Import raw bytes as a typed Asset

`POST /v1/assets/import`

## Request

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

Byte→typed-Asset rich ingress (Phase 3 of `unified-memory-media-substrate.md`).
The raw binary request body plus its declared `Content-Type` becomes a typed base
Asset (recorded through the sole writer `AssetStore.create` with a
`<media>_import` verb and an empty `derivedFrom`, so it is non-replayable by
construction), and every decodable Apple-capture side-channel (depth, gain map,
ProRAW develop, per-eye spatial views) is preserved as a sibling Asset
`derivedFrom` the base. This is the body-bearing twin of the path-bearing
`image_import` MCP verb; both feed one `AssetImportCore`, and both return the
SAME `WireAssetImportResponse` envelope: the base Asset, its siblings, and any
portable recipe or third-party workflow document embedded in the file.

## Response `200`

The import envelope — base Asset, side-channel siblings, and anything the file carried

- WireAssetImportResponse: The product of an import, shared by both transports (`POST /v1/assets/import` and the `image_import` / `video_import` MCP verbs).
  - `asset` WireAsset, required: A provenance-linked typed Asset record. Bytes are served separately via the `dataRef` MCP resource link, never inline.
    - `id` string, required: Stable Asset identifier.
    - `type` string, required: Typed-Asset medium (e.g. `image`, `video`, `mask`, `conditioning`, `splat`).
    - `contentHash` string, nullable: Content hash of the Asset's bytes; null for a pre-CAS / hashless Asset.
    - `createdAt` string, required: ISO-8601 timestamp when the Asset was minted.
    - `dataRef` string, required: MCP `resource_link` uri for the Asset's bytes (served by `resources/read`).
    - `derivedFrom` string[], required: Ids of the parent Assets this one was derived from; empty for a base import.
    - `conditioningKind` 'depth' | 'canny' | 'pose' | 'reference', nullable: Which structural-control field a `conditioning` Asset carries: a depth map, a canny edge map, a pose render, or a reference image. Set only on `type: conditioning` Assets; absent for every other type.
    - `trackId` string, nullable: Stable identity of the video track a track-born Asset belongs to (`video_segment`): per-frame masks of one tracked region share it, and a `conditioning` sibling that follows the region across frames carries the SAME id — one wire contract across both. Absent for every non-track Asset.
    - `madeBy` WireAssetMadeBy, required: Provenance edge of a typed Asset — the verb (and optional model@revision + canonical params) that produced it.
      - `verb` string, required: The verb that minted the Asset (e.g. `image_import`, `storyboard_create`).
      - `model` string, nullable: Human model name when a model produced the bytes; null for non-model verbs (e.g. import).
      - `modelRepo` string, nullable: Source repository the model was pulled from (e.g. an HF repo id); null when not model-produced.
      - `modelRevision` string, nullable: Pinned model revision; null when not model-produced.
      - `params` object, required: Canonical string-valued params that, with the model, make the step replayable.
  - `siblings` WireAsset[], required: Preserved Apple capture side-channels, each `derivedFrom` the base.
    - `id` string, required: Stable Asset identifier.
    - `type` string, required: Typed-Asset medium (e.g. `image`, `video`, `mask`, `conditioning`, `splat`).
    - `contentHash` string, nullable: Content hash of the Asset's bytes; null for a pre-CAS / hashless Asset.
    - `createdAt` string, required: ISO-8601 timestamp when the Asset was minted.
    - `dataRef` string, required: MCP `resource_link` uri for the Asset's bytes (served by `resources/read`).
    - `derivedFrom` string[], required: Ids of the parent Assets this one was derived from; empty for a base import.
    - `conditioningKind` 'depth' | 'canny' | 'pose' | 'reference', nullable: Which structural-control field a `conditioning` Asset carries: a depth map, a canny edge map, a pose render, or a reference image. Set only on `type: conditioning` Assets; absent for every other type.
    - `trackId` string, nullable: Stable identity of the video track a track-born Asset belongs to (`video_segment`): per-frame masks of one tracked region share it, and a `conditioning` sibling that follows the region across frames carries the SAME id — one wire contract across both. Absent for every non-track Asset.
    - `madeBy` WireAssetMadeBy, required: Provenance edge of a typed Asset — the verb (and optional model@revision + canonical params) that produced it.
      - `verb` string, required: The verb that minted the Asset (e.g. `image_import`, `storyboard_create`).
      - `model` string, nullable: Human model name when a model produced the bytes; null for non-model verbs (e.g. import).
      - `modelRepo` string, nullable: Source repository the model was pulled from (e.g. an HF repo id); null when not model-produced.
      - `modelRevision` string, nullable: Pinned model revision; null when not model-produced.
      - `params` object, required: Canonical string-valued params that, with the model, make the step replayable.
  - `recipe` WireMediaRecipe: The portable recipe embedded in exported media: the replayable instruction form of an Asset's provenance. DISTINCT from the signed lineage receipt — a receipt attests bytes and is deliberately detached, while a recipe instructs and is unsigned, strippable, and carries no claim about the bytes it rides in. Embedding is user-toggleable and enforced at export, so the canonical Asset bytes never carry it.
    - `version` string, required: Envelope version; an unrecognized version is refused whole.
    - `generator` string, required: What wrote the recipe.
    - `sourceType` string, required: Medium of the Asset the recipe describes.
    - `sourceContentHash` string, nullable: CAS digest of the CANONICAL Asset bytes — i.e. before the recipe was embedded, so deliberately NOT the digest of the file it rides in. It lets a re-import recognize a known Asset; it is never a self-check.
    - `createdAt` string, required: ISO-8601 timestamp the recipe was built.
    - `steps` WireMediaRecipeStep[], required: The hops in chronological order, so a consumer executes them front to back with no topological sort.
      - `verb` string, required: The verb this step ran.
      - `model` string, nullable: Human model name the step bound; null for a non-model verb.
      - `modelRepo` string, nullable: HuggingFace `org/name` of the bound checkpoint.
      - `modelRevision` string, nullable: Immutable revision of the bound checkpoint.
      - `provider` string, nullable: Cloud provider id when a hosted provider produced the bytes.
      - `params` object, required: The step's canonical arguments.
      - `resources` WireResourcePin[], nullable: LoRA / ControlNet / VAE overlays the step bound, in bind order — the modifier stack as recorded.
        - `role` 'lora' | 'vae' | 'controlnet' | 'ipadapter', required: The resource's function.
        - `model` string, required: Id of the applied component.
        - `modelRepo` string, nullable: HuggingFace `org/name` of the applied component.
        - `modelRevision` string, nullable: Immutable revision of the applied component; null makes the generation non-replayable (fail closed).
        - `weight` number, nullable: Applied overlay strength; the trained default when absent.
      - `inputs` integer[], required: Indices into `steps` naming this step's inputs. A parent outside the exported closure is omitted rather than faked.
  - `embeddedWorkflow` string, nullable: A structured workflow document another tool embedded, as RAW text — deliberately untyped, because reconstruction is the chat agent reading intent, never a foreign-format parser. Absent when the file carries a Piper recipe of its own.

## Other responses

- `400`: Empty import body
- `413`: Import payload exceeds the size limit
- `415`: The declared Content-Type is not a supported import medium
- `500`: Import failed (write failed or unexpected error)
- `503`: Asset store 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)