References

Everything the agent can see and work from — files, designs, URLs, text, HTML.

References are the inputs the design agent sees and works from. A request can mix any number of them: a brand kit, three product photos, the user's website, and a text file of copy, all in one references array.

Reference types

Prop

Type

Every reference is an object with a type discriminator:

A mixed references array

[
  { "type": "design", "id": "rmd_cj4hbqz4f0005mz6x7p9q2xr" },
  { "type": "file", "id": "rmf_cj4hbqz9x0001v2x8n6tqz7e" },
  { "type": "url", "url": "https://acmecoffee.co" },
  {
    "type": "text",
    "name": "sale-copy.md",
    "text": "Headline: Summer Sale — 30% off everything.\nSubline: This weekend only."
  },
  { "type": "html", "name": "base-layout.html", "html": "<main>…</main>" }
]

Designs can be references

Passing a design you created earlier — a template, an approved asset, or a brand kit — is the single most powerful pattern in the API. The agent treats it as ground truth and builds on it rather than starting from zero. See Editing and the user-created templates guide.

Uploading files

Upload a file once, get back a persistent rmf_… ID, and use it in as many requests as you like.

// multipart upload
const form = new FormData();
form.append("file", new Blob([await fs.readFile("brand-guidelines.zip")]), "brand-guidelines.zip");

const file = await fetch("https://api.rivermark.ai/upload", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.RIVERMARK_API_KEY}` },
  body: form,
}).then((r) => r.json());

// or snapshot a webpage by URL — fetched and extracted once:
const page = await fetch("https://api.rivermark.ai/upload", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIVERMARK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://acmecoffee.co/about" }),
}).then((r) => r.json());

Response

{
  "id": "rmf_cj4hbqz9x0001v2x8n6tqz7e",
  "name": "brand-guidelines.zip",
  "mime_type": "application/zip",
  "size": 2483712,
  "kind": "archive"
}

Webpage URLs can also be passed directly as { "type": "url" } references without pre-uploading — the effect is the same, a one-time fetch. Pre-uploading is useful when the same page will back many requests, or when you want Rivermark to snapshot a page before it changes.

Supported file types

Currently supported:

Images (PNG, JPEG, WebP, SVG, AVIF)
Text files (.txt, .md, CSV)
HTML/CSS files
.zip archives (brand guidelines, assets, batches of files)
Webpage URLs (fetched and extracted once)
Canva designs

On request:

PDFs
Figma designs
.docx (Word) documents
.pptx (PowerPoint)

Inside archives, Rivermark reads nested images, text, HTML, and even other archives, so a full brand guidelines drop works as a single reference.

Need a format?

If a format you rely on is on the request list, tell us — we will enable it for your account.

How references are used

The agent decides how to use each reference based on your task:

as source material — copy gets typeset into the design, images get placed (never redrawn),
as style guidance — a brand kit or a website's look steers typography, palette, and composition,
as a starting point — a design or HTML reference is edited rather than recreated.

If a task is ambiguous about which reference to use for what, say so in the task (see Tasks and prompts). Optional instructions on /brandkit serve the same purpose for brand extraction.

References

Reference types

Uploading files

Supported file types

How references are used

On this page