Spotlights Admin API

The Spotlights Admin API allows gallery administrators to feature individual artists on the homepage. Spotlights can be scheduled with publish and expiry dates.

Authentication

Requires Supabase authentication with admin role:

Authorization: Bearer <access_token>

---

Endpoints

List Spotlights

Retrieves all artist spotlights.

Endpoint: GET /api/admin/spotlights

Authentication: Required (admin only)

Query Parameters:

Parameter	Type	Description
is_active	boolean	Filter by active status
current	boolean	Show only currently published spotlights

Response:

{
  "spotlights": [
    {
      "id": "spot_001",
      "orgId": "org_abc",
      "title": "Artist Spotlight: Jane Smith",
      "description": "Discover Jane's unique abstract expressionism style",
      "featuredImage": "https://...",
      "isActive": true,
      "publishedAt": "2024-01-01T00:00:00Z",
      "expiresAt": "2024-01-31T23:59:59Z",
      "organization": {
        "name": "Jane Smith Studio",
        "slug": "jane-smith"
      },
      "createdAt": "2024-12-28T10:00:00Z"
    }
  ]
}

Example Request:

curl "https://gallery.artbase.studio/api/admin/spotlights?current=true" \
  -H "Authorization: Bearer <admin_token>"

---

Create Spotlight

Creates a new artist spotlight.

Endpoint: POST /api/admin/spotlights

Request Body:

{
  "orgId": "org_abc",
  "title": "Artist Spotlight: Jane Smith",
  "description": "Discover Jane's unique abstract expressionism style",
  "featuredImage": "https://cdn.example.com/jane-feature.jpg",
  "isActive": true,
  "publishedAt": "2024-03-01T00:00:00Z",
  "expiresAt": "2024-03-31T23:59:59Z"
}

Request Parameters:

Field	Type	Required	Description
orgId	string	Yes	Artist organization UUID
title	string	Yes	Spotlight headline
description	string	No	Spotlight description/bio
featuredImage	string	No	Feature image URL
isActive	boolean	No	Active status (default: true)
publishedAt	string	No	ISO 8601 publish date (default: now)
expiresAt	string	No	ISO 8601 expiry date

Response:

{
  "spotlight": {
    "id": "spot_002",
    "orgId": "org_abc",
    "title": "Artist Spotlight: Jane Smith",
    "isActive": true,
    "publishedAt": "2024-03-01T00:00:00Z",
    "createdAt": "2024-02-28T14:00:00Z"
  }
}

Example Request:

curl -X POST https://gallery.artbase.studio/api/admin/spotlights \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_abc",
    "title": "Meet the Artist: Jane Smith",
    "description": "Jane creates stunning abstract paintings...",
    "publishedAt": "2024-03-01T00:00:00Z",
    "expiresAt": "2024-03-31T23:59:59Z"
  }'

---

Update Spotlight

Updates an existing spotlight.

Endpoint: PATCH /api/admin/spotlights/{id}

Request Body (all fields optional):

{
  "title": "Updated Title",
  "description": "Updated description",
  "isActive": false,
  "expiresAt": "2024-04-30T23:59:59Z"
}

Response:

{
  "spotlight": {
    "id": "spot_001",
    "title": "Updated Title",
    "updatedAt": "2024-03-15T12:00:00Z"
  }
}

---

Delete Spotlight

Deletes a spotlight.

Endpoint: DELETE /api/admin/spotlights/{id}

Response:

{
  "success": true
}

---

Scheduling

Publish Dates

Control when spotlights appear:

• publishedAt: Spotlight visible from this date forward
• expiresAt: Spotlight hidden after this date
• isActive: Manual override (can deactivate before expiry)

Examples

Immediate publish:

{
  "publishedAt": "2024-03-01T00:00:00Z",
  "expiresAt": null  // No expiry
}

Scheduled spotlight:

{
  "publishedAt": "2024-04-01T00:00:00Z",  // Starts April 1
  "expiresAt": "2024-04-30T23:59:59Z"    // Ends April 30
}

Month-long feature:

{
  "publishedAt": "2024-03-01T00:00:00Z",
  "expiresAt": "2024-03-31T23:59:59Z"
}

---

Best Practices

Spotlight Rotation

• Monthly rotation: Feature 1-2 artists per month
• Overlap: Slight overlap for smooth transitions
• Diversity: Rotate between styles, mediums, price points

Content Guidelines

Titles:

• ✅ "Artist Spotlight: Jane Smith"
• ✅ "Meet the Artist: Bob Johnson"
• ✅ "Featured Creator: Alice Chen"
• ❌ "Artist 1"

Descriptions:

• Introduce the artist (50-150 words)
• Highlight unique style or story
• Mention notable works or achievements
• Include call-to-action ("Explore their work")

Images:

• High-quality artist photo or signature work
• 1200x630px recommended
• Professional, well-lit, representative

---

Next Steps

🎨 Collections API

Curate product collections

📊 Analytics API

Gallery performance metrics