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

# Get Flash Designs by Artist IDs

> Fetches flash designs for multiple artist IDs. Used by the explore page to show designs from filtered artists. Returns grouped results - one entry per artist with their flash designs.

## Overview

This endpoint fetches flash designs for multiple artist IDs in a single request. It's primarily used by the explore page to efficiently load designs from filtered artists.

## Key Features

* **Batch Processing**: Handles multiple artist IDs in one request
* **Chunked Queries**: Automatically handles Firestore's 10-item limit for `in` queries
* **Flexible Limiting**: Optional limit per artist (unlimited by default)
* **Availability Filtering**: Option to show only available designs
* **Grouped Results**: Returns data grouped by artist for easy processing

## Use Cases

* **Explore Page**: Display flash designs from artists in a specific area
* **Artist Discovery**: Show designs from multiple artists simultaneously
* **Marketplace Views**: Bulk loading of available designs

## Query Parameters

### Required Parameters

* `artistIds` (string): Comma-separated list of artist IDs
  * Example: `"artist1,artist2,artist3"`
  * No limit on the number of artist IDs

### Optional Parameters

* `limit` (integer): Number of designs per artist
  * Default: No limit (returns all designs)
  * Example: `3` (returns up to 3 designs per artist)
* `onlyAvailable` (boolean): Filter for available designs only
  * Default: `true`
  * Set to `false` to include unavailable designs

## Response Format

The endpoint returns an array of `ArtistFlashGroup` objects, where each group contains:

* `artistId`: The artist's unique identifier
* `designs`: Array of flash listings for that artist

Only artists with flash designs are included in the response.

## Performance Considerations

* **Efficient Querying**: Uses parallel chunked queries for scalability
* **Sorted Results**: Designs are sorted by order (newest first) within each artist group
* **Public Endpoint**: No authentication required, suitable for public discovery

## Example Usage

### Get all available designs from specific artists

```
GET /api/flash/by-artist-ids?artistIds=artist1,artist2,artist3&onlyAvailable=true
```

### Get limited designs per artist

```
GET /api/flash/by-artist-ids?artistIds=artist1,artist2&limit=5&onlyAvailable=true
```

### Include unavailable designs

```
GET /api/flash/by-artist-ids?artistIds=artist1&onlyAvailable=false
```

## Error Handling

* **400 Bad Request**: Missing or invalid `artistIds` parameter
* **500 Internal Server Error**: Database or server errors

The endpoint gracefully handles cases where some artists have no flash designs by simply excluding them from the results.


## OpenAPI

````yaml GET /flash/by-artist-ids
openapi: 3.1.0
info:
  title: Tatu API
  description: API documentation for Tatu's booking and artist management system
  version: 1.0.0
servers:
  - url: http://localhost:3000/api
    description: Development server
security: []
paths:
  /flash/by-artist-ids:
    get:
      summary: Get Flash Designs by Artist IDs
      description: >-
        Fetches flash designs for multiple artist IDs. Used by the explore page
        to show designs from filtered artists. Returns grouped results - one
        entry per artist with their flash designs.
      parameters:
        - name: artistIds
          in: query
          required: true
          description: Comma-separated list of artist IDs
          schema:
            type: string
            example: artist1,artist2,artist3
        - name: limit
          in: query
          required: false
          description: Number of designs per artist (optional, no limit if not provided)
          schema:
            type: integer
            minimum: 1
            example: 3
        - name: onlyAvailable
          in: query
          required: false
          description: Only return available designs
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Flash designs grouped by artist
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtistFlashGroup'
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: artistIds parameter is required
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Failed to fetch flash designs
components:
  schemas:
    ArtistFlashGroup:
      type: object
      required:
        - artistId
        - designs
      properties:
        artistId:
          type: string
          description: ID of the artist
        designs:
          type: array
          items:
            $ref: '#/components/schemas/FlashListing'
          description: Array of flash designs by this artist
      description: Grouped flash designs by artist
    FlashListing:
      type: object
      required:
        - id
        - artistId
        - artistName
        - artistUsername
        - price
        - size
        - styles
        - isAvailable
        - isVisible
        - order
        - createdAt
        - updatedAt
        - source
        - sourceData
      properties:
        id:
          type: string
          description: Unique identifier for the flash listing
        artistId:
          type: string
          description: Reference to artist who owns this flash
        artistName:
          type: string
          description: Denormalized artist name for performance
        artistUsername:
          type: string
          description: Denormalized artist username for discovery feeds
        price:
          $ref: '#/components/schemas/FlashPrice'
          description: Flash price information
        size:
          $ref: '#/components/schemas/FlashSize'
          description: Flash size information
        sessionDuration:
          $ref: '#/components/schemas/SessionDuration'
          description: Optional session duration estimate
        styles:
          type: array
          items:
            type: string
          description: Array of tattoo styles
        isAvailable:
          type: boolean
          description: Whether this flash is currently bookable
        isVisible:
          type: boolean
          description: Whether this flash is visible in listings
        viewCount:
          type: number
          description: Number of times this flash has been viewed
        bookmarkCount:
          type: number
          description: Number of users who bookmarked this flash
        createdAt:
          type: number
          description: Timestamp when flash was created
        updatedAt:
          type: number
          description: Timestamp when flash was last updated
        order:
          type: number
          description: Display order in artist's gallery
        tags:
          type: array
          items:
            type: string
          description: Optional tags for discovery/filtering
        notes:
          type: string
          description: Optional notes added by the artist
      allOf:
        - oneOf:
            - $ref: '#/components/schemas/InstagramSourceData'
            - $ref: '#/components/schemas/UploadSourceData'
            - $ref: '#/components/schemas/UrlSourceData'
    FlashPrice:
      oneOf:
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - fixed
              description: Fixed price type
            amount:
              type: string
              description: Fixed price amount (string for input handling)
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - range
              description: Range price type
            minAmount:
              type: string
              description: Minimum price amount (string for input handling)
            maxAmount:
              type: string
              description: Maximum price amount (string for input handling)
      description: Price can be either a single fixed amount or a range
    FlashSize:
      type: object
      required:
        - unit
      properties:
        minSize:
          type: string
          description: Minimum size (string for input handling)
        maxSize:
          type: string
          description: Maximum size (string for input handling)
        unit:
          type: string
          enum:
            - in
            - cm
          description: Size unit (inches or centimeters)
      description: Size dimensions in inches/cm
    SessionDuration:
      type: object
      required:
        - blocks
      properties:
        blocks:
          type: number
          description: Number of 30-minute blocks (e.g., 1 = 30min, 2 = 1hr)
      description: Session duration in 30-minute increments
    InstagramSourceData:
      type: object
      required:
        - source
        - sourceData
      properties:
        source:
          type: string
          enum:
            - instagram
          description: Source type
        sourceData:
          type: object
          required:
            - instagramId
            - permalink
            - mediaType
            - url
          properties:
            instagramId:
              type: string
              description: Instagram media ID
            permalink:
              type: string
              description: Instagram permalink URL
            caption:
              type: string
              description: Instagram media caption
            mediaType:
              type: string
              enum:
                - IMAGE
                - VIDEO
                - CAROUSEL_ALBUM
              description: Instagram media type
            url:
              type: string
              description: Instagram CDN URL (compliant with Meta's platform policy)
            thumbnailUrl:
              type: string
              description: Optional thumbnail URL
            urlRefreshedAt:
              type: number
              description: Timestamp when Instagram URL was last refreshed
            storageRef:
              type: string
              description: Legacy Firebase Storage reference
            fileSize:
              type: number
              description: Legacy file size in bytes
    UploadSourceData:
      type: object
      required:
        - source
        - sourceData
      properties:
        source:
          type: string
          enum:
            - upload
          description: Source type
        sourceData:
          type: object
          required:
            - originalFileName
            - fileSize
            - storageRef
            - url
          properties:
            originalFileName:
              type: string
              description: Original uploaded file name
            fileSize:
              type: number
              description: File size in bytes
            storageRef:
              type: string
              description: Firebase Storage reference
            url:
              type: string
              description: Firebase Storage URL
            thumbnailUrl:
              type: string
              description: Optional thumbnail URL
    UrlSourceData:
      type: object
      required:
        - source
        - sourceData
      properties:
        source:
          type: string
          enum:
            - url
          description: Source type
        sourceData:
          type: object
          required:
            - originalUrl
            - url
          properties:
            originalUrl:
              type: string
              description: Original source URL
            url:
              type: string
              description: Processed/cached URL
            thumbnailUrl:
              type: string
              description: Optional thumbnail URL

````