ChirpieDocs
API Reference

Accounts

List and connect X/Twitter, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, Telegram, Reddit, Pinterest, TikTok, YouTube, Google Business Profile, and Snapchat accounts to post through Chirpie.

List Connected Accounts

GET /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY

Response 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "platform": "x",
      "platform_user_id": "123456789",
      "username": "chirpie_ai",
      "display_name": "Chirpie",
      "avatar_url": "https://pbs.twimg.com/...",
      "max_post_length": 25000,
      "is_active": true,
      "created_at": "2026-03-01T00:00:00.000Z"
    },
    {
      "id": "660f9500-f30c-52e5-b827-557766551111",
      "platform": "bluesky",
      "platform_user_id": "did:plc:abc123",
      "username": "chirpie.bsky.social",
      "display_name": "Chirpie",
      "avatar_url": "https://cdn.bsky.app/...",
      "max_post_length": 300,
      "is_active": true,
      "created_at": "2026-03-15T00:00:00.000Z"
    },
    {
      "id": "770a0600-a41d-63f6-c938-668877662222",
      "platform": "linkedin",
      "platform_user_id": "urn:li:person:abc123",
      "username": "johndoe",
      "display_name": "John Doe",
      "avatar_url": "https://media.licdn.com/...",
      "max_post_length": 3000,
      "is_active": true,
      "created_at": "2026-03-20T00:00:00.000Z"
    },
    {
      "id": "880b1700-b52e-74g7-d049-779988773333",
      "platform": "threads",
      "platform_user_id": "12345678901",
      "username": "chirpie_ai",
      "display_name": "Chirpie",
      "avatar_url": "https://scontent.cdninstagram.com/...",
      "max_post_length": 500,
      "is_active": true,
      "created_at": "2026-03-22T00:00:00.000Z"
    }
  ]
}

Account Fields

FieldDescription
idChirpie account UUID — use this as account_id when creating posts
platform"x", "bluesky", "linkedin", "threads", "mastodon", "instagram", "facebook", "telegram", "reddit", "pinterest", "tiktok", "youtube", "google_business", or "snapchat"
platform_user_idPlatform-specific user ID (X numeric ID, Bluesky DID, LinkedIn URN, Threads user ID, Mastodon account ID, Instagram user ID, Facebook Page ID, Telegram bot ID, Reddit username, Pinterest user ID, TikTok open ID, YouTube channel ID, Google Business location ID, or Snapchat user ID)
usernameUsername on the platform
display_nameDisplay name on the platform
avatar_urlProfile picture URL
max_post_lengthMaximum post length: 280 (X standard), 25000 (X Premium), 300 (Bluesky), 3000 (LinkedIn), 500 (Threads), 500 (Mastodon), 2200 (Instagram), 63206 (Facebook), 4096 (Telegram), 40000 (Reddit), 500 (Pinterest), 2200 (TikTok), 5000 (YouTube), 1500 (Google Business Profile), or 160 (Snapchat)
is_activetrue if credentials are valid. false if tokens expired or were revoked

If is_active is false, the account needs re-authorization. For OAuth-based accounts (X, LinkedIn, Threads, Mastodon, Instagram, Facebook, Reddit, Pinterest, TikTok, YouTube, Google Business Profile, Snapchat), re-authorize from the dashboard. For Bluesky, generate a new app password and reconnect. For Telegram, verify your bot token and chat ID.

Connect an X Account

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "x"
}

No additional fields are required. If platform is omitted, defaults to "x".

Response 200 OK

{
  "data": {
    "authorization_url": "https://twitter.com/i/oauth2/authorize?..."
  }
}

How it Works

  1. Call POST /api/v1/accounts with "platform": "x"
  2. Redirect the user to the returned authorization_url
  3. User authorizes Chirpie on X
  4. X redirects to Chirpie's callback URL
  5. Chirpie stores the encrypted OAuth tokens
  6. The account appears in GET /api/v1/accounts

Connect a Bluesky Account

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "bluesky",
  "identifier": "yourhandle.bsky.social",
  "app_password": "xxxx-xxxx-xxxx-xxxx"
}
FieldTypeRequiredDescription
platformstringYesMust be "bluesky"
identifierstringYesYour Bluesky handle (e.g., yourhandle.bsky.social)
app_passwordstringYesApp password from Bluesky Settings > App Passwords

Response 201 Created

{
  "data": {
    "id": "660f9500-f30c-52e5-b827-557766551111",
    "platform": "bluesky",
    "platform_user_id": "did:plc:abc123",
    "username": "yourhandle.bsky.social",
    "display_name": "Your Name",
    "avatar_url": "https://cdn.bsky.app/...",
    "max_post_length": 300,
    "is_active": true,
    "created_at": "2026-03-15T00:00:00.000Z"
  }
}

How it Works

  1. Call POST /api/v1/accounts with your Bluesky handle and app password
  2. Chirpie validates the credentials against the AT Protocol
  3. Chirpie stores the encrypted app password
  4. The account appears in GET /api/v1/accounts

Generate an app password from Bluesky Settings > App Passwords. Do not use your main account password.

Connect a LinkedIn Account

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "linkedin"
}

Response 200 OK

{
  "data": {
    "authorization_url": "https://www.linkedin.com/oauth/v2/authorization?..."
  }
}

How it Works

  1. Call POST /api/v1/accounts with "platform": "linkedin"
  2. Redirect the user to the returned authorization_url
  3. User authorizes Chirpie on LinkedIn
  4. LinkedIn redirects to Chirpie's callback URL
  5. Chirpie stores the encrypted OAuth tokens
  6. The account appears in GET /api/v1/accounts

LinkedIn uses OAuth 2.0. The authorization flow requires the user to grant Chirpie permission to post on their behalf. Tokens are refreshed automatically when they expire.

Connect a Threads Account

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "threads"
}

Response 200 OK

{
  "data": {
    "authorization_url": "https://threads.net/oauth/authorize?..."
  }
}

How it Works

  1. Call POST /api/v1/accounts with "platform": "threads"
  2. Redirect the user to the returned authorization_url
  3. User authorizes Chirpie via Meta OAuth
  4. Threads redirects to Chirpie's callback URL
  5. Chirpie stores the encrypted OAuth tokens
  6. The account appears in GET /api/v1/accounts

Threads uses Meta's OAuth 2.0 flow. You'll authorize through your Instagram/Meta account that is linked to your Threads profile. Tokens are refreshed automatically when they expire.

Connect a Mastodon Account

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "mastodon",
  "instance_url": "https://mastodon.social"
}
FieldTypeRequiredDescription
platformstringYesMust be "mastodon"
instance_urlstringYesYour Mastodon instance URL (e.g., https://mastodon.social, https://fosstodon.org)

Response 200 OK

{
  "data": {
    "authorization_url": "https://mastodon.social/oauth/authorize?..."
  }
}

How it Works

  1. Call POST /api/v1/accounts with "platform": "mastodon" and your instance URL
  2. Redirect the user to the returned authorization_url
  3. User authorizes Chirpie on their Mastodon instance
  4. Mastodon redirects to Chirpie's callback URL
  5. Chirpie stores the encrypted OAuth tokens
  6. The account appears in GET /api/v1/accounts

Mastodon uses OAuth 2.0. Chirpie dynamically registers as an OAuth app on your instance. Mastodon tokens do not expire. If a token is revoked, re-authorize from the dashboard. Works with any Mastodon-compatible instance (Mastodon, Hometown, Glitch-soc, etc.).

Connect an Instagram Account

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "instagram"
}

Response 200 OK

{
  "data": {
    "authorization_url": "https://api.instagram.com/oauth/authorize?..."
  }
}

How it Works

  1. Call POST /api/v1/accounts with "platform": "instagram"
  2. Redirect the user to the returned authorization_url
  3. User authorizes Chirpie via Instagram Login
  4. Instagram redirects to Chirpie's callback URL
  5. Chirpie stores the encrypted OAuth tokens
  6. The account appears in GET /api/v1/accounts

Instagram uses Instagram Login (OAuth 2.0). You'll authorize through your Instagram account. Tokens are refreshed automatically when they expire. Instagram requires media — text-only posts are not supported. Each post must include at least one image. Carousel posts support 2-10 images.

Connect a Facebook Page

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "facebook"
}

Response 200 OK

{
  "data": {
    "authorization_url": "https://www.facebook.com/v22.0/dialog/oauth?..."
  }
}

How it Works

  1. Call POST /api/v1/accounts with "platform": "facebook"
  2. Redirect the user to the returned authorization_url
  3. User authorizes Chirpie via Facebook Login and selects a Page
  4. Facebook redirects to Chirpie's callback URL
  5. Chirpie stores the never-expiring page access token
  6. The account appears in GET /api/v1/accounts

Facebook uses Facebook Login (OAuth 2.0). Chirpie posts to Facebook Pages only (not personal profiles). Page access tokens are long-lived and do not expire under normal conditions. Text-only posts are supported.

Connect a Telegram Bot

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json
{
  "platform": "telegram",
  "bot_token": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ",
  "chat_id": "-1001234567890"
}
FieldTypeRequiredDescription
platformstringYesMust be "telegram"
bot_tokenstringYesBot token from @BotFather
chat_idstringYesChannel or group chat ID (e.g., @channelname or numeric ID)

Response 201 Created

Returns the connected account object.

Create a bot via @BotFather on Telegram. Add the bot as an admin to your channel or group. Telegram does not use OAuth. Analytics are not available for Telegram (no metrics API).

Connect a Reddit Account (Coming Soon)

Connect a Pinterest Account (Coming Soon)

Connect a TikTok Account (Coming Soon)

Connect a YouTube Channel (Coming Soon)

Connect a Google Business Profile (Coming Soon)

Connect a Snapchat Account (Coming Soon)

Account Limits

PlanMax Accounts (across all platforms)
Free1
Starter3
Pro10
Scale25
EnterpriseUnlimited

Threads

Create multi-post threads that publish as connected replies on X, Bluesky, Threads, Mastodon, and Telegram — threaded via comments on Reddit — or as standalone posts on LinkedIn, Instagram, Facebook, Pinterest, TikTok, YouTube, Google Business Profile, and Snapchat.

API Keys

Create, list, and revoke API keys programmatically.

On this page

List Connected AccountsResponse 200 OKAccount FieldsConnect an X AccountResponse 200 OKHow it WorksConnect a Bluesky AccountResponse 201 CreatedHow it WorksConnect a LinkedIn AccountResponse 200 OKHow it WorksConnect a Threads AccountResponse 200 OKHow it WorksConnect a Mastodon AccountResponse 200 OKHow it WorksConnect an Instagram AccountResponse 200 OKHow it WorksConnect a Facebook PageResponse 200 OKHow it WorksConnect a Telegram BotResponse 201 CreatedConnect a Reddit Account (Coming Soon)Connect a Pinterest Account (Coming Soon)Connect a TikTok Account (Coming Soon)Connect a YouTube Channel (Coming Soon)Connect a Google Business Profile (Coming Soon)Connect a Snapchat Account (Coming Soon)Account Limits