Media API

Upload and query organization media for sites, shop products, campaigns, and reusable content.

List Media

GET/api/v1/media

Retrieve uploaded media files for the authenticated organization

Query Parameters

Parameter	Type	Description
`group`	`string`	Filter by media group slug
`group_id`	`string`	Filter by media group ID
`mime_type`	`string`	Filter by MIME type prefix, for example image
`tags`	`string`	Comma-separated tags that each file must contain
`search`	`string`	Search filename, title, and alt text
`limit`	`number`	Max results Default: `50`
`offset`	`number`	Skip results for pagination Default: `0`

Request

curl -X GET "https://api.webkasa.app/api/v1/media?mime_type=image&tags=shop" \
  -H "Authorization: Bearer wk_live_xxx..."

Response

200 OK

{
  "data": [
    {
      "id": "media_abc123",
      "filename": "1719180000000-product-jar.jpg",
      "original_filename": "product-jar.jpg",
      "mime_type": "image/jpeg",
      "file_size": 184203,
      "title": "Golden Jar",
      "alt_text": "Golden jar product photo",
      "tags": ["shop", "jar"],
      "url": "https://..."
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Upload Media

POST/api/v1/media

Upload one media file with multipart/form-data

Multipart Fields

Parameter	Type	Description
`file` required	`File`	Multipart file upload. Maximum size is 25 MB.
`title`	`string`	Human-readable media title. Defaults to the file name.
`alt_text`	`string`	Accessible image description used by product and site UIs.
`caption`	`string`	Optional caption for internal or public display.
`tags`	`string \| string[]`	Comma-separated or repeated multipart tags.
`group_id`	`string`	Optional media group ID owned by the API key organization.

Request

curl -X POST "https://api.webkasa.app/api/v1/media" \
  -H "Authorization: Bearer wk_live_xxx..." \
  -F "file=@./product-jar.jpg;type=image/jpeg" \
  -F "title=Golden Jar" \
  -F "alt_text=Golden jar product photo" \
  -F "tags=shop,jar"

Response

201 Created

{
  "data": {
    "id": "media_abc123",
    "organization_id": "org_abc123",
    "filename": "1719180000000-product-jar.jpg",
    "original_filename": "product-jar.jpg",
    "mime_type": "image/jpeg",
    "file_size": 184203,
    "storage_path": "org_abc123/1719180000000-product-jar.jpg",
    "title": "Golden Jar",
    "alt_text": "Golden jar product photo",
    "tags": ["shop", "jar"],
    "url": "https://..."
  }
}

413 Payload Too Large

{
  "error": "Uploaded file exceeds the 25 MB limit"
}