Imports

How content enters Renza. An import takes HTML (upload, paste, or URL), parses the slide contract, and yields a deck plus its first artifact — or a new artifact version on an existing deck when you reuse an `external_id`.

Related guides: Import a deck

Attributes

idstringrequired
objectstringrequired
sourcestringrequired
Possible values: upload, paste, url
statusstringrequired
Possible values: pending, processing, succeeded, failed
deckstring | nullrequired
artifactstring | nullrequired
external_idstring | nullrequired
errorstring | nullrequired
livemodebooleanrequired
created_attimestamprequired
updated_attimestamprequired
uploadsarray of objectoptional
Direct upload only (status `pending`): PUT each declared file's raw bytes to its `url` (exact declared size), then call finalize. Returned once, on create.

Endpoints

GET/v1/imports
POST/v1/imports
GET/v1/imports/{id}
POST/v1/imports/claim
POST/v1/imports/{id}/finalize
POST/v1/public/imports

The Import object

{
  "id": "imp_5d2a…",
  "object": "import",
  "source": "paste",
  "status": "succeeded",
  "deck": "deck_2a9f8c1b",
  "artifact": "art_7c1b…",
  "external_id": "q3-board-deck",
  "error": null,
  "livemode": true,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z",
  "uploads": [
    {
      "path": "img/hero.png",
      "url": "https://…/?pathname=artifacts%2Fart_7c1b%2Fimg%2Fhero.png&…",
      "method": "PUT",
      "expires_at": "2026-06-19T10:30:00.000Z"
    }
  ]
}

List imports

GET/v1/imports

Lists imports in the active org, newest first. Filter by `status`.

Requires an API key (bearer), scoped to the active org.

Query parameters

limitintegeroptionaldefault 201–100
cursorstringoptional
orderstringoptionaldefault "created_at.desc"
Possible values: created_at.desc, created_at.asc
statusstringoptional
Possible values: pending, processing, succeeded, failed

Returns

200A page of imports.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza imports list

GET /v1/imports

curl https://api.renza.io/v1/imports \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const page = await renza.imports.list();

Response 200

{
  "object": "list",
  "url": "/v1/decks",
  "data": [
    {
      "id": "imp_5d2a…",
      "object": "import",
      "source": "paste",
      "status": "succeeded",
      "deck": "deck_2a9f8c1b",
      "artifact": "art_7c1b…",
      "external_id": "q3-board-deck",
      "error": null,
      "livemode": true,
      "created_at": "2026-06-19T10:30:00.000Z",
      "updated_at": "2026-06-19T10:30:00.000Z",
      "uploads": [
        {
          "path": "img/hero.png",
          "url": "https://…/?pathname=artifacts%2Fart_7c1b%2Fimg%2Fhero.png&…",
          "method": "PUT",
          "expires_at": "2026-06-19T10:30:00.000Z"
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Import a deck

POST/v1/imports

Parses the slide contract, stores the HTML, and creates a deck + artifact (+ slides). With `external_id`, re-importing adds a new artifact version to the same deck.

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Body parameters

sourcestringrequired
Possible values: upload, paste
htmlstringoptional
Single-file: the raw deck HTML. Provide this OR `files`.
filesarray of objectoptional
Multi-file bundle (entry HTML + its assets) inline; the entry is auto-detected. Provide this OR `html`. ~3 MB total cap — larger bundles use `assets` (direct upload).
entry_pathstringoptional
Direct upload: the entry HTML's bundle-relative path (default `index.html`). Asset paths resolve relative to it.
assetsarray of objectoptional
Direct upload (large bundles, up to 100 MB): send the entry as `html` and DECLARE the other files here instead of inlining them. The import is created `pending` with an upload URL per file; PUT each file, then `POST /v1/imports/{id}/finalize`. Nothing is visible until finalize.
titlestringoptionalmax 300 chars
external_idstringoptionalmax 200 chars
Reuse + version the deck with this id (update-in-place). Omitted → the server derives a FRESH id from the title (never touching an existing deck) and returns it as `external_id`; republish with it to version the same deck at the same link.

Returns

201The completed import (deck + artifact created).

Failures use the standard error envelope with a closed set of codes.

Terminal

renza import deck.html --title "Q3 Board Deck"

POST /v1/imports

curl https://api.renza.io/v1/imports \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "source": "paste",
  "html": "<!doctype html><section>Slide 1</section>…",
  "files": [
    {
      "path": "index.html",
      "content_base64": "PCFkb2N0eXBl…"
    }
  ],
  "entry_path": "index.html",
  "assets": [
    {
      "path": "img/hero.png",
      "size": 4194304
    }
  ],
  "title": "Q3 Board Deck",
  "external_id": "q3-board-deck"
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const imported = await renza.imports.create({
  source: "paste",
  html: "<!doctype html><section>Slide 1</section>…",
  files: [{"path":"index.html","content_base64":"PCFkb2N0eXBl…"}],
  entry_path: "index.html",
  assets: [{"path":"img/hero.png","size":4194304}],
  title: "Q3 Board Deck",
  external_id: "q3-board-deck",
});

Response 201

{
  "id": "imp_5d2a…",
  "object": "import",
  "source": "paste",
  "status": "succeeded",
  "deck": "deck_2a9f8c1b",
  "artifact": "art_7c1b…",
  "external_id": "q3-board-deck",
  "error": null,
  "livemode": true,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z",
  "uploads": [
    {
      "path": "img/hero.png",
      "url": "https://…/?pathname=artifacts%2Fart_7c1b%2Fimg%2Fhero.png&…",
      "method": "PUT",
      "expires_at": "2026-06-19T10:30:00.000Z"
    }
  ]
}

Retrieve an import

GET/v1/imports/{id}

Fetches an import by Renza id or by `external_id` within the active org.

Requires an API key (bearer), scoped to the active org.

Path parameters

idstringrequired

Returns

200The import.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza imports get imp_5d2a…

GET /v1/imports/{id}

curl https://api.renza.io/v1/imports/imp_5d2a… \
  -H "Authorization: Bearer $RENZA_API_KEY"

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const imported = await renza.imports.get("imp_5d2a…");

Response 200

{
  "id": "imp_5d2a…",
  "object": "import",
  "source": "paste",
  "status": "succeeded",
  "deck": "deck_2a9f8c1b",
  "artifact": "art_7c1b…",
  "external_id": "q3-board-deck",
  "error": null,
  "livemode": true,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z",
  "uploads": [
    {
      "path": "img/hero.png",
      "url": "https://…/?pathname=artifacts%2Fart_7c1b%2Fimg%2Fhero.png&…",
      "method": "PUT",
      "expires_at": "2026-06-19T10:30:00.000Z"
    }
  ]
}

Claim anonymous imports

POST/v1/imports/claim

Reattributes the anonymous imports tracked against `anon_token` into the active org as real decks (the CLI's `~/.renza` token after `renza login`). Returns the created deck ids.

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Runs automatically during `renza login` — anonymous uploads are claimed into the org.

Body parameters

anon_tokenstringrequired
The client-held anon token whose anonymous imports to claim.

Returns

200The decks created from the claimed tries.

Failures use the standard error envelope with a closed set of codes.

POST /v1/imports/claim

curl https://api.renza.io/v1/imports/claim \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "anon_token": "anon_9f3c…"
}'

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const imported = await renza.imports.claim("anon_9f3c…");

Response 200

{
  "object": "import_claim",
  "deck_ids": [
    "deck_2a9f…"
  ]
}

Finalize a direct upload

POST/v1/imports/{id}/finalize

Completes a `pending` direct-upload import once every declared file has been PUT to its upload URL: creates (or versions) the deck and makes the new version current. Idempotent — finalizing a succeeded import returns it. 409 if files are still missing or the upload expired (2 h).

Requires an API key (bearer), scoped to the active org. Supports idempotency keys.

Runs automatically inside `renza publish` for large bundles.

Path parameters

idstringrequired

Returns

200The completed import.

Failures use the standard error envelope with a closed set of codes.

POST /v1/imports/{id}/finalize

curl https://api.renza.io/v1/imports/imp_5d2a…/finalize \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -X POST

TypeScript

import { createRenzaClient } from "renza-sdk";

const renza = createRenzaClient({ apiKey: process.env.RENZA_API_KEY! });

const imported = await renza.imports.finalize("imp_5d2a…");

Response 200

{
  "id": "imp_5d2a…",
  "object": "import",
  "source": "paste",
  "status": "succeeded",
  "deck": "deck_2a9f8c1b",
  "artifact": "art_7c1b…",
  "external_id": "q3-board-deck",
  "error": null,
  "livemode": true,
  "created_at": "2026-06-19T10:30:00.000Z",
  "updated_at": "2026-06-19T10:30:00.000Z",
  "uploads": [
    {
      "path": "img/hero.png",
      "url": "https://…/?pathname=artifacts%2Fart_7c1b%2Fimg%2Fhero.png&…",
      "method": "PUT",
      "expires_at": "2026-06-19T10:30:00.000Z"
    }
  ]
}

Anonymous import (no auth)

POST/v1/public/imports

Public. Hosts a single HTML deck without an account and tracks it against the supplied `anon_token`, returning a `/try/<id>` link. Pass the same `external_id` again to update that try in place (same link). Sign in later and claim the token's imports into a real org. Larger/multi-file imports require authentication.

Public — no authentication required. Supports idempotency keys.

`renza publish` uses this path when you're not logged in.

Body parameters

htmlstringoptional
Single-file: the raw deck HTML. Provide this OR `files`.
filesarray of objectoptional
Bounded multi-file bundle (entry + assets), entry auto-detected. Max 20 files / ~3 MB — sign in for larger bundles.
anon_tokenstringrequired
A client-held token the import is tracked against (the claim key).
external_idstringoptionalmax 255 chars
Stable id, unique per anon token. Republishing with the same one UPDATES the existing try in place — same /try link, fresh content and TTL — instead of minting a new link. Omitted → the server derives a fresh one from the deck title and returns it as `external_id`; reuse it to update in place.

Returns

200An existing try, updated in place (matched by `external_id`).
201The hosted anonymous import.

Failures use the standard error envelope with a closed set of codes.

Terminal

renza publish deck.html

POST /v1/public/imports

curl https://api.renza.io/v1/public/imports \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
  "html": "<!doctype html><section>Slide 1</section>…",
  "files": [
    {
      "path": "index.html"
    }
  ],
  "anon_token": "anon_9f3c…",
  "external_id": "renza-intro"
}'

Response 200

{
  "object": "guest_import",
  "id": "gim_5d2a…",
  "url": "https://renza.io/try/gim_5d2a…",
  "expires_at": "2026-07-07T10:30:00Z",
  "external_id": "renza-intro"
}