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.

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

# Response:
# {
#   "projects": [
#     {
#       "id": "proj_abc123",
#       "name": "My SaaS",
#       "created_at": "2026-01-15T08:00:00Z"
#     },
#     {
#       "id": "proj_def456",
#       "name": "Marketing Site",
#       "created_at": "2026-02-20T14:30:00Z"
#     }
#   ]
# }

List Collections

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

GET/v1/collections
# 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:
# {
#   "collections": [
#     {
#       "id": "col_xyz789",
#       "project_id": "proj_abc123",
#       "name": "Fox Mascot",
#       "description": "A friendly fox character for our SaaS",
#       "created_at": "2026-02-01T10:00:00Z",
#       "item_count": 12,
#       "asset_count": 48
#     }
#   ]
# }

Collection Detail

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

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

# Response:
# {
#   "id": "col_xyz789",
#   "project_id": "proj_abc123",
#   "name": "Fox Mascot",
#   "description": "A friendly fox character for our SaaS",
#   "config": {
#     "style_card": "Flat illustration style with bold outlines...",
#     "reference_asset_ids": ["ast_ref_001", "ast_ref_002"],
#     "caution_list": ["Avoid overly rounded ears", "Keep tail fluffy"]
#   },
#   "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).

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

# Response:
# {
#   "items": [
#     {
#       "id": "item_001",
#       "name": "Idle",
#       "type": "image",
#       "created_at": "2026-02-01T10:05:00Z",
#       "assets": {
#         "image": { "id": "ast_img_001", "status": "completed" },
#         "transparent_image": { "id": "ast_timg_001", "status": "completed" }
#       }
#     },
#     {
#       "id": "item_002",
#       "name": "Dancing",
#       "type": "animation",
#       "created_at": "2026-02-01T10:10:00Z",
#       "assets": {
#         "image": { "id": "ast_img_002", "status": "completed" },
#         "transparent_image": { "id": "ast_timg_002", "status": "completed" },
#         "video": { "id": "ast_vid_002", "status": "completed" },
#         "webm": { "id": "ast_webm_002", "status": "completed" },
#         "hevc": { "id": "ast_hevc_002", "status": "completed" }
#       }
#     }
#   ]
# }

Check Asset Status

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

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

# Response:
# {
#   "assets": [
#     {
#       "id": "ast_img_001",
#       "type": "image",
#       "status": "completed",
#       "url": "https://assets.masko.ai/col_xyz/image_001.png",
#       "item_id": "item_001"
#     },
#     {
#       "id": "ast_vid_003",
#       "type": "video",
#       "status": "processing",
#       "url": null,
#       "item_id": "item_003"
#     },
#     {
#       "id": "ast_webm_004",
#       "type": "webm",
#       "status": "pending",
#       "url": null,
#       "item_id": "item_004"
#     }
#   ]
# }

Get All URLs

For published collections, you can retrieve all CDN URLs in one call. This returns only completed assets that have been published to the CDN.

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

# Response:
# {
#   "urls": {
#     "item_001": {
#       "image": "https://assets.masko.ai/col_xyz/idle.png",
#       "transparent_image": "https://assets.masko.ai/col_xyz/idle_transparent.png"
#     },
#     "item_002": {
#       "image": "https://assets.masko.ai/col_xyz/dancing.png",
#       "webm": "https://assets.masko.ai/col_xyz/dancing.webm",
#       "hevc": "https://assets.masko.ai/col_xyz/dancing.mp4"
#     }
#   }
# }