Postiz Public API

{
  "openapi": "3.1.0",
  "info": {
    "title": "Postiz Public API",
    "description": "API for managing social media posts, integrations, and media uploads in Postiz.\n\n## Authentication\n\nAll endpoints require an API key passed in the `Authorization` header:\n\n```\nAuthorization: your-api-key\n```\n\nGet your API key from Postiz Settings.\n\n## Rate Limits\n\nThere is a limit of **30 requests per hour**.\n\n## Terminology\n\nThe UI uses `channel`, but the API uses `integration`. They refer to the same thing.\n\n## Supported Platforms (27)\n\n**Social Platforms:** X (Twitter), LinkedIn, LinkedIn Page, Facebook, Instagram, Instagram Standalone, Threads, Bluesky, Mastodon, Warpcast (Farcaster), Nostr, VK\n\n**Video Platforms:** YouTube, TikTok\n\n**Community Platforms:** Reddit, Lemmy, Discord, Slack, Telegram\n\n**Design Platforms:** Pinterest, Dribbble\n\n**Blogging Platforms:** Medium, Dev.to, Hashnode, WordPress\n\n**Business:** Google My Business (GMB), Listmonk (newsletters)",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.postiz.com/public/v1",
      "description": "Postiz Cloud"
    },
    {
      "url": "https://{your-domain}/api/public/v1",
      "description": "Self-hosted",
      "variables": {
        "your-domain": {
          "default": "localhost:5000",
          "description": "Your Postiz instance domain"
        }
      }
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Integrations",
      "description": "Manage connected social media channels"
    },
    {
      "name": "Posts",
      "description": "Create, list, and delete posts"
    },
    {
      "name": "Uploads",
      "description": "Upload media files"
    },
    {
      "name": "Notifications",
      "description": "View organization notifications"
    },
    {
      "name": "Analytics",
      "description": "View analytics for integrations and posts"
    },
    {
      "name": "Video Generation",
      "description": "Generate videos with AI"
    }
  ],
  "paths": {
    "/integrations": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "List all integrations",
        "description": "Returns all connected social media channels for your organization.",
        "operationId": "listIntegrations",
        "responses": {
          "200": {
            "description": "List of integrations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Integration"
                  }
                },
                "example": [
                  {
                    "id": "cm4ean69r0003w8w1cdomox9n",
                    "name": "Nevo David",
                    "identifier": "x",
                    "picture": "https://uploads.postiz.com/avatar.jpg",
                    "disabled": false,
                    "profile": "nevodavid",
                    "customer": {
                      "id": "customer-id",
                      "name": "My Company"
                    }
                  }
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "Filter integrations by customer (group) ID. Returns only channels assigned to the given group.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/groups": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "List all groups (customers)",
        "description": "Returns all customers (groups) for your organization. Use a group ID to filter the integrations list.",
        "operationId": "listGroups",
        "responses": {
          "200": {
            "description": "List of groups",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Group"
                  }
                },
                "example": [
                  {
                    "id": "customer-id",
                    "name": "My Company"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/integrations/{id}": {
      "delete": {
        "tags": [
          "Integrations"
        ],
        "summary": "Delete a channel",
        "description": "Delete a connected channel by its integration ID. Any scheduled posts associated with this channel will also be deleted.",
        "operationId": "deleteChannel",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Integration ID of the channel to delete",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Channel deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "id": "cm4ean69r0003w8w1cdomox9n"
                }
              }
            }
          },
          "404": {
            "description": "Channel not found"
          }
        }
      }
    },
    "/social/{integration}": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "Get OAuth URL for a channel",
        "description": "Generate an OAuth authorization URL for a given integration. Use this to connect a new social media channel. Only OAuth-based integrations are supported (integrations that require an external URL, such as Mastodon, are not available via this endpoint).",
        "operationId": "getIntegrationUrl",
        "parameters": [
          {
            "name": "integration",
            "in": "path",
            "required": true,
            "description": "The integration identifier (e.g. x, linkedin, facebook, instagram, youtube, tiktok, reddit, etc.)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refresh",
            "in": "query",
            "required": false,
            "description": "Pass an existing integration ID to refresh its OAuth token instead of creating a new connection",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OAuth authorization URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "description": "The OAuth authorization URL to redirect the user to"
                    }
                  }
                },
                "example": {
                  "url": "https://twitter.com/i/oauth2/authorize?response_type=code&client_id=..."
                }
              }
            }
          },
          "400": {
            "description": "Integration not allowed or requires an external URL"
          }
        }
      }
    },
    "/integration-settings/{id}": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "Get integration settings and tools",
        "description": "Returns the posting rules, maximum content length, settings schema, and available provider tools for a connected channel. Use this to discover which tools can be executed with the trigger endpoint.",
        "operationId": "getIntegrationSettings",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The integration ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Settings and tools for the integration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "output": {
                      "type": "object",
                      "properties": {
                        "rules": {
                          "type": "string",
                          "description": "Platform-specific posting rules"
                        },
                        "maxLength": {
                          "type": "number",
                          "description": "Maximum content length"
                        },
                        "settings": {
                          "description": "JSON schema of the provider settings, or a string when no settings are required"
                        },
                        "tools": {
                          "type": "array",
                          "description": "Provider tools that can be executed via the trigger endpoint",
                          "items": {
                            "type": "object",
                            "properties": {
                              "methodName": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "dataSchema": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "output": {
                    "rules": "Instagram should have at least one attachment, if it's a story, it can have only one picture",
                    "maxLength": 2200,
                    "settings": {
                      "type": "object"
                    },
                    "tools": [
                      {
                        "methodName": "audioSearch",
                        "description": "Search audio (music or original sounds) to attach to a Reel via the \"audio\" setting, an empty query returns trending audio",
                        "dataSchema": [
                          {
                            "key": "q",
                            "type": "string",
                            "description": "Search query, leave empty for trending audio"
                          },
                          {
                            "key": "type",
                            "type": "string",
                            "description": "Either \"music\" or \"original_sound\", defaults to \"music\""
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Integration not found"
          }
        }
      }
    },
    "/integration-trigger/{id}": {
      "post": {
        "tags": [
          "Integrations"
        ],
        "summary": "Trigger an integration tool",
        "description": "Executes a provider-specific tool on a connected channel, for example searching Instagram audio for Reels, listing Discord channels, or fetching Reddit flairs. Discover available tools with the integration settings endpoint.",
        "operationId": "triggerIntegrationTool",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The integration ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "methodName"
                ],
                "properties": {
                  "methodName": {
                    "type": "string",
                    "description": "The tool method name, as returned by the integration settings endpoint"
                  },
                  "data": {
                    "type": "object",
                    "description": "Key-value parameters for the tool",
                    "additionalProperties": {
                      "type": "string"
                    }
                  }
                }
              },
              "example": {
                "methodName": "audioSearch",
                "data": {
                  "q": "summer vibes",
                  "type": "music"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool executed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "output": {
                      "description": "The tool result, shape depends on the tool"
                    }
                  }
                },
                "example": {
                  "output": [
                    {
                      "id": "587784541076604",
                      "title": "Summer Vibes",
                      "artist": "Some Artist",
                      "image": "https://scontent.cdninstagram.com/cover.jpg",
                      "duration": 30000,
                      "previewUrl": "https://scontent.cdninstagram.com/preview.mp4"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Channel disconnected due to expired token"
          },
          "404": {
            "description": "Integration or tool not found"
          }
        }
      }
    },
    "/is-connected": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "Check connection status",
        "description": "Verify if your API key is valid and connected.",
        "operationId": "isConnected",
        "responses": {
          "200": {
            "description": "Connection status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connected": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "connected": true
                }
              }
            }
          }
        }
      }
    },
    "/find-slot/{id}": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "Find next available slot",
        "description": "Get the next available time slot for posting to a specific channel.",
        "operationId": "findSlot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Integration ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Next available slot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                },
                "example": {
                  "date": "2025-01-15T10:00:00.000Z"
                }
              }
            }
          }
        }
      }
    },
    "/posts": {
      "get": {
        "tags": [
          "Posts"
        ],
        "summary": "List posts",
        "description": "Get posts within a date range.",
        "operationId": "listPosts",
        "parameters": [
          {
            "name": "startDate",
            "in": "query",
            "required": true,
            "description": "Start date in UTC ISO format",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-12-01T00:00:00.000Z"
          },
          {
            "name": "endDate",
            "in": "query",
            "required": true,
            "description": "End date in UTC ISO format",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2024-12-31T23:59:59.000Z"
          },
          {
            "name": "customer",
            "in": "query",
            "required": false,
            "description": "Filter by customer ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of posts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostsResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Posts"
        ],
        "summary": "Create a post",
        "description": "Create or schedule a new post. Each social media platform has its own settings schema.",
        "operationId": "createPost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePostRequest"
              },
              "examples": {
                "general": {
                  "summary": "General (Threads, Mastodon, Bluesky, Telegram, Nostr, VK, Kick)",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-integration-id"
                        },
                        "value": [
                          {
                            "content": "Hello world!",
                            "image": []
                          }
                        ],
                        "settings": {
                          "__type": "bluesky"
                        }
                      }
                    ]
                  }
                },
                "x": {
                  "summary": "X (Twitter)",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-x-integration-id"
                        },
                        "value": [
                          {
                            "content": "Hello from the Postiz API!",
                            "image": []
                          }
                        ],
                        "settings": {
                          "__type": "x",
                          "who_can_reply_post": "everyone",
                          "community": ""
                        }
                      }
                    ]
                  }
                },
                "linkedin": {
                  "summary": "LinkedIn",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-linkedin-integration-id"
                        },
                        "value": [
                          {
                            "content": "Check out our latest product showcase!",
                            "image": []
                          }
                        ],
                        "settings": {
                          "__type": "linkedin",
                          "post_as_images_carousel": false
                        }
                      }
                    ]
                  }
                },
                "linkedin-page": {
                  "summary": "LinkedIn Page",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-linkedin-page-integration-id"
                        },
                        "value": [
                          {
                            "content": "Company update: We just launched a new feature!",
                            "image": [
                              {
                                "id": "img1",
                                "path": "https://uploads.postiz.com/1.png"
                              },
                              {
                                "id": "img2",
                                "path": "https://uploads.postiz.com/2.png"
                              }
                            ]
                          }
                        ],
                        "settings": {
                          "__type": "linkedin-page",
                          "post_as_images_carousel": true,
                          "carousel_name": "Product Showcase"
                        }
                      }
                    ]
                  }
                },
                "instagram": {
                  "summary": "Instagram",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-instagram-integration-id"
                        },
                        "value": [
                          {
                            "content": "Beautiful sunset today!",
                            "image": [
                              {
                                "id": "img1",
                                "path": "https://uploads.postiz.com/photo.jpg"
                              }
                            ]
                          }
                        ],
                        "settings": {
                          "__type": "instagram",
                          "post_type": "post",
                          "is_trial_reel": false,
                          "collaborators": []
                        }
                      }
                    ]
                  }
                },
                "instagram-standalone": {
                  "summary": "Instagram Standalone",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-instagram-standalone-integration-id"
                        },
                        "value": [
                          {
                            "content": "",
                            "image": [
                              {
                                "id": "story-img",
                                "path": "https://uploads.postiz.com/story.jpg"
                              }
                            ]
                          }
                        ],
                        "settings": {
                          "__type": "instagram-standalone",
                          "post_type": "story",
                          "is_trial_reel": false,
                          "collaborators": []
                        }
                      }
                    ]
                  }
                },
                "youtube": {
                  "summary": "YouTube",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-youtube-integration-id"
                        },
                        "value": [
                          {
                            "content": "Video description here...",
                            "image": [
                              {
                                "id": "video-id",
                                "path": "https://uploads.postiz.com/video.mp4"
                              }
                            ]
                          }
                        ],
                        "settings": {
                          "__type": "youtube",
                          "title": "My Awesome Video",
                          "type": "public",
                          "selfDeclaredMadeForKids": "no",
                          "tags": [
                            {
                              "value": "tutorial",
                              "label": "tutorial"
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                "tiktok": {
                  "summary": "TikTok",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-tiktok-integration-id"
                        },
                        "value": [
                          {
                            "content": "Check this out! #viral #fyp",
                            "image": [
                              {
                                "id": "video-id",
                                "path": "https://uploads.postiz.com/tiktok.mp4"
                              }
                            ]
                          }
                        ],
                        "settings": {
                          "__type": "tiktok",
                          "privacy_level": "PUBLIC_TO_EVERYONE",
                          "duet": true,
                          "stitch": true,
                          "comment": true,
                          "autoAddMusic": "no",
                          "brand_content_toggle": false,
                          "brand_organic_toggle": false,
                          "video_made_with_ai": false,
                          "content_posting_method": "DIRECT_POST"
                        }
                      }
                    ]
                  }
                },
                "reddit": {
                  "summary": "Reddit",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-reddit-integration-id"
                        },
                        "value": [
                          {
                            "content": "Post content here...",
                            "image": []
                          }
                        ],
                        "settings": {
                          "__type": "reddit",
                          "subreddit": [
                            {
                              "value": {
                                "subreddit": "programming",
                                "title": "My Post Title",
                                "type": "self",
                                "url": "",
                                "is_flair_required": false,
                                "flair": null
                              }
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                "lemmy": {
                  "summary": "Lemmy",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-lemmy-integration-id"
                        },
                        "value": [
                          {
                            "content": "Post content here...",
                            "image": []
                          }
                        ],
                        "settings": {
                          "__type": "lemmy",
                          "subreddit": [
                            {
                              "value": {
                                "subreddit": "technology",
                                "id": "community-id",
                                "title": "My Post Title",
                                "url": ""
                              }
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                "pinterest": {
                  "summary": "Pinterest",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-pinterest-integration-id"
                        },
                        "value": [
                          {
                            "content": "Pin description here...",
                            "image": [
                              {
                                "id": "pin-img",
                                "path": "https://uploads.postiz.com/pin.jpg"
                              }
                            ]
                          }
                        ],
                        "settings": {
                          "__type": "pinterest",
                          "board": "board-id",
                          "title": "My Pin",
                          "link": "https://example.com"
                        }
                      }
                    ]
                  }
                },
                "dribbble": {
                  "summary": "Dribbble",
                  "value": {
                    "type": "schedule",
                    "date": "2024-12-14T10:00:00.000Z",
                    "shortLink": false,
                    "tags": [],
                    "posts": [
                      {
                        "integration": {
                          "id": "your-dribbble-integration-id"
                        },
                        "value": [
                          {
                            "content": "Shot description here...",
                     

# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/postiz/refs/heads/main/openapi/postiz-public-api-openapi.json