Nitty Music Social Management
Nitty Music Social Management

Overview

API Overview

Getting started with the Nitty Music Social Public API

SDK

Node.js SDK

Official Nitty Music Social Node.js SDK

Authentication

There are two ways to authenticate with the Nitty Music Social API:

API Key

Include it in the Authorization header:

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

OAuth2 Token

If you’re building an app for other Nitty Music Social 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://social.nittymusic.com/api/public/v1/integrations

Base URL

Rate Limits

90 requests per hour limit applies only to 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 for the whole instance. It does not tier by subscription plan. Plans tier on channel and post-per-month quotas instead. Self-hosters can adjust the per-hour limit with the API_LIMIT env var (see Configuration Reference).

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 Nitty Music Social 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 uses the same composer as Nitty Music Social, but generates the JSON payload instead of scheduling the post.

Make sure you are signed in to Nitty Music Social before opening the wizard.

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) |

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 Nitty Music Social 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://social.nittymusic.com/api/public/v1/upload" \
  -H "Authorization: your-api-key" \
  -F "file=@photo.jpg"

# Response: { "id": "img-123", "path": "https://media.nittymusic.com/uploads/photo.jpg", ... }

# Step 2: Create the post with the uploaded image
curl -X POST "https://social.nittymusic.com/api/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://media.nittymusic.com/uploads/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"
      }
    }
  ]
}