> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixy.art/llms.txt
> Use this file to discover all available pages before exploring further.

# List designs

> Browse saved designs with optional embed user filtering.



## OpenAPI

````yaml /openapi.yaml get /api/v1/designs
openapi: 3.1.0
info:
  title: Pixy Public API
  version: 1.0.0
  description: >
    Public API for validating bearer API keys, browsing and duplicating saved

    designs, and generating rendered design output from a Pixy design or
    template.


    The first endpoint in this reference is the API key validation endpoint used
    by

    integrations such as Zapier. Design, template, duplicate, and generate
    endpoints

    follow after it.


    This specification documents the currently exposed public endpoints in

    `apps/pixy-web/app/api/(public)`.
servers:
  - url: https://app.pixy.art
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Auth
    description: Resolve the current user for a Pixy bearer API key.
  - name: Generate
    description: Render design output from a Pixy design or template.
  - name: Templates
    description: Browse public Pixy templates.
  - name: Designs
    description: Browse designs saved in your Pixy organization.
paths:
  /api/v1/designs:
    get:
      tags:
        - Designs
      summary: List designs
      description: >
        Returns saved Pixy designs for the authenticated organization.


        When designs are created through the Embed editor with the optional
        `userId`,

        pass the same `userId` here to return only designs associated with that

        embedder user.
      operationId: listDesigns
      parameters:
        - in: query
          name: userId
          required: false
          schema:
            type: string
            maxLength: 128
          description: >-
            Optional embedder-provided user identifier to filter designs created
            or opened with the same Embed `userId`.
          example: user_123
        - in: query
          name: search
          required: false
          schema:
            type: string
          description: Search designs by name.
          example: campaign
        - in: query
          name: page
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Zero-based page index.
          example: 0
        - in: query
          name: perPage
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 24
          description: Number of designs to return per page.
          example: 24
      responses:
        '200':
          description: Successfully returned designs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DesignListResponse'
              examples:
                success:
                  value:
                    data:
                      - id: des_123
                        name: Summer campaign
                        thumbnail: https://assets.example.com/designs/summer.png
                        createdAt: '2026-05-11T10:00:00.000Z'
                        updatedAt: '2026-05-11T10:05:00.000Z'
                        userId: user_123
                        size:
                          width: 1080
                          height: 1080
                    total: 3
                    page: 0
                    perPage: 24
                    userId: user_123
                    search: ''
        '400':
          description: The request parameters are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRequest:
                  value:
                    message: Failed to load designs.
        '401':
          description: The bearer token is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  value:
                    message: Unauthorized
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: javascript
          label: npm / @pixy-art/sdk
          source: |
            import { Pixy } from '@pixy-art/sdk'

            const pixy = new Pixy({
              apiKey: 'YOUR_API_KEY',
            })

            const designs = await pixy.designs.list({
              // Optional: filter designs created with this Embed userId.
              userId: 'YOUR_APP_USER_ID',
              perPage: 24,
            })

            console.log(designs.data)
components:
  schemas:
    DesignListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - total
        - page
        - perPage
        - userId
        - search
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DesignListItem'
        total:
          type: integer
          description: Total matching designs.
        page:
          type: integer
          description: Zero-based page index.
        perPage:
          type: integer
          description: Page size used for the response.
        userId:
          type:
            - string
            - 'null'
          description: Embedder-provided user id filter, when supplied.
        search:
          type: string
          description: Normalized search text.
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - message
      properties:
        message:
          type: string
    DesignListItem:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - thumbnail
        - createdAt
        - updatedAt
        - userId
        - size
      properties:
        id:
          type: string
          description: Design identifier.
        name:
          type:
            - string
            - 'null'
          description: Design name.
        thumbnail:
          type:
            - string
            - 'null'
          format: uri
          description: Design thumbnail URL.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        userId:
          type:
            - string
            - 'null'
          description: Embedder-provided user id saved on this design.
        size:
          type: object
          additionalProperties: false
          required:
            - width
            - height
          properties:
            width:
              type:
                - integer
                - 'null'
              description: Design width in pixels.
            height:
              type:
                - integer
                - 'null'
              description: Design height in pixels.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Organization API key passed as a bearer token.

````