List & Browse

Browse your projects, collections, and assets. Use these endpoints to find resource IDs, check generation status, and retrieve CDN URLs.

List Projects

Projects are the top-level container. Each project can hold multiple collections.

curl https://api.masko.ai/v1/projects \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Response:
# {
#   "data": [
#     {
#       "id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#       "name": "My SaaS",
#       "organization_id": null,
#       "created_at": "2026-01-15T08:00:00Z",
#       "updated_at": "2026-01-15T08:00:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

List Collections

List all collections, optionally filtered by project. Each collection represents one mascot character.

# All collections
curl https://api.masko.ai/v1/collections \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Filter by project
curl "https://api.masko.ai/v1/collections?project_id=proj_abc123" \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Response:
# {
#   "data": [
#     {
#       "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#       "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#       "name": "Fox Mascot",
#       "type": "mascot",
#       "is_published": true,
#       "public_slug": "fox-mascot-a1b2c3d4",
#       "user_prefix": "fda8417d",
#       "created_at": "2026-02-01T10:00:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Collection Detail

Get full details of a single collection, including its configuration with style card and reference settings.

curl https://api.masko.ai/v1/collections/col_xyz789 \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Response:
# {
#   "data": {
#     "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#     "name": "Fox Mascot",
#     "type": "mascot",
#     "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#     "slug": "fox-mascot-a1b2c3d4",
#     "config": {
#       "prompt": "A friendly fox character for our SaaS",
#       "reference_asset_ids": ["e906ebb5-deb1-4010-82f9-f0182a3812e0"],
#       "style_card": null,
#       "caution_list": []
#     },
#     "cdn_status": [],
#     "created_at": "2026-02-01T10:00:00Z",
#     "updated_at": "2026-03-15T16:20:00Z"
#   }
# }

List Items

Items are individual poses or assets within a collection. Each item can have multiple asset types (image, animation, logo).

curl https://api.masko.ai/v1/collections/col_xyz789/items \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Response:
# {
#   "data": [
#     {
#       "id": "b646b856-5832-49f4-90bf-9c41a50515b3",
#       "name": "Idle",
#       "type": "image",
#       "prompt": "idle pose",
#       "public_slug": "idle",
#       "created_at": "2026-02-01T10:05:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Check Asset Status

List all assets in a collection with their current status. Useful for checking which generations are still in progress.

curl https://api.masko.ai/v1/collections/col_xyz789/assets \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Response:
# {
#   "data": [
#     {
#       "id": "e906ebb5-deb1-4010-82f9-f0182a3812e0",
#       "type": "image",
#       "status": "completed",
#       "file_url": "https://storage.googleapis.com/...",
#       "cdn_url": "https://assets.masko.ai/fda8417d/fox-mascot/idle.png",
#       "item_id": "b646b856-5832-49f4-90bf-9c41a50515b3",
#       "collection_id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#       "created_at": "2026-02-01T10:05:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Published assets include cdn_url when a CDN URL exists. Assets without CDN publishing still include a signed file_url when available.

Items, Assets, and Deletion

Individual items can be renamed or deleted via:

  • PATCH /v1/collections/:id/items/:itemId - body { name?, prompt? }
  • DELETE /v1/collections/:id/items/:itemId

Assets are also exposed as a first-class resource:

  • GET /v1/assets - list your assets with pagination
  • GET /v1/assets/:id - get a single asset
  • DELETE /v1/assets/:id - archive an asset (soft delete)