AI sign designs

Create an AI sign design source

Copy page

Declares a raster image for the AI sign designer and returns a short-lived presigned target to send its bytes to. Requires ai_sign_designs:write and an Idempotency-Key.

POST/api/v3/ai-sign-design-sources

Create an AI sign design source

Declares a raster image for the AI sign designer and returns a short-lived presigned target to send its bytes to. Requires `ai_sign_designs:write` and an `Idempotency-Key`. It does not need any customiser scope, and it spends no credit. Declare PNG (`image/png`), JPEG (`image/jpeg`, filename `.jpg`, `.jpeg` or `.jfif`) or WebP (`image/webp`) at no more than 5 MiB. A filename extension that does not match the content type, or any other type, answers 422 `source_type_not_allowed` with the accepted values. A larger declaration answers 422 `source_size_exceeded` with `max_byte_size`. There is no multipart, base64 or remote URL input: the bytes travel only through the upload target. Send the file as the raw body of a request that uses the target's `method` and `url` and every header it lists. The target expires about ten minutes after it is issued and is returned only by this response. An idempotent replay returns the recorded body with `upload_target` set to null, so a lost target needs a new source with a new key. Poll `GET /api/v3/ai-sign-design-sources/{source_id}` until `status` is `uploaded`. `uploaded` means the bytes arrived. It does not mean they passed verification. The real bytes are checked when a design uses the source: exact byte size, image signature, dimensions, decoded pixels and a complete decode, on a private copy that a later PUT cannot change. The source belongs to the API key, or the AI agent connection, that created it. While the AI sign designer is turned off for the store this answers 503 `ai_sign_designer_unavailable`; read the capabilities and try again when `available` is true.

Create an AI sign design source

Overview

It does not need any customiser scope, and it spends no credit. Declare PNG (image/png), JPEG (image/jpeg, filename .jpg, .jpeg or .jfif) or WebP (image/webp) at no more than 5 MiB. A filename extension that does not match the content type, or any other type, answers 422 source_type_not_allowed with the accepted values. A larger declaration answers 422 source_size_exceeded with max_byte_size. There is no multipart, base64 or remote URL input: the bytes travel only through the upload target. Send the file as the raw body of a request that uses the target's method and url and every header it lists. The target expires about ten minutes after it is issued and is returned only by this response. An idempotent replay returns the recorded body with upload_target set to null, so a lost target needs a new source with a new key. Poll GET/api/v3/ai-sign-design-sources/{source_id} until status is uploaded. uploaded means the bytes arrived. It does not mean they passed verification. The real bytes are checked when a design uses the source: exact byte size, image signature, dimensions, decoded pixels and a complete decode, on a private copy that a later PUT cannot change. The source belongs to the API key, or the AI agent connection, that created it. While the AI sign designer is turned off for the store this answers 503 ai_sign_designer_unavailable; read the capabilities and try again when available is true.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: ai_sign_designs:write

Request body

filenamestringbody

content_typestringbody

byte_sizeintegerbody

Request body example

{
  "filename": "shopfront-logo.png",
  "content_type": "image/png",
  "byte_size": 482133
}

Create an AI sign design source

curl https://web.signcustomiser.com/api/v3/ai-sign-design-sources \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "filename": "shopfront-logo.png",
  "content_type": "image/png",
  "byte_size": 482133
}'

{
  "data": {
    "object": "ai_sign_design_source",
    "id": "aisrc_9f2c4b7ad13e6058ba41cd4201",
    "filename": "shopfront-logo.png",
    "content_type": "image/png",
    "byte_size": 482133,
    "status": "pending",
    "verification_failure_code": null,
    "width_px": null,
    "height_px": null,
    "expires_at": "2026-10-21T09:30:00Z",
    "consumed_at": null,
    "created_at": "2026-10-20T09:30:00Z",
    "upload_target": {
      "method": "PUT",
      "url": "https://uploads.example.invalid/ai-sign-design-source-target-example",
      "headers": {},
      "expires_at": "2026-10-20T09:40:00Z"
    }
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/ai-sign-design-sources/aisrc_9f2c4b7ad13e6058ba41cd4201",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_idempotency_key",
  "title": "Missing idempotency key",
  "status": 400,
  "code": "missing_idempotency_key",
  "detail": "Provide an Idempotency-Key header for this write.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "Provide a store API key as a bearer token.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the ai_sign_designs:write scope.",
  "required_scopes": [
    "ai_sign_designs:write"
  ],
  "granted_scopes": [
    "ai_sign_designs:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "The requested endpoint does not exist. The API reference lists every available operation: https://www.signcustomiser.com/help/api/",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict",
  "title": "Idempotency key conflict",
  "status": 409,
  "code": "idempotency_key_conflict",
  "detail": "This Idempotency-Key was already used for a different request body on this operation.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/source_type_not_allowed",
  "title": "Source type not allowed",
  "status": 422,
  "code": "source_type_not_allowed",
  "detail": "AI sign design sources do not accept image/svg+xml files.",
  "errors": [
    {
      "pointer": "/content_type",
      "code": "unsupported_value",
      "detail": "AI sign design sources do not accept image/svg+xml files.",
      "allowed_values": [
        "image/png",
        "image/jpeg",
        "image/webp"
      ]
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "You have exceeded the request limit for this API key.",
  "retry_after": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/ai_sign_designer_unavailable",
  "title": "AI sign designer unavailable",
  "status": 503,
  "code": "ai_sign_designer_unavailable",
  "detail": "The AI sign designer is turned off for this store. Sources and designs that already exist stay readable. Read GET /api/v3/ai-sign-design-capabilities and try again when available is true.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}