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

# Search public templates

> Browse public Pixy templates with optional search and pagination.



## OpenAPI

````yaml /openapi.yaml get /api/v1/templates
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/templates:
    get:
      tags:
        - Templates
      summary: Search public templates
      description: >
        Returns public Pixy templates that can be used as starting points for
        generation

        or for opening a new design as a copy.


        When using a public template `id` with the Embed editor, pass it as
        `designId`

        with `openAsCopy: true`. Public templates cannot be embedded directly.
      operationId: searchPublicTemplates
      parameters:
        - in: query
          name: search
          required: false
          schema:
            type: string
          description: Search public templates by name or keyword.
          example: social
        - 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 templates to return per page.
          example: 24
        - in: query
          name: promoted
          required: false
          schema:
            type: boolean
          description: Optional filter for promoted templates.
          example: true
        - in: query
          name: orderBy
          required: false
          schema:
            type: string
            enum:
              - latest
              - oldest
            default: latest
          description: >-
            Sort templates. `latest` returns recently updated templates first.
            `oldest` returns oldest created templates first.
          example: oldest
      responses:
        '200':
          description: Successfully returned public templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicTemplateSearchResponse'
              examples:
                success:
                  value:
                    data:
                      - id: cmmtpl123
                        name: Sporty Flash Sale Social Media Post
                        thumbnail: https://assets.example.com/templates/flash-sale.png
                        category: Social media
                        size:
                          width: 1600
                          height: 900
                        orientation: Landscape
                        fonts:
                          - Anton
                          - Plus Jakarta Sans
                        formats:
                          - jpeg
                          - png
                          - pdf
                    total: 125
                    page: 0
                    perPage: 24
                    search: social
        '400':
          description: The request parameters are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidRequest:
                  value:
                    message: Failed to load public templates.
        '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 templates = await pixy.templates.list({
              search: 'social',
              promoted: true,
              orderBy: 'oldest',
              perPage: 24,
            })

            console.log(templates.data)
components:
  schemas:
    PublicTemplateSearchResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - total
        - page
        - perPage
        - search
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicTemplateItem'
        total:
          type: integer
          description: Total matching templates.
        page:
          type: integer
          description: Zero-based page index.
        perPage:
          type: integer
          description: Page size used for the response.
        search:
          type: string
          description: Normalized search text.
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - message
      properties:
        message:
          type: string
    PublicTemplateItem:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - thumbnail
        - category
        - size
        - orientation
        - fonts
        - formats
      properties:
        id:
          type: string
          description: Public template identifier.
        name:
          type:
            - string
            - 'null'
          description: Template name.
        thumbnail:
          type:
            - string
            - 'null'
          format: uri
          description: Public thumbnail URL for the template preview.
        category:
          type:
            - string
            - 'null'
          description: Template category label.
          example: Social media
        size:
          type: object
          additionalProperties: false
          required:
            - width
            - height
          properties:
            width:
              type:
                - integer
                - 'null'
              description: Template width in pixels.
            height:
              type:
                - integer
                - 'null'
              description: Template height in pixels.
          description: Template dimensions.
        orientation:
          type:
            - string
            - 'null'
          enum:
            - Landscape
            - Portrait
            - Square
            - null
          description: Template orientation.
        fonts:
          type: array
          description: Font family names used by the template.
          items:
            type: string
          example:
            - Anton
            - Plus Jakarta Sans
        formats:
          type: array
          description: Supported export format labels.
          items:
            type: string
            enum:
              - jpeg
              - png
              - pdf
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Organization API key passed as a bearer token.

````