AI sign designs

Create an AI sign design source

Copy page

Declares an image, SVG or PDF 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 an image, SVG or PDF 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`), WebP (`image/webp`), AVIF (`image/avif`) or SVG (`image/svg+xml`) at no more than 5 MiB, or PDF (`application/pdf`) at no more than 25 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`. The job converts an AVIF, an SVG, or the first page of a PDF, to an image before the designer reads it. 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. Creating a job checks the exact byte size, the file signature and, for an image, the dimensions in its header, on a private copy that a later PUT cannot change. A failed check answers 422 `source_rejected` at once. The job then converts an SVG or a PDF to an image and decodes the result completely. If that fails, the job fails with `error.code` `source_rejected`, no credit is charged, and the source becomes `rejected`. 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), WebP (image/webp), AVIF (image/avif) or SVG (image/svg+xml) at no more than 5 MiB, or PDF (application/pdf) at no more than 25 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. The job converts an AVIF, an SVG, or the first page of a PDF, to an image before the designer reads it. 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. Creating a job checks the exact byte size, the file signature and, for an image, the dimensions in its header, on a private copy that a later PUT cannot change. A failed check answers 422 source_rejected at once. The job then converts an SVG or a PDF to an image and decodes the result completely. If that fails, the job fails with error.code source_rejected, no credit is charged, and the source becomes rejected. 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/gif files.",
  "errors": [
    {
      "pointer": "/content_type",
      "code": "unsupported_value",
      "detail": "AI sign design sources do not accept image/gif files.",
      "allowed_values": [
        "image/png",
        "image/jpeg",
        "image/webp",
        "image/avif",
        "image/svg+xml",
        "application/pdf"
      ]
    }
  ],
  "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"
}