Developer Docs

Scene Pack API

Fetch public Scene Packs, images, and product catalog data via REST. Authenticate with an API key, browse the interactive reference, or copy a code snippet below.

API Reference

Interactive Explorer

Browse all endpoints, try live requests, and inspect response schemas with the Swagger UI.

Open Swagger UI

OpenAPI JSON Spec

AI-ready

Feed this URL into ChatGPT, Claude, Cursor, or Copilot to generate type-safe clients instantly.

Quick Start

Fetch your first scene pack in three steps:

  1. 1 Sign up and generate an API key in Dashboard → API Keys
  2. 2 Send a GET request to /api/v1/scene-packs with your key in the Authorization header
  3. 3 Use the returned images and product_data to power your store, demo, or mockup
curl — minimal example
# List active categories (no auth needed)
curl https://scenesku.com/api/v1/categories

# List public scene packs
curl https://scenesku.com/api/v1/scene-packs \
  -H "Authorization: Bearer $SCENESKU_API_KEY"

# Get a specific pack by ID
curl https://scenesku.com/api/v1/scene-packs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $SCENESKU_API_KEY"

Authentication

Bearer Token (API Key)

Every API request must include your API key as a bearer token in the Authorization header. Create and manage keys in Dashboard → API Keys.

Authorization: Bearer YOUR_SCENESKU_API_KEY
Note: Requests without a valid API key return 401 Unauthorized. Keep your key secret and rotate it from the dashboard if compromised.

List Categories

GET /api/v1/categories

Returns all active categories sorted by display order then name. Use these slugs with the category filter on the scene packs endpoint or browse packs directly via the category route below. No authentication required.

Example response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Electronics",
      "slug": "electronics",
      "description": "Consumer electronics and gadgets",
      "sort_order": 0
    },
    {
      "id": "e5f6g7h8-...",
      "name": "Fashion & Apparel",
      "slug": "fashion-apparel",
      "description": null,
      "sort_order": 1
    }
  ]
}

Scene Packs by Category

GET /api/v1/categories/:slug/scene-packs

Returns published scene packs tagged with the given category slug. Pagination and plan behaviour is identical to the List Scene Packs endpoint.

Path parameters

slug string required

Category slug from the List Categories endpoint (e.g. electronics). Returns 404 if the slug is not found or inactive.

Query parameters

page integer default: 1

Page number (Pro plan only, minimum 1).

per_page integer default: 20

Results per page, maximum 100 (Pro plan only).

Example

curl https://scenesku.com/api/v1/categories/electronics/scene-packs \
  -H "Authorization: Bearer $SCENESKU_API_KEY"

Response shape is identical to List Scene Packs — a data array of scene packs with a meta object.

List Scene Packs

GET /api/v1/scene-packs

Returns public, published scene packs including images and product data. Behaviour varies by plan:

Free limited list

Returns up to the plan's download limit. No pagination. meta.limit shows the cap.

Pro paginated

Returns all packs with cursor-style offset pagination via page and per_page.

Query parameters

page integer default: 1

Page number (Pro plan only, minimum 1).

per_page integer default: 20

Results per page, maximum 100 (Pro plan only).

Example response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "visibility": "public",
      "images": [
        { "index": 0, "image_url": "https://..." },
        { "index": 1, "image_url": "https://..." }
      ],
      "product_data": {
        "product_title": "Matte Black Travel Tumbler",
        "short_description": "Sleek 20oz insulated tumbler for on-the-go hydration.",
        "long_description": "...",
        "bullet_points": ["BPA-free", "Double-wall insulation", "Fits most cup holders"],
        "price": "34.99",
        "categories": ["Kitchen", "Travel"],
        "tags": ["tumbler", "insulated", "travel"],
        "collections": ["Best Sellers"],
        "options": { "size": ["20oz", "32oz"], "color": ["Matte Black", "Navy"] },
        "attributes": { "material": "Stainless steel", "capacity": "20oz" },
        "language": "en",
        "status": "active"
      }
    }
  ],
  "meta": {
    "plan": "pro",
    "page": 1,
    "per_page": 20,
    "total": 48,
    "total_pages": 3
  }
}

Get Scene Pack

GET /api/v1/scene-packs/:id

Returns a single public, published scene pack by its UUID, including all succeeded images and product data. Returns 404 if the pack does not exist, is private, or is unpublished.

Path parameters

id uuid required

The scene pack UUID.

Example response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "visibility": "public",
    "images": [
      { "index": 0, "image_url": "https://..." },
      { "index": 1, "image_url": "https://..." },
      { "index": 2, "image_url": "https://..." }
    ],
    "product_data": {
      "product_title": "Matte Black Travel Tumbler",
      "short_description": "...",
      "long_description": "...",
      "bullet_points": ["BPA-free", "Double-wall insulation"],
      "price": "34.99",
      "categories": ["Kitchen"],
      "tags": ["tumbler", "travel"],
      "collections": [],
      "options": null,
      "attributes": null,
      "language": "en",
      "status": "active"
    }
  }
}

Response Schema

Scene Pack

id uuid

Unique identifier for the scene pack.

visibility string

Always "public" for API-accessible packs.

images array

List of succeeded images, sorted by index. Each item has index (integer) and image_url (string).

product_data object | null

Product catalog data. Null if no product data was generated for this pack.

product_data fields

product_title string | null

Product name, suitable for a store listing title.

short_description string | null

One-line or brief product description.

long_description string | null

Full product description, may contain multiple paragraphs.

bullet_points string[]

List of feature/benefit bullet points.

price string | null

Decimal price as a string (e.g. "34.99"). Null if not generated.

categories string[]

Product categories (e.g. ["Kitchen", "Travel"]).

tags string[]

SEO and search tags.

collections string[]

Store collections this product belongs to.

options object | null

Product variants (e.g. {"color": ["Black", "White"], "size": ["S", "M", "L"]}).

attributes object | null

Product attributes (e.g. {"material": "Stainless steel"}).

language string | null

ISO 639-1 language code of the generated content (e.g. "en").

status string | null

Lifecycle status of the product data (e.g. "active").

Code Examples

# List active categories (no auth required)
curl https://scenesku.com/api/v1/categories

# Browse packs in a specific category
curl https://scenesku.com/api/v1/categories/electronics/scene-packs \
  -H "Authorization: Bearer $SCENESKU_API_KEY"

# List all packs (first page, 20 per page)
curl https://scenesku.com/api/v1/scene-packs \
  -H "Authorization: Bearer $SCENESKU_API_KEY"

# List packs — page 2 with 10 per page (Pro plan)
curl "https://scenesku.com/api/v1/scene-packs?page=2&per_page=10" \
  -H "Authorization: Bearer $SCENESKU_API_KEY"

# Get a specific pack by ID
curl https://scenesku.com/api/v1/scene-packs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $SCENESKU_API_KEY"

Best Practices

🔑

One key per integration

Create a dedicated API key for each app or service that calls the API. If a key leaks, rotate only that one without disrupting other integrations.

📄

Paginate on Pro

On the Pro plan, always paginate through results using page and per_page. Don't assume all packs fit in a single response.

🖼️

Filter succeeded images only

Images are already filtered to succeeded status in the API response. All image_url values are ready to use — no additional status check needed.

💾

Cache pack data locally

Scene pack content changes infrequently. Cache the list response in your app rather than fetching on every request to reduce latency.

🏷️

Use product_data for catalog seeding

The product_data block is designed to seed ecommerce platforms directly. Map title, categories, tags, and options to your platform's schema.

🔄

Handle null product_data

Some packs may have null product_data. Always check before accessing nested fields to avoid runtime errors.