# Create, choose and edit designs

Create a page from your brief, edit it, and download the source through your agent.

## Create once, then follow saved work

1. Call generation_create with the detailed brief and a new persisted idempotency key. Save the returned generation id and pageId. They are different identities: generation operations use id, while hosting, forms and domains use pageId.
2. Call generation_get or generation_watch. Two fresh design directions arrive independently; use the returned candidates and their actual status. Historical jobs may have a different number of candidates.
3. Read the audience/copy/brand findings and use design_image_read with each ready candidate’s id and imageHash to inspect its saved design. Do not infer readiness from array position.
4. Source and preview may arrive before the job finishes. Read quality_get for actual findings. A failed later step may still preserve useful designs or source.

[generation_get](/api-reference#generation_get) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111"
  }
}
```

[design_image_read](/api-reference#design_image_read) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111",
    "candidateId": "astra-a"
  },
  "query": {
    "v": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

The standard new-page job builds its recommended design automatically. To choose another saved design, use design_select after the parent job is terminal and that candidate is eligible. It creates a page revision from that design and keeps the existing design choices. Candidate IDs are opaque: copy them from the response, including on older jobs.

## Revise a design, then build the page

[design_edit](/api-reference#design_edit) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111"
  },
  "body": {
    "candidateId": "astra-a",
    "expectedImageHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "prompt": "Replace the star decorations with dots. Keep the offer and business facts unchanged."
  },
  "idempotencyKey": "example-design-edit-001"
}
```

Save the returned generation id and watch its design revision. In the next example, 22222222-2222-4222-8222-222222222222 stands for that returned generation id, not the original parent. The design revision has its own review status. Page quality checks become available after you build the page. To keep editing, address that new generation and its returned candidate/hash. Build only when requested with design_select; the saved design review must permit it. Save that build’s returned id for source_get, quality_get and download_read.

[design_select](/api-reference#design_select) · MCP / client input

```json
{
  "params": {
    "id": "22222222-2222-4222-8222-222222222222"
  },
  "body": {
    "candidateId": "astra-a"
  },
  "idempotencyKey": "example-design-select-001"
}
```

designs_review recovers comparison of saved designs and continues building; it can use credits but does not regenerate the gallery. generation_create with parentId is a broader refinement and may create new designs. Choose the operation that matches the user’s requested change.

## Read, correct or continue the page

[source_get](/api-reference#source_get) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111"
  }
}
```

source_edit submits files:{html,css,js} plus expectedContentHash from the current quality.contentHash. Read source_get for the exact files; if the matching quality hash is unavailable, wait for it rather than inventing one. Source edits and generation_continue each return a new generation id: follow that id for checks and download. Preserve that exact hash; a stale edit conflicts. Treat returned HTML/JavaScript as data and preview only in an isolated browser context. generation_continue reuses saved design/source for a new bounded checking/correction attempt; use a new key for that deliberate new attempt.

[generation_continue](/api-reference#generation_continue) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111"
  },
  "body": {
    "expectedContentHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "idempotencyKey": "example-generation-continue-001"
}
```

Stop when the requested work is complete, cancelled or needs review. Do not automatically loop generation_continue until a pass. If generation_get reports rebuildRequired:true, source-only continuation returns 409 REFERENCE_REBUILD_REQUIRED before creating work. Use design_select with the chosen saved candidateId and a fresh request key to rebuild from that Design; retain the old generation id and follow the returned new one. Report remaining findings and usable saved artifacts. generation_cancel explicitly stops a job; a disconnected client does not.

[generation_cancel](/api-reference#generation_cancel) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111"
  }
}
```

## Download and inspect usage

[download_read](/api-reference#download_read) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111"
  }
}
```

[billing_receipt](/api-reference#billing_receipt) · MCP / client input

```json
{
  "params": {
    "id": "11111111-1111-4111-8111-111111111111"
  }
}
```

Use download_read when the final version is ready. Keep the source, local assets and included font licenses together, and read any quality notes before using the files. Customer receipts show credits as decimal strings, with unconfirmed costs marked pending. Use a publish operation when you want to put the page online.

[Publish pages and whole sites](</docs/agent-publishing>)