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:
# {
#   "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.

# 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.

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).

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.

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, GET /v1/collections/:id/assets returns every asset grouped by item, with CDN URLs when available.

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

# Response:
# {
#   "data": {
#     "collection": "Fox Mascot",
#     "items": [
#       {
#         "name": "Idle",
#         "image": "https://assets.masko.ai/col_xyz/idle.png",
#         "transparent_image": "https://assets.masko.ai/col_xyz/idle_transparent.png"
#       },
#       {
#         "name": "Dancing",
#         "image": "https://assets.masko.ai/col_xyz/dancing.png",
#         "animations": [
#           {
#             "video": "https://assets.masko.ai/col_xyz/dancing.mp4",
#             "transparent_video_webm": "https://assets.masko.ai/col_xyz/dancing.webm"
#           }
#         ]
#       }
#     ]
#   }
# }

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)