---
title: "Three design directions (palette, font pairing, hero layout, corners) for a site that does not exist yet, from one small AI call (metered in Build Credits); send directionsId and feedback to refine them (at most 5 times). Every look meets WCAG AA contrast"
method: POST
path: "/builder/directions"
tags: ["Builder"]
---

# Three design directions (palette, font pairing, hero layout, corners) for a site that does not exist yet, from one small AI call (metered in Build Credits); send directionsId and feedback to refine them (at most 5 times). Every look meets WCAG AA contrast

`POST /builder/directions`

## Request

- Base URL: `https://hostingsurge.com/api/v1`
- URL: `https://hostingsurge.com/api/v1/builder/directions`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Host-hs_session`

## Query parameters

- `orgId` string

## Request body

- object
  - `prompt` string, required: What the site is for (the first message)
  - `template` string
  - `directionsId` string, uuid: Refine these directions (at most 5 times)
  - `feedback` string: What the customer wants different

## Response `200`

Three looks

- object
  - `id` string, uuid, required
  - `looks` object[], required
    - `name` string, required
    - `mood` string, required
    - `seed` object, required
      - `background` string, required: The page background
      - `primary` string, required: The brand color: buttons, links, accents
      - `accent` string, required: A second color for highlights and badges
      - `dark` boolean, required: A dark site (light text on a dark page)
      - `pairing` 'modern' | 'editorial' | 'elegant' | 'friendly' | 'bold' | 'classic' | 'reading' | 'expressive' | 'playful' | 'technical' | 'geometric' | 'sturdy', required
      - `hero` 'centered' | 'split' | 'full-bleed', required
      - `radius` 'sharp' | 'soft' | 'round', required
    - `tokens` object, required: Every color token of both schemes (AA contrast guaranteed)
      - `light` object, required
      - `dark` object, required
  - `refinesLeft` integer, required
  - `credits` number, required: Build Credits this call used

## Other responses

- `400`: Invalid request (code invalid_request; details.reason: unsupported, too_large, unreadable, no_text, reference_gone)
- `401`: Missing or invalid session/token (code unauthorized)
- `402`: No Build Credits left, or the team's daily credits are used (code limit_reached)
- `403`: Authenticated but not permitted (code forbidden; details.reason private_beta or role)
- `404`: Not found or not visible to the caller (code not_found)
- `409`: Refused for now (code conflict; details.reason: plan_building, plan_dismissed, plan_empty, refines_used, figma_connect, archived, stale)
- `429`: Too many requests (code rate_limited; details.reason mode_rate, daily_budget, provider_busy); see Retry-After
- `501`: Not available on this server (code not_configured; details.reason capture_off, figma_off, migration_pending)
- `503`: The AI did not answer (code provider_unavailable); nothing was charged for the failed try

---

[API](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api.md) · [All operations](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hostingsurge/apis/hostingsurge-platform-api/revisions/4d08337cdff1?raw)