---
title: "House Specify"
method: POST
path: "/house/specify"
---

# House Specify

`POST /house/specify`

## Request

- Base URL: `https://api.colourmemory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.colourmemory.com/house/specify`
- Auth: none declared

Multi-room colour scheme grounded entirely in documented archive
provenance. Groups candidates by weighted provenance strength (same
object > same pattern colourway > same source entry > same pattern
book > same designer+material > same designer > same period+
institution > visual similarity fallback), assigns groups to rooms
respecting orientation constraints, and builds full colour cards
(paint matches, LRV, illuminant behaviour, WCAG) for every colour.
Historical rationale is templated only from documented fields; design
rationale (room/surface assignment) is clearly separated and never
presented as a historical claim.

## Headers

- `x-api-key` string, nullable
- `origin` string, nullable

## Request body

- HouseSpecifyRequest
  - `concept` string, required
  - `output_format` 'standard' | 'scene_brief'
  - `archive` string, required
  - `rooms` HouseRoomSpec[], required
    - `label` string, required
    - `room_type` string
    - `orientation` string, nullable
    - `function` string, nullable
    - `requested_character` string, nullable
    - `surface_targets` HouseSurfaceTarget[]
      - `surface_role` string, required
      - `target_hex` string
      - `intent` string
      - `allow_contrast` boolean
    - `surfaces` object[]
  - `colours_per_room` integer
  - `shared_house_colours` integer
  - `minimum_claim_strength` string
  - `guidance_level` 'client' | 'decorator'
  - `avoid` string[]
  - `narrative_mode` string
  - `strict_semantic_colour` boolean
  - `colour_direction` 'balanced' | 'distinctive': Experimental -- opt-in only, not part of the stable API surface. Colour direction for this scheme. balanced (default) preserves the existing evidence-led specification. distinctive pushes this scheme toward a clearer, more committed colour identity where the documented archive supports it. How far it can go depends on the surviving evidence; the response reports what was achieved.
  - `save` boolean

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/colourmemory/apis/colour-memory-api.md) · [All operations](https://skmtc.dev/colourmemory/apis/colour-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/colourmemory/apis/colour-memory-api/revisions/4ba028f64042?raw)