Designs

The design is the central object in the Rivermark API. Every /design and /brandkit call creates one, identified by a persistent ID that you can use in any later request.

Design IDs

Design IDs look like rmd_cj4hbqz2w0003mz6x7p9q2xe — a rmd_ prefix followed by a collision-resistant unique ID. They are:

• persistent — designs are stored permanently by default, so you can treat the ID as a long-lived identifier in your own database,
• addressable — retrieve metadata with GET /design/{id}, delete with DELETE /design/{id},
• referenceable — pass the ID as a reference in any later request to build on it, or use continue_from to fork an editing session from it (see Editing).

Uploaded files get their own rmf_… IDs (see References).

What lives inside a design

A design is a real HTML/CSS document tree — one or more frames, their imagery, and their fonts — exactly what a human would produce in the Rivermark editor. Because designs are HTML/CSS rather than opaque rasters:

• sets of frames stay consistent with each other,
• output is deterministic, portable, and editable — you can download the source from the changes list and change it,
• precise edits ("make the headline 20% smaller") are cheap and reliable.

Brand kits are designs

A brand kit extracted with POST /brandkit is internally the same thing as a design. It carries a design_id with the same rmd_ format, lives under the same endpoints, and can be passed anywhere a design reference is accepted.

The difference is purely in content and intent: a brand kit contains structured brand data — palette, fonts, assets, voice — which the agent uses to keep everything it creates on-brand. (You can retrieve the structured fields of a brand kit at any time with GET /design/{id}.)

This means, for example, that you can:

• pass a brand kit as a reference when creating designs,
• continue_from a brand kit to refine the brand definition itself ("we've rebranded: swap the accent color to teal"),
• use a regular design as a light-weight brand reference when a full brand kit doesn't exist yet.

Rendered output is ephemeral, designs are not

The image URLs in the output and changes fields are temporary — download what you want to keep. The design itself, including its source files, is stored permanently and can be referenced, forked, edited, or re-rendered at any time.

Managing designs

Retrieve a design's metadata — creation time, outputs, cost — with:

curl https://api.rivermark.ai/design/rmd_cj4hbqz2w0003mz6x7p9q2xe \
  -H "Authorization: Bearer $RIVERMARK_API_KEY" | jq

{
  "design_id": "rmd_cj4hbqz2w0003mz6x7p9q2xe",
  "created_at": "2026-10-12T09:24:11Z",
  "continued_from": null,
  "change_summary": "Created an Instagram post for the summer sale",
  "outputs": [{ "id": "post", "format": "png", "width": 1080, "height": 1350 }],
  "cost": 0.08
}

If the design is a brand kit, the response additionally includes the brand kit fields — name, palette, fonts, assets, voice, and so on.

Delete a design and its assets with DELETE /design/{id}. Deleted designs become immediately inaccessible; copies may be retained for up to 30 days for diagnostics and legal retention, then purged. See the API reference for both endpoints.

Time-to-live

If you create large numbers of short-lived designs (for example, one per user session in an editor product), you can set a per-design TTL from the API dashboard — designs that aren't referenced within their TTL are cleaned up automatically. Designs referenced by other designs (for example templates used in a pipeline) are never auto-deleted.