API Overview - Groniz Documentation

Clients & Integrations

The API is plain HTTP + JSON, so any language works with a bare request. Two first-party clients wrap it for you:

Groniz CLI

Drive the API from your terminal or a coding agent — curl -fsSL https://groniz.com/install.sh | sh

MCP Server

Expose Groniz as tools to any MCP client (Claude, Cursor, …) at https://mcp.groniz.com/mcp

Authentication

There are two ways to authenticate with the Groniz API:

API Key

Get your API key from Settings > Developers > Public API. Include it in the Authorization header:

curl -H "Authorization: your-api-key" https://api.groniz.com/public/v1/integrations

OAuth2 Token

If you’re building an app for other Groniz users, use OAuth2 Authentication to get tokens that act on behalf of users. OAuth tokens start with pos_ and are used the same way:

curl -H "Authorization: pos_your-oauth-token" https://api.groniz.com/public/v1/integrations

Base URL

All requests go to:

https://api.groniz.com/public/v1

Rate Limits

90 requests per hour (100 for the cloud) limit applies to only the create post endpoint.This doesn’t mean you can only post 90 times per hour—each API call counts as one request. Schedule multiple posts in a single request to maximize throughput.

The rate limit is a single global value — it doesn’t tier by subscription plan. Plans tier on channel and post-per-month quotas instead.

Errors

Status	Meaning
`400 Bad Request`	The request body or path parameter is malformed (wrong shape, unknown enum, missing required field).
`401 Unauthorized`	`Authorization` header is missing or the API key is unrecognised.
`403 Forbidden`	The API key is valid but doesn’t own the resource (e.g. you tried to delete a post in another organisation).
`404 Not Found`	The endpoint doesn’t exist, or the path parameter (integration ID, post ID) was correct format but no row matched.
`413 Payload Too Large`	Your request body exceeded 50 MB on `/posts` — usually because images were base64-inlined instead of pre-uploaded. See Uploads troubleshooting.
`429 Too Many Requests`	You exceeded `API_LIMIT` per hour on the create-post endpoint.
`5xx`	Server error — retry with exponential backoff.

For DELETE endpoints, 404 always means “already deleted” and is safe to ignore. A 500 can mean the same thing today because of a known issue where a missing post ID surfaces as 500 instead of 404 — but only if the error matches that specific signature. Treat other 500 responses as real server errors: log them, retry with exponential backoff, and don’t silently suppress them.

Terminology

The Groniz UI uses the term channel, while the API uses integration. They refer to the same thing—a connected social media account.

Generate Output

The easiest way to generate your post payloads is by using this wizard. It’s the same wizard used to schedule posts in the Groniz app, but instead of scheduling, it generates the JSON payload for you to use in your API requests. Make sure you are signed in to the console first.

Open in full screen

Supported Platforms (32 total)

When creating posts, each social media platform has its own settings schema. The settings object must include a __type field matching the provider.

Platforms with custom settings (25)

Platform	`__type`	Key settings
X (Twitter)	`x`	`who_can_reply_post`, `community`
LinkedIn	`linkedin`	`post_as_images_carousel`
LinkedIn Page	`linkedin-page`	`post_as_images_carousel`
Facebook	`facebook`	`url` (optional)
Instagram (FB-linked)	`instagram`	`post_type`, `collaborators`
Instagram Standalone	`instagram-standalone`	`post_type`, `collaborators`
Warpcast (Farcaster)	`warpcast`	`subreddit[]` (channels)

Platform	`__type`	Key settings
YouTube	`youtube`	`title`, `type`, `selfDeclaredMadeForKids`, `thumbnail`, `tags`
TikTok	`tiktok`	`privacy_level`, `duet`, `stitch`, `comment`, `autoAddMusic`, `brand_content_toggle`, `brand_organic_toggle`, `content_posting_method`

Platform	`__type`	Key settings
Reddit	`reddit`	`subreddit[]` with `title`, `type`, `flair`
Lemmy	`lemmy`	`subreddit[]` with `id`, `title`, `url`
Discord	`discord`	`channel`
Slack	`slack`	`channel`
Skool	`skool`	`group`, `label`, `title`
Whop	`whop`	`company`, `experience`, `title`

Platform	`__type`	Key settings
Pinterest	`pinterest`	`board`, `title`, `link`, `dominant_color`
Dribbble	`dribbble`	`title`, `team`

Platform	`__type`	Key settings
Medium	`medium`	`title`, `subtitle`, `canonical`, `publication`, `tags`
Dev.to	`devto`	`title`, `main_image`, `canonical`, `organization`, `tags`
Hashnode	`hashnode`	`title`, `subtitle`, `main_image`, `publication`, `tags`
WordPress	`wordpress`	`title`, `main_image`, `type`

Platform	`__type`	Key settings
Google My Business	`gmb`	`topicType`, `callToActionType`, `callToActionUrl`, event/offer fields
Listmonk	`listmonk`	`subject`, `preview`, `list`, `template`

Platform	`__type`	Key settings
Twitch	`twitch`	`messageType`, `announcementColor`

Platforms without custom settings (7)

These platforms only require { "__type": "platform-name" }:

Platform	`__type`
Threads	`threads`
Mastodon	`mastodon`
Bluesky	`bluesky`
Telegram	`telegram`
Nostr	`nostr`
VK	`vk`
Kick	`kick`

View Provider Settings Reference

See detailed settings schemas with examples for each platform

Quick Examples

Schedule a post to X (Twitter)

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-integration-id" },
      "value": [
        {
          "content": "Hello from the Groniz API! 🚀",
          "image": []
        }
      ],
      "settings": {
        "__type": "x",
        "who_can_reply_post": "everyone"
      }
    }
  ]
}

Post immediately to LinkedIn

{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-linkedin-id" },
      "value": [
        {
          "content": "Exciting announcement! 🎉",
          "image": []
        }
      ],
      "settings": {
        "__type": "linkedin"
      }
    }
  ]
}

Upload an image and post to Instagram

# Step 1: Upload the image
curl -X POST "https://api.groniz.com/public/v1/upload" \
  -H "Authorization: your-api-key" \
  -F "[email protected]"

# Response: { "id": "img-123", "path": "https://api.groniz.com/photo.jpg", ... }

# Step 2: Create the post with the uploaded image
curl -X POST "https://api.groniz.com/public/v1/posts" \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2024-12-14T10:00:00.000Z",
    "shortLink": false,
    "tags": [],
    "posts": [{
      "integration": { "id": "your-instagram-id" },
      "value": [{
        "content": "Beautiful sunset 🌅 #photography",
        "image": [{ "id": "img-123", "path": "https://api.groniz.com/photo.jpg" }]
      }],
      "settings": {
        "__type": "instagram",
        "post_type": "post"
      }
    }]
  }'

Publish a Medium article

{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-medium-id" },
      "value": [
        {
          "content": "# Introduction\n\nThis is my article in markdown...",
          "image": []
        }
      ],
      "settings": {
        "__type": "medium",
        "title": "My Amazing Article",
        "subtitle": "A deep dive into something interesting",
        "tags": [
          { "value": "programming", "label": "Programming" }
        ]
      }
    }
  ]
}

Create a Google My Business offer

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-gmb-id" },
      "value": [
        {
          "content": "🎉 Holiday Sale! 20% off everything!",
          "image": []
        }
      ],
      "settings": {
        "__type": "gmb",
        "topicType": "OFFER",
        "callToActionType": "GET_OFFER",
        "callToActionUrl": "https://example.com/sale",
        "offerCouponCode": "HOLIDAY20"
      }
    }
  ]
}

​Clients & Integrations

Groniz CLI

MCP Server

​Authentication

​API Key

​OAuth2 Token

​Base URL

​Rate Limits

​Errors

​Terminology

​Generate Output

​Supported Platforms (32 total)

​Platforms with custom settings (25)

​Platforms without custom settings (7)

View Provider Settings Reference

​Quick Examples

​Schedule a post to X (Twitter)

​Post immediately to LinkedIn

​Upload an image and post to Instagram

​Publish a Medium article

​Create a Google My Business offer

Clients & Integrations

Authentication

API Key

OAuth2 Token

Base URL

Rate Limits

Errors

Terminology

Generate Output

Supported Platforms (32 total)

Platforms with custom settings (25)

Platforms without custom settings (7)

Quick Examples

Schedule a post to X (Twitter)

Post immediately to LinkedIn

Upload an image and post to Instagram

Publish a Medium article

Create a Google My Business offer