List catalog entries

GET

/v1/catalog/{resource}

curl --request GET \
  --url https://example.com/v1/catalog/models \
  --header 'Authorization: Bearer <token>'

List catalog entries for resource — filters pass through to studio.

Filters other than status/limit/offset are resource-specific and ignored by studio where they don’t apply.

Authorizations

• sk_*

Parameters

Path Parameters

resource

required

Resource

string

Allowed values: models backgrounds complementary-garments

Query Parameters

status

Any of:

string

string

Allowed values: active archived

null

null

limit

Any of:

integer

integer

>= 1

null

null

offset

Any of:

integer

integer

null

null

gender

Any of:

string

string

null

null

ethnicity

Any of:

string

string

null

null

scene_type

Any of:

string

string

null

null

garment_category

Any of:

string

string

null

null

compatible_with_category_id

Any of:

string

string

null

null

Header Parameters

X-Shopify-Hmac-Sha256

Any of:

string

string

null

null

Responses

200

Successful Response

Media type application/json

Response V1 List Catalog V1 Catalog Resource Get

Array<object>

CatalogEntryResponse

One catalog entry — a generated image with its spec embedded.

image_url is a short-lived presigned GET URL; a raw S3 key never crosses this boundary (studio AD-8). spec is the resource-specific spec view — models: {public_id, display_name, gender, ethnicity, body_type, age_range, metadata}; backgrounds: {public_id, display_name, scene_type, mood, dominant_colors, metadata}; complementary-garments: {public_id, display_name, garment_category_public_id, color, material, pattern, fit, length, metadata}. Kept polymorphic-as-dict on this boundary so studio can extend spec attributes without a gateway contract break.

object

public_id

required

Public Id

The catalog image’s ULID — what workflow requests reference.

string

image_url

required

Image Url

Short-lived presigned preview URL.

string

status

required

Status

‘active’ | ‘archived’.

string

spec

required

Spec

The embedded resource-specific spec view (see class docstring).

object

key

additional properties

any

description

Any of:

string

string

null

null

generation_job_public_id

Any of:

string

string

null

null

created_at

Any of:

string

string format: date-time

null

null

Example ^generated

[
  {
    "public_id": "example",
    "image_url": "example",
    "status": "example",
    "spec": {},
    "description": "example",
    "generation_job_public_id": "example",
    "created_at": "2026-04-15T12:00:00Z"
  }
]

422

Validation Error

Media type application/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example ^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}