Create Prints Product discovery API

openapi: 3.2.0
info:
  title: Createprints Ai Product discovery API
  version: 1.1.0
  contact:
    name: Create Prints support
    url: https://www.createprints.ai/contact
  license:
    name: Proprietary
    url: https://www.createprints.ai/terms
  description: 'Operations tagged Product discovery across 2 of this provider''s published API definitions: createprints-ai-openapi.json, createprints-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.createprints.ai
  description: Create Prints API origin
tags:
- name: Product discovery
  description: Read print variants, generation dimensions, frames, prices, and postage estimates.
paths:
  /api/agent-print-options:
    get:
      operationId: listAgentPrintOptions
      summary: List purchasable physical print variants
      description: 'Returns canonical `productVariantId` values, print dimensions, format, optional extras, compatible generation size, frame choices, product price, and a single-item postage estimate. That estimate is not final basket postage: checkout recalculates postage for quantity and multi-item baskets. Use `generation.imageModelSize` when creating artwork for the selected variant.'
      tags:
      - Product discovery
      security: []
      parameters:
      - name: country
        in: query
        description: Supported destination market. `GB` returns GBP; `US` returns USD.
        schema:
          type: string
          enum:
          - GB
          - US
          default: GB
      responses:
        '200':
          description: Currently purchasable physical print variants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintOptions'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
  /api/prints:
    get:
      operationId: searchPrints
      summary: Search the public print catalogue
      description: Searches every published print by free text and by any combination of attributes. Values within one attribute are OR-ed and attributes are AND-ed together, so `colour=Blue&colour=Green&room=Bedroom` means (blue or green) and bedroom. Each attribute accepts repeated parameters or a comma-separated list, and matches case-insensitively with dashes, underscores and spaces treated alike, so `red-orange` and `Red Orange` are the same value. Set `facets=1` to receive the remaining attribute values with the count of prints each would yield, which is the reliable way to narrow a search without guessing at vocabulary. Use the returned `id` with the checkout and print-option endpoints.
      tags:
      - Product discovery
      security: []
      parameters:
      - name: q
        in: query
        description: Free text over title, keywords, colour and description. Terms match at the start of a word, so prefixes work and mid-word noise does not. Every term must match, so more words narrow the result.
        schema:
          type: string
      - name: colour
        in: query
        description: Colour category, e.g. Blue, Orange, Grey. `color` is accepted too.
        schema:
          type: string
      - name: room
        in: query
        description: Recommended room, e.g. Bedroom, Living Room, Home Office.
        schema:
          type: string
      - name: trait
        in: query
        description: Mood, e.g. Serene, Bold, Grounded. `mood` is accepted too.
        schema:
          type: string
      - name: impact
        in: query
        description: Visual impact, e.g. Subtle, Moderate, Dramatic.
        schema:
          type: string
      - name: keyword
        in: query
        description: Subject or style keyword, e.g. botanical, minimal.
        schema:
          type: string
      - name: palette
        in: query
        description: Any named colour present in the artwork, from its extracted palette or its colour category, e.g. navy, sage, blue. Broader than `colour`, which is the single dominant category.
        schema:
          type: string
      - name: featured
        in: query
        description: Set to 1 to return only prints marked featured.
        schema:
          type: string
          enum:
          - '1'
          - 'true'
      - name: similarTo
        in: query
        description: A print id. Returns prints sharing any of its colour, room, mood, impact, keyword or palette, best match first, never the print itself. This is how to answer "more like this"; the attribute filters AND together and cannot express it. Composes with the other filters.
        schema:
          type: string
          format: uuid
      - name: sort
        in: query
        description: Defaults to similar when `similarTo` is given, relevance when `q` is given, and newest otherwise.
        schema:
          type: string
          enum:
          - relevance
          - newest
          - oldest
          - featured
          - similar
      - name: limit
        in: query
        description: Prints per response, 1-96.
        schema:
          type: integer
          minimum: 1
          maximum: 96
          default: 24
      - name: offset
        in: query
        description: Rows to skip. Page with `offset += limit` while `hasMore` is true.
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: page
        in: query
        description: Shorthand for `offset = (page - 1) * limit`. Ignored when `offset` is given.
        schema:
          type: integer
          minimum: 1
      - name: facets
        in: query
        description: Set to 1 to include the available attribute values and their counts.
        schema:
          type: string
          enum:
          - '1'
          - 'true'
      responses:
        '200':
          description: Matching prints, the total match count, and optionally the facet counts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintSearchResult'
        '503':
          description: The catalogue is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
  /api/print-sizes:
    get:
      operationId: listPrintSizes
      summary: List unframed print sizes
      description: Returns the legacy unframed-print size list in GBP. New agent integrations should normally use `/api/agent-print-options`, which also supplies generation dimensions, formats, frames, currency selection, and postage estimates.
      tags:
      - Product discovery
      security: []
      responses:
        '200':
          description: Available unframed print sizes and GBP prices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrintSizes'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
  /api/frame-options:
    get:
      operationId: listFrameOptions
      summary: List frame colours
      description: 'Returns frame-option identifiers and labels. `frameOptionId` is required only when the chosen product variant has `requiresFrameOption: true`.'
      tags:
      - Product discovery
      security: []
      responses:
        '200':
          description: Available frame colour options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrameOptions'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
components:
  schemas:
    FrameOptions:
      type: object
      required:
      - frameOptions
      properties:
        frameOptions:
          type: array
          items:
            $ref: '#/components/schemas/Option'
    CataloguePrint:
      type: object
      required:
      - id
      - imagePaths
      properties:
        id:
          type: string
          format: uuid
          description: Use this as `jobId` when creating a checkout.
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        imagePaths:
          type: array
          items:
            type: string
            format: uri
        colorCategory:
          type:
          - string
          - 'null'
        recommendedRoom:
          type: array
          items:
            type: string
        colorPsychologyPrimaryTrait:
          type:
          - string
          - 'null'
        colorPsychologyImpactLevel:
          type:
          - string
          - 'null'
        keywords:
          type: array
          items:
            type: string
        paletteColors:
          type: array
          items:
            type: string
          description: Named colours extracted from the artwork. The `palette` filter also matches on colorCategory, so it can match a print whose list here is empty.
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
        width:
          type:
          - integer
          - 'null'
        height:
          type:
          - integer
          - 'null'
        aspectRatio:
          type:
          - number
          - 'null'
        orientation:
          type:
          - string
          - 'null'
          enum:
          - portrait
          - landscape
          - square
          - null
    PrintOptions:
      type: object
      required:
      - currency
      - usage
      - productVariants
      properties:
        currency:
          type: string
          enum:
          - GBP
          - USD
        usage:
          type: string
        productVariants:
          type: array
          items:
            $ref: '#/components/schemas/ProductVariant'
    PrintSizes:
      type: object
      required:
      - sizes
      properties:
        sizes:
          type: array
          items:
            $ref: '#/components/schemas/PrintSize'
    PrintSize:
      type: object
      required:
      - id
      - productVariantId
      - sizeOptionId
      - name
      - price
      - priceFormatted
      properties:
        id:
          type: string
          format: uuid
        productVariantId:
          type: string
          format: uuid
        sizeOptionId:
          type: string
          format: uuid
        name:
          type: string
        price:
          type: number
          minimum: 0
        priceFormatted:
          type: string
    GenerationSpec:
      type: object
      required:
      - aspect
      - imageModelSize
      - promptSizeId
      properties:
        aspect:
          $ref: '#/components/schemas/Aspect'
        imageModelSize:
          type: string
          examples:
          - 1536x1536
          - 1024x1536
          - 1536x1024
        promptSizeId:
          type: integer
          enum:
          - 1
          - 2
          - 3
    ProductVariant:
      type: object
      required:
      - productVariantId
      - productId
      - sizeOptionId
      - size
      - format
      - extra
      - generation
      - requiresFrameOption
      - frameOptions
      - price
      - priceFormatted
      - shippingPrice
      - shippingPriceFormatted
      - estimatedCheckoutTotal
      - estimatedCheckoutTotalFormatted
      - shipping
      - checkout
      properties:
        productVariantId:
          type: string
          format: uuid
        productId:
          type:
          - string
          - integer
        sku:
          type:
          - string
          - 'null'
        sizeOptionId:
          type: string
          format: uuid
          description: Legacy alias; use `productVariantId`.
        size:
          $ref: '#/components/schemas/Option'
        format:
          $ref: '#/components/schemas/Option'
        extra:
          oneOf:
          - $ref: '#/components/schemas/Option'
          - type: 'null'
        generation:
          $ref: '#/components/schemas/GenerationSpec'
        requiresFrameOption:
          type: boolean
        frameOptions:
          type: array
          items:
            $ref: '#/components/schemas/Option'
        price:
          type: number
          minimum: 0
        priceFormatted:
          type: string
        shippingPrice:
          type:
          - number
          - 'null'
          minimum: 0
        shippingPriceFormatted:
          type:
          - string
          - 'null'
        estimatedCheckoutTotal:
          type:
          - number
          - 'null'
          minimum: 0
        estimatedCheckoutTotalFormatted:
          type:
          - string
          - 'null'
        shipping:
          type: object
          required:
          - price
          - priceFormatted
          - includedInPrice
          - note
          properties:
            price:
              type:
              - number
              - 'null'
            priceFormatted:
              type:
              - string
              - 'null'
            includedInPrice:
              type: boolean
              const: false
            note:
              type: string
        checkout:
          type: object
          required:
          - productVariantId
          - frameOptionId
          properties:
            productVariantId:
              type: string
              format: uuid
            frameOptionId:
              type:
              - string
              - 'null'
    Error:
      type: object
      description: Errors use `error`; some endpoints also return a stable `code`, validation `details`, or `retryable` hint.
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: array
          items:
            type: string
        retryable:
          type: boolean
      additionalProperties: true
    Aspect:
      type: string
      enum:
      - square
      - portrait
      - landscape
    Option:
      type: object
      required:
      - id
      - value
      - name
      properties:
        id:
          type:
          - integer
          - string
        value:
          type:
          - string
          - 'null'
        name:
          type: string
    FacetOption:
      type: object
      required:
      - value
      - slug
      - count
      - selected
      properties:
        value:
          type: string
          description: Pass this back as the filter value.
        slug:
          type: string
        count:
          type: integer
          minimum: 0
          description: Prints this value would yield alongside the other filters already applied. Zero means the combination is empty.
        selected:
          type: boolean
    PrintSearchResult:
      type: object
      required:
      - prints
      - total
      - limit
      - offset
      - hasMore
      - sort
      properties:
        prints:
          type: array
          items:
            $ref: '#/components/schemas/CataloguePrint'
        total:
          type: integer
          minimum: 0
          description: Full match count, so a pager needs no second request.
        limit:
          type: integer
        offset:
          type: integer
        hasMore:
          type: boolean
        sort:
          type: string
          enum:
          - relevance
          - newest
          - oldest
          - featured
          - similar
        q:
          type:
          - string
          - 'null'
        appliedFilters:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        facets:
          $ref: '#/components/schemas/PrintSearchFacets'
        truncated:
          type: boolean
          description: Present only when the catalogue outgrew the search index and the answer is partial.
    PrintSearchFacets:
      type: object
      description: Available values per attribute. A facet's counts ignore that facet's own selection, so a second value can always be added to widen the search.
      properties:
        colour:
          type: array
          items:
            $ref: '#/components/schemas/FacetOption'
        room:
          type: array
          items:
            $ref: '#/components/schemas/FacetOption'
        trait:
          type: array
          items:
            $ref: '#/components/schemas/FacetOption'
        impact:
          type: array
          items:
            $ref: '#/components/schemas/FacetOption'
        keyword:
          type: array
          items:
            $ref: '#/components/schemas/FacetOption'
        palette:
          type: array
          items:
            $ref: '#/components/schemas/FacetOption'
  securitySchemes:
    agentApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Create Prints account API key beginning with `cp_`. Required scopes vary by operation.
    agentBearer:
      type: http
      scheme: bearer
      description: Account API key (`cp_…`) or MCP OAuth token (`cp_mcp_access_…`) in Authorization.
    userSessionBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Signed-in Create Prints user-session token; supported only where this scheme is listed.
    oauth2:
      type: oauth2
      description: Create Prints OAuth 2.0 authorization-code flow with PKCE for MCP and agent clients.
      flows:
        authorizationCode:
          authorizationUrl: https://api.createprints.ai/api/oauth/authorize
          tokenUrl: https://api.createprints.ai/api/oauth/token
          scopes:
            artwork:create: Create, import, and retry artwork jobs.
            artwork:read: Read and list artwork jobs.
            print_options:read: Read print variants, frames, prices, and postage estimates.
            checkout:create: Create checkout sessions and retry production submission.
            checkout:read: Read checkout, fulfilment, and shipment status.
            orders:read: Read orders and, on the current credit endpoint, generation credits.
externalDocs:
  description: Create Prints developer resources
  url: https://www.createprints.ai/developers
x-refined-from:
- createprints-ai-openapi.json
- createprints-ai-openapi.yml