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. For metadata-only polling or inventory views, add ?include_file_urls=false to skip signed file_url generation while keeping cdn_url.

CDN Export JSON

Use the CDN export endpoint when you want the same hosted-link JSON shown in the collection page's Get Links → Export JSON panel. This endpoint is built from published cdn_assets, so it includes pose items that have video loops attached even when the item itself is not typed as an animation.

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

# Response:
# {
#   "collection": "Fox Mascot",
#   "items": [
#     {
#       "name": "card-sit",
#       "image": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.png",
#       "transparent_image": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-transparent.png",
#       "animations": [
#         {
#           "video": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mp4",
#           "transparent_video_webm": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.webm",
#           "transparent_video_mov": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mov",
#           "transparent_video_android": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-android.mp4"
#         }
#       ]
#     }
#   ]
# }

Use /v1/collections/:id/items and /v1/collections/:id/assets for raw metadata, item IDs, asset IDs, prompts, and status checks. Use /v1/collections/:id/cdn-export for the clean copy/paste export format.

If asset hosting is disabled, the collection is unpublished, or no CDN assets are available yet, the endpoint returns 409 cdn_export_not_ready instead of an empty export. Enable asset hosting and publish/sync the collection before retrying.

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; add include_file_urls=false for metadata-only lists
GET /v1/assets/:id - get a single asset
DELETE /v1/assets/:id - archive an asset (soft delete)