Guide

Changelog

Every change to the v1 API, newest first.

2026-10-05 — delete a job, per-key retention, result URLs

• New endpoint: DELETE /v1/jobs/{id} deletes a finished job together with its rendered results and its input image, and answers 204. A job that is still processing answers 409 job_in_progress, a new error code. A job of another account, or one already deleted, answers 404 job_not_found; after a delete, GET /v1/jobs/{id} answers 404 too. A webhook not delivered yet is not sent. Deletes have their own limit of 60 per minute per key. See Delete a job.
• GET /v1/account returns a new field, retention_days: the number of days after which jobs created with the key are deleted, images included, or null when the key has none. Roomagen sets it on request. See Storage and retention.
• The input image of a request that is rejected without creating a job, for example with 402 insufficient_credits, is now deleted at once. Until now it was kept with the failed run.
• The input image of a failed job is deleted 30 days after the job was created.
• Documentation: the result URL examples showed https://api.roomagen.com/api/uploads/…, which is not where results are served. Result images are public URLs of the form https://uploads.roomagen.com/<account-id>/<file-id>-<name>.<ext>; how long they are kept is now documented under Storage and retention.

2026-10-03 — every tool documented, warnings, idempotent replays, free-image watermark

• Every tool GET /v1/tools returns is now documented, with its options, its price and an example; Tools lists them by what they do. Until now seven were documented and the rest were accepted without documentation. Nothing changes for calls you already make. A few things worth knowing:
  • Most tools do not read customPrompt; the Tools tables say which do.
  • 4k-upscale sends the same prompt and asks for the same 4K output as image-upscaling, but is charged as two images.
  • sketch-to-floor-plan leaves out dimensions, room names and furniture unless you ask for them (preserve).
• POST /v1/jobs answers with a new field, warnings: the options in your request that the tool will not use — a key it does not have (with the key you probably meant), a customPrompt it does not read or that was sent without tier: "custom", a resolution other than 2K or 4K. Nothing is rejected that was accepted before: the job runs exactly as it did. warnings is always present and usually empty. See Warnings.
• Until an account buys a pack, its renders now carry a Roomagen watermark. That is what the API pages have always said about the 50 free images, but the watermark was not being applied. Accounts that have bought a pack see no change: every render stays watermark-free, the free images left over included. See Pricing.
• A request replayed with the same Idempotency-Key and body used to answer processing forever, even for a job that had long finished, so a client retrying after a timeout never learned the outcome from POST /v1/jobs. It now answers 201 with the job as it stands — the job object GET /v1/jobs/{id} returns — so the status can already be completed with result_urls, or failed with error. Nothing is charged and nothing is rendered again. If the job that key created no longer exists, the replay answers 404 job_not_found. See Idempotency.

2026-10-03 — tool fixes: stainless steel, facade material, holiday decorations

• bathroom-fixtures accepts fixtureFinish: "stainless-steel". It was rejected with 400 invalid_request.
• construction-exterior has a new facadeMaterial value, auto, and it is now the default: the facade is chosen to suit the style and the building, and the model is told to keep a material the building is clearly being finished in (brick, stone, cladding, glass). Until now a request without facadeMaterial always asked for a plaster facade; send "plaster" to keep that.
• festive-flip: Christmas, Halloween and Easter list their decorations per regional style, and without holidayRegion the instruction used to list none. The first style is now used — american for Christmas and Halloween, western for Easter. A holidayRegion the holiday does not have is ignored instead of emptying the list, and decorations with no id the theme's list has gets the whole list instead of none. See Festive flip.
• exterior-additions with hasExisting: "true" names what it replaces — a fence or boundary wall, a driveway, a garage or carport — instead of calling it by the new type's name. It and landscaping are now told to keep pools, spas, pergolas, gazebos, decks and patios as they are.
• watermark-removal with removalTarget: "watermark" removes the watermark and logo overlays; it is no longer told to remove copyright notices. Use it on photos you own or have the rights to edit.
• lighting-update: its option description said fixtures are "added or replaced". The tool has always replaced only the fixtures already in the photo — it is told not to add new ones — and the description now says so.

2026-10-03 — webhook verification sample, day to dusk

Documentation only; the API itself did not change.

• The Node verification sample on Webhooks compared string lengths before crypto.timingSafeEqual. A signature header with non-ASCII characters can have the right number of characters and more bytes; timingSafeEqual then throws instead of returning false, and in an async handler that can take the process down. The sample now compares the byte lengths of the two Buffers. The Python sample compared str values, which hmac.compare_digest rejects with TypeError when one has non-ASCII characters; it now compares bytes. If you copied either sample, apply the same change.
• day-to-dusk is the interior tool: it treats every photo as a room (windows, the view through them, the room's own lights). Its page described an exterior; it now says so and explains hasWindows.
• day-to-dusk-exterior, accepted since launch and listed by GET /v1/tools, is documented for building exteriors, with its options timeShift and season.

2026-09-30 — floor plan to 3D

• floor-plan-to-3d is documented, with its options. New optional keys: fp3dOutdoor (as_drawn by default: balconies, terraces, pools and parking only where the plan draws them) and fp3dLabels (none by default). inputType also accepts auto: no format hint, the same as leaving the key out.
• tier custom now uses customPrompt for this tool; before, the text was ignored and the default prompt ran. furnitureMode empty sent with it still gives an empty shell.
• The aliases view (→ outputStyle) and style (→ interiorStyle, when it is one of its values) are accepted. An unknown view, or an unknown value for one of the tool's own keys, is rejected with invalid_request in every tier — previously custom and auto requests ignored it.
• The model is now told to build the plan once (no second copy on the sheet) and to draw doors, windows and outdoor areas only where the plan draws them.

v1 — 2026-08-30

Initial public release: 5 tools, webhooks, idempotency, self-serve keys.