# List AI designs (`list_ai_designs`)

List the AI designs of this store, newest first, with an opaque cursor: the designs shoppers made in the customer customiser, quote files converted with the AI sign designer, merchant admin uploads and AI sign design jobs. Filter by status, origin, customiser_id or creation day. Each design has its outcome, its files and the products, orders and quote it is linked to. The shopper name, email and contact details are never returned. Requires ai_sign_designs:read. Has no side effects.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/list_ai_designs/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/list_ai_designs.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `ai_sign_designs:read`
- Behaviour: read

## Purpose

Find the AI designs shoppers and the merchant made, and see which ones were delivered, refused or failed.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

- A merchant has connected this store and approved the ai_sign_designs:read scope.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no | How many designs to return per page, between 1 and 100. Defaults to 20. |
| `cursor` | string | no | The opaque next_cursor value from the previous page, sent back with identical filters and timezone. |
| `filter` | object | no | Optional filters. An unknown filter is rejected, never ignored. |
| `filter.status` | string | no | Only designs with this status: processing, delivered, refused, failed. Expected to grow. |
| `filter.origin` | string | no | Only designs from this origin: customer_customiser, quote, merchant_admin, api. Expected to grow. |
| `filter.customiser_id` | integer | no | Only designs made in this customiser. |
| `filter.created_from` | string | no | The first included creation day, YYYY-MM-DD, counted in timezone. |
| `filter.created_to` | string | no | The last included creation day, YYYY-MM-DD, counted in timezone. It must not precede created_from. |
| `timezone` | string | no | The IANA timezone the creation days are counted in, such as Australia/Sydney. Defaults to UTC. |

## Result

A page of designs and the pagination block. An erased design is not listed. Each file has a download_url only when the design has a no-login link; a private file of a shopper, quote or merchant admin design has none.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `ai_designs` | array of object | yes | The page of designs, newest first. |
| `ai_designs[].id` | integer | yes |  |
| `ai_designs[].origin` | string | yes | customer_customiser (a shopper used the AI sign designer), quote (a quote file was converted), merchant_admin (an upload in the merchant admin) or api (an AI sign design job). Expected to grow. One of: `customer_customiser`, `quote`, `merchant_admin`, `api`. |
| `ai_designs[].status` | string | yes | processing, then delivered (a design exists), refused (a check refused the design) or failed (no design for another reason). No credit is charged for refused or failed. Expected to grow. One of: `processing`, `delivered`, `refused`, `failed`. |
| `ai_designs[].product_family` | string or null | no | One of: `neon`, `channel_letter`, `metal_cut_out`. |
| `ai_designs[].customiser_id` | integer or null | no |  |
| `ai_designs[].files` | array of object | yes | The SVG, EPS, PDF, preview and face files only when status is delivered, and the uploaded source and its preview for every status. |
| `ai_designs[].files[].kind` | string | yes | One of: `svg`, `eps`, `illustrator_pdf`, `raster_preview`, `face_svg`, `source`, `source_preview`. |
| `ai_designs[].files[].purpose` | string | yes |  |
| `ai_designs[].files[].media_type` | string | yes |  |
| `ai_designs[].files[].access` | string | yes | One of: `private`, `public`. |
| `ai_designs[].files[].download_url` | string or null | no | A URL that needs no login. For a private file of an api design it is a revocable Sign Customiser link. For a public file it is the public storage URL, which cannot be revoked. Null for every other private file. |
| `ai_designs[].product_ids` | array of integer | yes |  |
| `ai_designs[].order_ids` | array of integer | yes |  |
| `ai_designs[].quote_id` | integer or null | no |  |
| `ai_designs[].quote_file` | object or null | no | The quote file the design was converted from, or null. |
| `ai_designs[].quote_file.field_id` | string | yes |  |
| `ai_designs[].quote_file.file_index` | integer | yes |  |
| `ai_designs[].ai_sign_design_job_id` | string or null | no |  |
| `ai_designs[].feedback_rating` | string or null | no | One of: `thumbs_up`, `thumbs_down`. |
| `ai_designs[].created_at` | string | yes |  |
| `pagination` | object | yes |  |
| `pagination.has_more` | boolean | yes |  |
| `pagination.next_cursor` | string or null | no |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without ai_sign_designs:read. |
| `invalid_cursor` | The cursor belongs to other filters. Call the tool again without a cursor. |
| `invalid_parameter` | A filter value is not supported; allowed_values lists the accepted values. |

## Example: List the delivered designs

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_ai_designs",
    "arguments": {
      "filter": {
        "status": "delivered"
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "ai_designs": [
        {
          "id": 51234,
          "origin": "quote",
          "status": "delivered",
          "product_family": "neon",
          "customiser_id": 42,
          "files": [
            {
              "kind": "svg",
              "purpose": "design",
              "media_type": "image/svg+xml",
              "access": "private",
              "download_url": null
            },
            {
              "kind": "source",
              "purpose": "source",
              "media_type": "image/png",
              "access": "private",
              "download_url": null
            }
          ],
          "product_ids": [],
          "order_ids": [],
          "quote_id": 8123,
          "quote_file": {
            "field_id": "field_artwork",
            "file_index": 0
          },
          "ai_sign_design_job_id": null,
          "feedback_rating": "thumbs_up",
          "created_at": "2026-10-20T09:32:00Z"
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}
```

## Example: A status that does not exist (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_ai_designs",
    "arguments": {
      "filter": {
        "status": "downloadable"
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "invalid_parameter",
        "title": "Invalid query parameter",
        "detail": "The filter[status] value is not a supported AI design status.",
        "recovery": "Correct the parameter named in parameter. Dates are YYYY-MM-DD in UTC and identifiers are integers between 1 and 2147483647.",
        "parameter": "filter[status]",
        "allowed_values": [
          "processing",
          "delivered",
          "refused",
          "failed"
        ]
      }
    }
  }
}
```
