Media

Upload and manage media assets

Media

Upload, retrieve, and manage media assets in your tenant.

Endpoints

GETList Media POSTUpload Media GETGet Media DELETEDelete Media

GET/v1/media/{tenant_id}

List Media

Retrieve all media assets in your tenant. Supports pagination and filtering by type.

Requires API Key

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.

Query Parameters

Name	Type	Default	Description
`page`	integer	1	Page number.
`per_page`	integer	25	Results per page.
`type`	string	—	Filter by file type: image, video, document, or audio.

curl -X GET "https://api.knitt.co/v1/media/ten_abc123?page=1&per_page=25&type=image" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns a paginated list of media assets.

{
  "data": [
    {
      "id": "med_abc123",
      "filename": "hero-image.jpg",
      "url": "https://cdn.knitt.co/tenant_id/hero-image.jpg",
      "type": "image",
      "size": 245760,
      "width": 1920,
      "height": 1080,
      "alt": "Hero banner",
      "created_at": "2026-01-18T12:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 12
  }
}

POST/v1/media/{tenant_id}

Upload Media

Upload a file to your tenant media library. Send as multipart/form-data.

Requires API Key

File upload uses multipart/form-data. The code examples below show language-specific file upload patterns.

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.

Request Body

Name	Type	Required	Description
`file`	file	Yes	The file to upload. Max 10 MB on Starter, 50 MB on Pro+.
`alt`	string	No	Alt text for the media asset.
`folder`	string	No	Folder path to organise the file.

curl -X POST "https://api.knitt.co/v1/media/ten_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./screenshot.png" \
  -F "alt=Product screenshot"

Response

Returns the uploaded media asset.

{
  "data": {
    "id": "med_def456",
    "filename": "screenshot.png",
    "url": "https://cdn.knitt.co/tenant_id/blog/images/screenshot.png",
    "type": "image",
    "size": 184320,
    "width": 1440,
    "height": 900,
    "alt": "Product screenshot",
    "created_at": "2026-01-20T15:30:00Z"
  }
}

GET/v1/media/{tenant_id}/{media_id}

Get Media

Retrieve a single media asset by its ID.

Requires API Key

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.
`media_id`	string	The ID of the media asset.

curl -X GET "https://api.knitt.co/v1/media/ten_abc123/med_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns the media asset object.

{
  "data": {
    "id": "med_abc123",
    "filename": "hero-image.jpg",
    "url": "https://cdn.knitt.co/tenant_id/hero-image.jpg",
    "type": "image",
    "size": 245760,
    "width": 1920,
    "height": 1080,
    "alt": "Hero banner",
    "created_at": "2026-01-18T12:00:00Z"
  }
}

DELETE/v1/media/{tenant_id}/{media_id}

Delete Media

Permanently delete a media asset. Any entries referencing this asset will have their media fields cleared.

Requires API Key

Path Parameters

Name	Type	Description
`tenant_id`	string	Your tenant ID.
`media_id`	string	The ID of the media asset.

curl -X DELETE "https://api.knitt.co/v1/media/ten_abc123/med_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns a confirmation message.

{
  "message": "Media asset deleted successfully."
}

Last updated: February 7, 2026