Developers

Create designs from code

One public endpoint turns a short JSON brief into a furnished design and returns links that open it in Arcvelle Studio and the 3D viewer. No key is needed. API keys, stored projects and an MCP server are planned.

POST /api/agent/design

Send rooms with their sizes, or the slug of a template. Rooms without positions are laid out left to right, sharing walls. Smart Layout furnishes each room in the chosen style.

Request

curl -X POST https://arcvelle.com/api/agent/design \
  -H "Content-Type: application/json" \
  -d '{ "name": "Garden flat", "style": "japandi", "rooms": [ { "type": "living",  "width": 5,   "depth": 4 }, { "type": "bedroom", "width": 3.5, "depth": 4 } ], "openings": [ { "type": "door",   "at": [5, 2] }, { "type": "window", "at": [2.5, 0] } ] }'

The response holds the full design document, a summary of rooms and areas, and two links. The design travels inside the link after #d=, so nothing is stored on the server.

Response (shortened)

{
  "design":  { "version": 1, "name": "Garden flat", "walls": [...], "items": [...], ... },
  "summary": {
    "name": "Garden flat",
    "style": "Japandi",
    "levels": [{ "name": "Ground floor", "rooms": [
      { "name": "Living room", "type": "living",  "area": 20 },
      { "name": "Bedroom",     "type": "bedroom", "area": 14 } ] }],
    "items": 25
  },
  "links": {
    "studio": "https://arcvelle.com/studio#d=N4Igbg…",
    "view":   "https://arcvelle.com/view#d=N4Igbg…"
  }
}

Brief fields

Field	Type	Notes
`rooms`	array, 1–20	Each: `type`, `width` and `depth` in metres (0.8–30), optional `name`, and `x`/`y` for the top-left corner (give them on every room or none).
`template`	string	Instead of rooms: one of 13 template slugs, such as `two-bedroom-apartment`.
`style`	string	japandi, modern, scandinavian, minimalist, industrial, mid-century, bohemian, coastal, classic, wabi-sabi. Default modern.
`openings`	array, up to 80	`type` (door, double-door, sliding-door, window, tall-window, opening), `at`: a point on or near the wall in metres, optional `width`.
`name`, `units`	string	Project name; display units `m` or `ft`. Sizes in the brief are always metres.

Room types: living, bedroom, kitchen, dining, bathroom, office, kids, hallway, outdoor, other.

GET /api/agent/schema

JSON Schemas (draft 2020-12) of the brief and of the design document, for validation and for giving to a language model as a tool definition.

Request

curl https://arcvelle.com/api/agent/schema

Conventions

Lengths are metres. Plan x points right and y points down; rotation is in radians, clockwise in plan. In 3D, plan (x, y) is world (x, z) and y is up.
Designs are repaired on load: invalid elements are dropped, missing fields get defaults. Any design you build yourself can be opened by encoding it the same way as the links (LZ-string, URI-safe) after #d=.
Errors are JSON: { "error": { "code": "invalid_input", "message": "…" } } with status 400, 413, 415, 422 or 429.
Requests are limited to 60 an hour per caller while the API has no keys.

GET /api/health

Liveness for monitors: { "status": "ok", "version": "…" }. Add ?deep=1 to include dependency checks.

Building an AI agent? See Arcvelle for AI agents.

Questions about the API?

Tell us what you are building and what you need from the API.