From ea142a460589637a4a8971954374d5721546890b Mon Sep 17 00:00:00 2001 From: Gilad Resisi Date: Wed, 19 Aug 2026 18:34:47 +0700 Subject: [PATCH 1/4] docs: list media via public API (GET /media) and MCP mediaListTool Documents gitroomhq/postiz-app#1926: OpenAPI entry for GET /public/v1/media, a List Media page under Uploads, mediaListTool in the MCP tools reference and a "reuse an existing upload" example. Verified with mintlify dev: all three pages render with correct navigation entries and no overflow. Co-Authored-By: Claude Fable 5 --- docs.json | 3 +- mcp/examples.mdx | 50 +++++++++++++ mcp/tools.mdx | 22 ++++++ public-api/openapi.json | 120 ++++++++++++++++++++++++++++++ public-api/uploads/list-media.mdx | 43 +++++++++++ 5 files changed, 237 insertions(+), 1 deletion(-) create mode 100644 public-api/uploads/list-media.mdx diff --git a/docs.json b/docs.json index 529b9800..b6331418 100644 --- a/docs.json +++ b/docs.json @@ -359,7 +359,8 @@ "group": "Uploads", "pages": [ "public-api/uploads/upload-file", - "public-api/uploads/upload-from-url" + "public-api/uploads/upload-from-url", + "public-api/uploads/list-media" ] }, { diff --git a/mcp/examples.mdx b/mcp/examples.mdx index 580c5e53..5d84b5a3 100644 --- a/mcp/examples.mdx +++ b/mcp/examples.mdx @@ -226,6 +226,56 @@ API requires Facebook Login. +## Reuse an Existing Upload + + + + The agent calls `mediaListTool`: + + ```json + { + "search": "launch-banner" + } + ``` + + Returns: + + ```json + { + "pages": 1, + "output": [ + { + "id": "med-789", + "name": "6fba0ef5febb4400ae8778a5b854224d.png", + "originalName": "launch-banner.png", + "path": "https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png", + "type": "image", + "fileSize": 48213, + "createdAt": "2025-01-10T09:12:00.000Z", + "thumbnail": null + } + ] + } + ``` + + + The agent passes the returned `path` as an attachment, no re-upload needed: + + ```json + { + "postsAndComments": [ + { + "content": "

Launch day!

", + "attachments": ["https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png"] + } + ] + } + ``` + + + +--- + ## Generate a Video and Post diff --git a/mcp/tools.mdx b/mcp/tools.mdx index fd9049aa..88885b82 100644 --- a/mcp/tools.mdx +++ b/mcp/tools.mdx @@ -234,6 +234,28 @@ If the update fails, returns `{ errors: string }` with details (e.g., post not f --- +## mediaListTool + +List the media files already uploaded to your media library, newest first, 18 per page. Use it to reuse an existing image or video instead of uploading it again. + +**Parameters:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `search` | string | No | Case-insensitive filter on the original file name | +| `page` | number | No | Page number, starting at 1 (default 1) | + +**Returns:** + +| Field | Type | Description | +|-------|------|-------------| +| `pages` | number | Total number of pages | +| `output` | array | Media items: `id`, `name`, `originalName`, `path`, `type`, `fileSize`, `createdAt`, `thumbnail` | + +Use an item's `path` in the `attachments` array when scheduling a post. + +--- + ## generateImageTool Generate an AI image to use as a post attachment. diff --git a/public-api/openapi.json b/public-api/openapi.json index 21629023..7fa245c8 100644 --- a/public-api/openapi.json +++ b/public-api/openapi.json @@ -1990,6 +1990,79 @@ } } }, + "/media": { + "get": { + "tags": [ + "Uploads" + ], + "summary": "List media", + "description": "List the media files already uploaded to your organization's media library, newest first, 18 per page.", + "operationId": "listMedia", + "parameters": [ + { + "name": "page", + "in": "query", + "required": false, + "description": "Page number (1-indexed). Defaults to 1.", + "schema": { + "type": "integer", + "minimum": 1, + "default": 1 + } + }, + { + "name": "search", + "in": "query", + "required": false, + "description": "Case-insensitive filter on the original file name.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Paginated list of media files", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pages": { + "type": "integer", + "description": "Total number of pages" + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MediaListItem" + } + } + } + }, + "example": { + "pages": 2, + "results": [ + { + "id": "e639003b-f727-4a1e-87bd-74a2c48ae41e", + "name": "6fba0ef5febb4400ae8778a5b854224d.png", + "originalName": "cover-cyan.png", + "path": "https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png", + "thumbnail": null, + "alt": null, + "thumbnailTimestamp": null, + "type": "image", + "fileSize": 48213, + "createdAt": "2024-12-14T08:18:54.274Z" + } + ] + } + } + } + } + } + } + }, "/notifications": { "get": { "tags": [ @@ -2282,6 +2355,53 @@ } } }, + "MediaListItem": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique file ID" + }, + "name": { + "type": "string", + "description": "Stored file name" + }, + "originalName": { + "type": "string", + "nullable": true, + "description": "File name as uploaded (searchable)" + }, + "path": { + "type": "string", + "description": "Public file URL, usable as a post attachment" + }, + "thumbnail": { + "type": "string", + "nullable": true, + "description": "Thumbnail URL (videos)" + }, + "alt": { + "type": "string", + "nullable": true + }, + "thumbnailTimestamp": { + "type": "integer", + "nullable": true + }, + "type": { + "type": "string", + "description": "image or video" + }, + "fileSize": { + "type": "integer", + "description": "Size in bytes" + }, + "createdAt": { + "type": "string", + "format": "date-time" + } + } + }, "MediaFile": { "type": "object", "properties": { diff --git a/public-api/uploads/list-media.mdx b/public-api/uploads/list-media.mdx new file mode 100644 index 00000000..93e224fc --- /dev/null +++ b/public-api/uploads/list-media.mdx @@ -0,0 +1,43 @@ +--- +title: 'List Media' +openapi: 'GET /media' +icon: 'images' +--- + +List the files already in your media library so you can reuse them as post attachments without uploading again. Results are scoped to your organization, sorted newest first, 18 per page. + +## Query parameters + +- `page`: page number, starting at 1 (default 1). +- `search`: case-insensitive filter on the original file name. + +## Example + +```bash +curl "https://api.postiz.com/public/v1/media?search=banner&page=1" \ + -H "Authorization: your-api-key" +``` + +Response: + +```json +{ + "pages": 1, + "results": [ + { + "id": "e639003b-f727-4a1e-87bd-74a2c48ae41e", + "name": "6fba0ef5febb4400ae8778a5b854224d.png", + "originalName": "launch-banner.png", + "path": "https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png", + "thumbnail": null, + "alt": null, + "thumbnailTimestamp": null, + "type": "image", + "fileSize": 48213, + "createdAt": "2025-01-10T09:12:00.000Z" + } + ] +} +``` + +Pass an item's `path` in a post's `image` array (see [Create Post](/public-api/posts/create)). `path` is a public URL, so there is no separate download endpoint. From 5fc99df972371edf7b5ef2747b2247f12b28c6b8 Mon Sep 17 00:00:00 2001 From: Gilad Resisi Date: Wed, 19 Aug 2026 22:36:41 +0700 Subject: [PATCH 2/4] docs: describe the media type field accurately Co-Authored-By: Claude Fable 5 --- public-api/openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public-api/openapi.json b/public-api/openapi.json index 7fa245c8..0a107b73 100644 --- a/public-api/openapi.json +++ b/public-api/openapi.json @@ -2390,7 +2390,7 @@ }, "type": { "type": "string", - "description": "image or video" + "description": "Media type. Currently always \"image\" regardless of the file; use the extension of path to tell images from videos." }, "fileSize": { "type": "integer", From 9ef8cb81f7c886b02c784e7c2a5c326fd65c109e Mon Sep 17 00:00:00 2001 From: Gilad Resisi Date: Wed, 7 Oct 2026 09:46:48 +0700 Subject: [PATCH 3/4] docs: drop type and fileSize from the media list response The API and mediaListTool no longer return them (type was always "image", fileSize almost always 0), so the examples, field table and OpenAPI schema drop both. Co-Authored-By: Claude Sonnet 5.5 --- mcp/examples.mdx | 2 -- mcp/tools.mdx | 2 +- public-api/openapi.json | 10 ---------- public-api/uploads/list-media.mdx | 2 -- 4 files changed, 1 insertion(+), 15 deletions(-) diff --git a/mcp/examples.mdx b/mcp/examples.mdx index 5d84b5a3..ff313113 100644 --- a/mcp/examples.mdx +++ b/mcp/examples.mdx @@ -249,8 +249,6 @@ API requires Facebook Login. "name": "6fba0ef5febb4400ae8778a5b854224d.png", "originalName": "launch-banner.png", "path": "https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png", - "type": "image", - "fileSize": 48213, "createdAt": "2025-01-10T09:12:00.000Z", "thumbnail": null } diff --git a/mcp/tools.mdx b/mcp/tools.mdx index 88885b82..a5d5670a 100644 --- a/mcp/tools.mdx +++ b/mcp/tools.mdx @@ -250,7 +250,7 @@ List the media files already uploaded to your media library, newest first, 18 pe | Field | Type | Description | |-------|------|-------------| | `pages` | number | Total number of pages | -| `output` | array | Media items: `id`, `name`, `originalName`, `path`, `type`, `fileSize`, `createdAt`, `thumbnail` | +| `output` | array | Media items: `id`, `name`, `originalName`, `path`, `createdAt`, `thumbnail` | Use an item's `path` in the `attachments` array when scheduling a post. diff --git a/public-api/openapi.json b/public-api/openapi.json index 0a107b73..4c4d196b 100644 --- a/public-api/openapi.json +++ b/public-api/openapi.json @@ -2051,8 +2051,6 @@ "thumbnail": null, "alt": null, "thumbnailTimestamp": null, - "type": "image", - "fileSize": 48213, "createdAt": "2024-12-14T08:18:54.274Z" } ] @@ -2388,14 +2386,6 @@ "type": "integer", "nullable": true }, - "type": { - "type": "string", - "description": "Media type. Currently always \"image\" regardless of the file; use the extension of path to tell images from videos." - }, - "fileSize": { - "type": "integer", - "description": "Size in bytes" - }, "createdAt": { "type": "string", "format": "date-time" diff --git a/public-api/uploads/list-media.mdx b/public-api/uploads/list-media.mdx index 93e224fc..b4af92e5 100644 --- a/public-api/uploads/list-media.mdx +++ b/public-api/uploads/list-media.mdx @@ -32,8 +32,6 @@ Response: "thumbnail": null, "alt": null, "thumbnailTimestamp": null, - "type": "image", - "fileSize": 48213, "createdAt": "2025-01-10T09:12:00.000Z" } ] From 0386f39379ec59cab8658e907784695bd19e9508 Mon Sep 17 00:00:00 2001 From: Gilad Resisi Date: Wed, 7 Oct 2026 10:24:08 +0700 Subject: [PATCH 4/4] docs: drop alt, thumbnail and thumbnailTimestamp from the media list response The API and mediaListTool now return only id, name, originalName, path and createdAt, so the examples, field list and OpenAPI schema drop the rest. Co-Authored-By: Claude Sonnet 5.5 --- mcp/examples.mdx | 3 +-- mcp/tools.mdx | 2 +- public-api/openapi.json | 16 ---------------- public-api/uploads/list-media.mdx | 3 --- 4 files changed, 2 insertions(+), 22 deletions(-) diff --git a/mcp/examples.mdx b/mcp/examples.mdx index ff313113..b8801f64 100644 --- a/mcp/examples.mdx +++ b/mcp/examples.mdx @@ -249,8 +249,7 @@ API requires Facebook Login. "name": "6fba0ef5febb4400ae8778a5b854224d.png", "originalName": "launch-banner.png", "path": "https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png", - "createdAt": "2025-01-10T09:12:00.000Z", - "thumbnail": null + "createdAt": "2025-01-10T09:12:00.000Z" } ] } diff --git a/mcp/tools.mdx b/mcp/tools.mdx index a5d5670a..9c2c97ec 100644 --- a/mcp/tools.mdx +++ b/mcp/tools.mdx @@ -250,7 +250,7 @@ List the media files already uploaded to your media library, newest first, 18 pe | Field | Type | Description | |-------|------|-------------| | `pages` | number | Total number of pages | -| `output` | array | Media items: `id`, `name`, `originalName`, `path`, `createdAt`, `thumbnail` | +| `output` | array | Media items: `id`, `name`, `originalName`, `path`, `createdAt` | Use an item's `path` in the `attachments` array when scheduling a post. diff --git a/public-api/openapi.json b/public-api/openapi.json index 4c4d196b..769b5450 100644 --- a/public-api/openapi.json +++ b/public-api/openapi.json @@ -2048,9 +2048,6 @@ "name": "6fba0ef5febb4400ae8778a5b854224d.png", "originalName": "cover-cyan.png", "path": "https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png", - "thumbnail": null, - "alt": null, - "thumbnailTimestamp": null, "createdAt": "2024-12-14T08:18:54.274Z" } ] @@ -2373,19 +2370,6 @@ "type": "string", "description": "Public file URL, usable as a post attachment" }, - "thumbnail": { - "type": "string", - "nullable": true, - "description": "Thumbnail URL (videos)" - }, - "alt": { - "type": "string", - "nullable": true - }, - "thumbnailTimestamp": { - "type": "integer", - "nullable": true - }, "createdAt": { "type": "string", "format": "date-time" diff --git a/public-api/uploads/list-media.mdx b/public-api/uploads/list-media.mdx index b4af92e5..45d25a16 100644 --- a/public-api/uploads/list-media.mdx +++ b/public-api/uploads/list-media.mdx @@ -29,9 +29,6 @@ Response: "name": "6fba0ef5febb4400ae8778a5b854224d.png", "originalName": "launch-banner.png", "path": "https://uploads.postiz.com/6fba0ef5febb4400ae8778a5b854224d.png", - "thumbnail": null, - "alt": null, - "thumbnailTimestamp": null, "createdAt": "2025-01-10T09:12:00.000Z" } ]