Skip to content

Usage — API / CLI / MCP

postiz-agent exposes the same capability three ways: as MCP tools an agent calls, as a Python API (PostizApi) the operator import, and through its console scripts. The connector's role and architecture are covered in Overview.

As an MCP server

Once deployed, the server serves one typed tool per Postiz public API operation (37 operations), plus three knowledge-graph ingest tools:

Area Tools
Channels postiz_list_integrations, postiz_get_integration_settings, postiz_get_integration_url, postiz_check_connection, postiz_get_me, postiz_list_groups, postiz_trigger_integration_tool, postiz_delete_channel
Posts and calendar postiz_list_posts, postiz_create_post, postiz_change_post_status, postiz_update_post_settings, postiz_delete_post, postiz_delete_post_by_group, postiz_find_slot, postiz_get_missing_content, postiz_update_release_id
Media postiz_upload_file_content, postiz_upload_from_url, postiz_upload_file, postiz_list_media, postiz_generate_video, postiz_video_function, postiz_start_clipping, postiz_list_clippings, postiz_get_clipping
Preview and review postiz_get_post_preview, postiz_list_post_comments, postiz_create_post_comment
Analytics postiz_get_analytics, postiz_get_post_analytics, postiz_list_notifications
Diagnostics (super-admin key) postiz_list_users, postiz_get_post_timeline, postiz_get_account_overview, postiz_get_channel_health, postiz_get_org_activity, postiz_reset_credits
Knowledge graph postiz_ingest_posts, postiz_ingest_integrations, postiz_ingest_analytics

The server also serves the social_media_manager prompt, the packaged skills (including postiz-campaign-post-from-asset) and the ontology (social.ttl, pack.ttl). Example agent prompts:

  • "List the social channels connected to my Postiz account" → postiz_list_integrations
  • "Draft this image for X next Tuesday at 9am" → postiz_upload_file_content, postiz_create_post
  • "How did last week's posts perform?" → postiz_get_post_analytics

As a Python API

PostizApi aggregates the per-domain clients (integrations, posts, uploads, video, notifications, analytics) behind one requests-based facade.

from postiz_agent.api_client import PostizApi

api = PostizApi(
    base_url="https://api.postiz.com/public/v1",
    token="your_postiz_token",
)

# Reads
integrations = api.get_integrations()                       # connected channels
posts = api.list_posts("2026-06-01", "2026-06-30")          # scheduled / published posts
notifications = api.list_notifications(page=0)              # account notifications

# Analytics for a connected channel (date window in days)
analytics = api.get_analytics(integrations[0].id, date="7")

Build a client straight from the environment:

from postiz_agent.auth import get_client
api = get_client()        # reads POSTIZ_URL / POSTIZ_TOKEN and AgentConfig TLS policy

The client reads POSTIZ_URL and POSTIZ_TOKEN; its mandatory checked TLS policy is resolved from AgentConfig. It remains a singleton for the process lifetime.

As a CLI

The package installs two console scripts:

# MCP server (stdio by default, or an HTTP transport)
postiz-mcp --transport streamable-http --host 0.0.0.0 --port 8000

# A2A agent server (port 9004) — wraps the tool surface in a Pydantic-AI agent
postiz-agent --provider openai --model-id gpt-4o --api-key sk-...

Both read their connection settings from the environment / .env; see Deployment for the complete variable set.