---
title: "Document the designed exterior as a PDF album"
method: POST
path: "/concepts/{concept}/album/generate"
tags: ["Albums"]
---

# Document the designed exterior as a PDF album

`POST /concepts/{concept}/album/generate`

## Request

- Base URL: `https://api.getfacade.ai/api/v1`
- URL: `https://api.getfacade.ai/api/v1/concepts/{concept}/album/generate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.getfacade.ai/oauth/authorize`, token URL `https://api.getfacade.ai/oauth/token`, scopes: `agent`)

The design documented for the crew that builds it: materials, the build-up of the
facade, safety notes and the regulatory references behind them. Requires a finished main
render on the design;
without one the API refuses with 422 and an explanation. The finished album's
`public_url` is a permanent public link that can be handed to a person as it stands.

## Path parameters

- `concept` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `data` object, required
    - `type` 'album', required
    - `attributes` object, required
      - `selected_renders` string[], required
      - `language` string: Defaults to the account language
      - `include_blueprints` boolean
      - `include_estimate` boolean
      - `requirements` string

## Response `200`

An album with these exact settings already exists and is returned instead of a second one: `duplicate_exists` is true on it. Send `force_regenerate` to build a new one.

- object
  - `data` Resource: JSON:API resource. `id` is a top-level field, never inside `attributes`.
    - `type` string, required
    - `id` string, required
    - `attributes` object
    - `relationships` object

## Other responses

- `202`: A JSON:API document
- `402`: Admission refused before any work was queued. `AGENT_KEY_CAP_REACHED` — this key has spent its cap, issue a new one or raise it. `AGENT_CREDITS_EXHAUSTED` — the account has no `api`-scope credits left. Neither is retryable: back off and report the `detail` text as it stands.
- `409`: `IDEMPOTENCY_IN_PROGRESS` — the first call carrying this `Idempotency-Key` has not answered yet. Retryable, and the only refusal here that is: wait and send the same call again, or read the job list. Do not re-send it under a new key — that is the second charge this header exists to prevent.
- `422`: The request was understood and refused. The message is the API's own text; show it unchanged. `IDEMPOTENCY_KEY_REQUIRED` — a paid call from an agent key with no `Idempotency-Key` header; nothing was queued, send it again with one. `IDEMPOTENCY_KEY_REUSED` — that header value already names a different request; a new order needs a new value.
- `429`: Rate limited on this key's own bucket, separate from the human sessions of the same account. Refusal is deliberately cheap: back off, do not retry in a tight loop.

---

[API](https://skmtc.dev/getfacade/apis/getfacade-agent-api.md) · [All operations](https://skmtc.dev/getfacade/apis/getfacade-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getfacade/apis/getfacade-agent-api/revisions/2b52eda7362c?raw)