# POST 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.

- Source URL: https://www.signcustomiser.com/help/api/v3-post-create-an-ai-sign-design-source/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-post-create-an-ai-sign-design-source.md
- Group: AI sign designs
- Method: POST
- Path: /api/v3/ai-sign-design-sources
- Auth: Bearer token
- Required scopes: `ai_sign_designs:write`

## Body parameters

- filename (string, optional): No description provided.
- content_type (string, optional): No description provided.
- byte_size (integer, optional): No description provided.

## Request body example

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

## cURL example

```bash
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
}'
```

## Response examples

### 201 POST 201 example 1

```json
{
  "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"
  }
}
```

### 400 Missing idempotency key

```json
{
  "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"
}
```

### 401 Missing API key

```json
{
  "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"
}
```

### 403 Insufficient scope

```json
{
  "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"
}
```

### 404 Not released for this store

```json
{
  "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"
}
```

### 409 Idempotency conflict

```json
{
  "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"
}
```

### 422 File type not allowed

```json
{
  "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"
}
```

### 429 Upload target budget exhausted

```json
{
  "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"
}
```

### 503 AI sign designer turned off

```json
{
  "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"
}
```