Media Folders

Organize media files into a hierarchical folder structure. Maximum nesting depth is 3 levels.

8 endpoints

`GET /media-folders`

List folders

Returns a flat list of all media folders.

Parameters

Name	In	Type	Required	Description
`parentId`	query	string	No	Parent resource ID
`search`	query	string	No	Full-text search query

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions

Examples

Bash

curl https://api.lynkow.com/v1/media-folders \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Banners",
      "parentId": null,
      "mediaCount": 24,
      "createdAt": "2025-01-15T09:00:00.000Z"
    },
    {
      "id": "f2b3c4d5-e6f7-8901-bcde-f12345678901",
      "name": "Blog Images",
      "parentId": null,
      "mediaCount": 87,
      "createdAt": "2025-01-15T09:05:00.000Z"
    },
    {
      "id": "f3c4d5e6-f7a8-9012-cdef-234567890123",
      "name": "Thumbnails",
      "parentId": "f2b3c4d5-e6f7-8901-bcde-f12345678901",
      "mediaCount": 42,
      "createdAt": "2025-02-01T14:00:00.000Z"
    }
  ]
}

`POST /media-folders`

Create a folder

Creates a new media folder. Set parentId to create a subfolder.

Request Body

Content-Type: application/json

Field	Type	Required	Description
`name`	string	Yes	Required. Display name. 1-255 characters
`parentId`	string	No	Parent resource ID

Responses

Status	Description
`201`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`422`	Validation error

Notes: - Maximum nesting depth: 3 levels.
Folder names must be unique within the same parent.

Examples

Bash

curl -X POST https://api.lynkow.com/v1/media-folders \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Product Photos", "parentId": null}'

Response Example

JSON

{
  "data": {
    "id": "f4d5e6f7-a8b9-0123-defa-345678901234",
    "name": "Product Photos",
    "parentId": null,
    "mediaCount": 0,
    "createdAt": "2025-04-06T11:00:00.000Z"
  }
}

`GET /media-folders/tree`

Get folder tree

Returns folders as a nested tree structure.

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions

Examples

Bash

curl https://api.lynkow.com/v1/media-folders/tree \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Banners",
      "mediaCount": 24,
      "children": []
    },
    {
      "id": "f2b3c4d5-e6f7-8901-bcde-f12345678901",
      "name": "Blog Images",
      "mediaCount": 87,
      "children": [
        {
          "id": "f3c4d5e6-f7a8-9012-cdef-234567890123",
          "name": "Thumbnails",
          "mediaCount": 42,
          "children": []
        }
      ]
    }
  ]
}

`POST /media-folders/move-media`

Move files to a folder

Moves one or more media files to a target folder. Provide an array of media IDs and the target folder ID (or null for root).

Request Body

Content-Type: application/json

Field	Type	Required	Description
`mediaIds`	string[]	Yes	Required. 1-100 characters. Array of strings
`folderId`	string \| null	Yes	Required. Media folder UUID

Responses

Status	Description
`201`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`422`	Validation error

Examples

Bash

curl -X POST https://api.lynkow.com/v1/media-folders/move-media \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mediaIds": ["uuid1", "uuid2"], "folderId": "target-folder-uuid"}'

Response Example

JSON

{
  "moved": 2
}

`GET /media-folders/:id`

Get a folder

Returns a single folder with its contents and subfolders.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl https://api.lynkow.com/v1/media-folders/f1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Banners",
    "parentId": null,
    "mediaCount": 24,
    "children": [
      {
        "id": "f5e6f7a8-b9c0-1234-efab-567890123456",
        "name": "Homepage",
        "mediaCount": 8
      }
    ],
    "createdAt": "2025-01-15T09:00:00.000Z",
    "updatedAt": "2025-03-10T14:00:00.000Z"
  }
}

`PUT /media-folders/:id`

Rename a folder

Updates a folder's name.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Request Body

Content-Type: application/json

Field	Type	Required	Description
`name`	string	No	Display name. 1-255 characters
`parentId`	string \| null	No	Parent resource ID

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found
`422`	Validation error

Examples

Bash

curl -X PUT https://api.lynkow.com/v1/media-folders/f1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hero Banners"}'

Response Example

JSON

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Hero Banners",
    "parentId": null,
    "mediaCount": 24,
    "createdAt": "2025-01-15T09:00:00.000Z",
    "updatedAt": "2025-04-06T12:00:00.000Z"
  }
}

`DELETE /media-folders/:id`

Delete a folder

Deletes a folder. You must specify what happens to contained files via the action parameter: move (to parent) or delete (permanently).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found

Examples

Bash

curl -X DELETE "https://api.lynkow.com/v1/media-folders/f1a2b3c4-d5e6-7890-abcd-ef1234567890?action=move" \
  -H "Authorization: Bearer $API_TOKEN"

Response Example

JSON

{
  "message": "Folder deleted"
}

`POST /media-folders/:id/move`

Move a folder

Moves a folder to a different parent folder (or to root with parentId: null).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier

Request Body

Content-Type: application/json

Field	Type	Required	Description
`parentId`	string \| null	Yes	Required. Parent resource ID

Responses

Status	Description
`200`	Successful response
`401`	Unauthorized — invalid or missing API token
`403`	Forbidden — insufficient permissions
`404`	Not found
`422`	Validation error

Examples

Bash

curl -X POST https://api.lynkow.com/v1/media-folders/f3c4d5e6-f7a8-9012-cdef-234567890123/move \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parentId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"}'

Response Example

JSON

{
  "data": {
    "id": "f3c4d5e6-f7a8-9012-cdef-234567890123",
    "name": "Thumbnails",
    "parentId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "mediaCount": 42,
    "createdAt": "2025-02-01T14:00:00.000Z",
    "updatedAt": "2025-04-06T12:00:00.000Z"
  }
}

GET /media-folders

Parameters

Responses

Examples

Response Example

POST /media-folders

Request Body

Responses

Examples

Response Example

GET /media-folders/tree

Responses

Examples

Response Example

POST /media-folders/move-media

Request Body

Responses

Examples

Response Example

GET /media-folders/:id

Parameters

Responses

Examples

Response Example

PUT /media-folders/:id

Parameters

Request Body

Responses

Examples

Response Example

DELETE /media-folders/:id

Parameters

Responses

Examples

Response Example

POST /media-folders/:id/move

Parameters

Request Body

Responses

Examples

Response Example

For LLMs

`GET /media-folders`

`POST /media-folders`

`GET /media-folders/tree`

`POST /media-folders/move-media`

`GET /media-folders/:id`

`PUT /media-folders/:id`

`DELETE /media-folders/:id`

`POST /media-folders/:id/move`