Diamond Painting Converter API — API Evangelist enhancements

overlay: 1.0.0
info:
  title: Diamond Painting Converter API — API Evangelist enhancements
  version: '2026-11-05'
  x-provenance:
    method: generated
    generated: '2026-11-05'
    source: https://diamondpaintingconverter.com/api/docs
extends: ../openapi/_ae-authored/diamondpaintingconverter-com-openapi-generated.yml
actions:
- target: $.paths['/api/v1/preview'].post
  description: Summary, idempotency, wait limit and documented errors from the API docs.
  update:
    summary: Request a diamond painting preview
    description: Upload a photo (multipart; JPEG, PNG or WebP, max 20 MB) and receive a diamond painting preview and size recommendation. Use wait (max 10 seconds) to wait synchronously; on 202 Accepted, poll GET /api/v1/jobs/{job_id}. Send an Idempotency-Key header to prevent duplicate processing — the same key with the same parameters returns the original job, different parameters return 409; keys expire after 24 hours.
    x-idempotency:
      header: Idempotency-Key
      ttl: 24 hours
      conflict_status: 409
    x-rate-limit-units: 1 + ceil(min(allowed_sizes, 50) / 10)
- target: $.paths['/api/v1/preview'].post.parameters
  description: Document the Idempotency-Key header.
  update:
  - name: Idempotency-Key
    in: header
    required: false
    description: Unique key per cart item/request; expires after 24 hours.
    schema:
      type: string
- target: $.paths['/api/v1/preview'].post.responses
  description: Responses documented on the API docs page.
  update:
    '202':
      description: Accepted — processing continues; poll GET /api/v1/jobs/{job_id}.
    '409':
      description: Idempotency key reused with different parameters.
    '422':
      description: invalid_mime, file_too_large or invalid_parameter.
    '429':
      description: rate_limit_exceeded — includes Retry-After, X-RateLimit-Used-Units, X-RateLimit-Remaining, X-RateLimit-Reset.
- target: $.paths['/api/v1/batch-preview'].post
  description: Summary and limits from the API docs.
  update:
    summary: Group single previews into a batch
    description: Group previously created single previews (job_ids) into a batch; max 50 items per batch (400 when exceeded). Retrieve items with cursor pagination at GET /api/v1/jobs/{batch_id}/items?cursor=0.
- target: $.paths['/api/v1/jobs/{jobid}'].get
  description: Summary and status lifecycle from the API docs.
  update:
    summary: Get job status
    description: Poll a preview or batch job. Statuses pending → processing → completed; processing errors return an error envelope with HTTP 500 and job null.