Accounts

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,
      "byo_keys": false,
      "is_active": true,
      "scheduled_posts": 0,
      "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,
      "scheduled_posts": 2,
      "created_at": "2026-03-15T00:00:00.000Z"
    },
    {
      "id": "770a0600-a41d-63f6-c938-668877662222",
      "platform": "linkedin",
      "platform_user_id": "abc123",
      "username": "John Doe",
      "display_name": "John Doe",
      "avatar_url": "https://media.licdn.com/...",
      "max_post_length": 3000,
      "account_type": "member",
      "is_active": true,
      "scheduled_posts": 0,
      "created_at": "2026-03-20T00:00:00.000Z"
    },
    {
      "id": "990c2800-c63f-85h8-e150-880099884444",
      "platform": "linkedin",
      "platform_user_id": "5515715",
      "username": "Acme Robotics",
      "display_name": "Acme Robotics",
      "avatar_url": "https://media.licdn.com/...",
      "max_post_length": 3000,
      "account_type": "organization",
      "is_active": true,
      "scheduled_posts": 0,
      "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": false,
      "inactive_reason": "plan_limit",
      "scheduled_posts": 0,
      "created_at": "2026-03-22T00:00:00.000Z"
    }
  ],
  "accounts_limit": 3,
  "accounts_active": 3
}

Response Envelope

Inactive accounts are still listed, so data can be longer than accounts_active. Use PATCH /api/v1/accounts/{id} to choose which accounts are on.

Account Fields

Activate or Deactivate an Account

PATCH /api/v1/accounts/{id}
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json

{
  "is_active": true
}

Response 200 OK

Returns the updated account, in the same shape as GET /api/v1/accounts, plus canceled_posts.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "platform": "facebook",
    "platform_user_id": "101234567890123",
    "username": "Firecode.io",
    "display_name": "Firecode.io",
    "avatar_url": "https://scontent.xx.fbcdn.net/...",
    "max_post_length": 63206,
    "is_active": true,
    "canceled_posts": 0,
    "created_at": "2026-03-22T00:00:00.000Z"
  }
}

Chirpie never discards a connected account when your plan runs out of room. Connecting a platform that grants several profiles at once (Facebook, where one authorization can hand back every Page you manage, and Instagram connected via Facebook, which brings in the Instagram account linked to each of those Pages) stores them all and switches on as many as your plan allows. The rest are listed with is_active: false and inactive_reason: "plan_limit", and this endpoint is how you choose which ones publish.

Deactivating keeps the account connected and frees a slot against your plan's account limit, so you can switch a different one on without reauthorizing.

Errors

Disconnect an Account

DELETE /api/v1/accounts/{id}
Authorization: Bearer chirpie_sk_YOUR_KEY

Ends the connection. The account stops publishing immediately and stops counting against your plan's account limit, and Chirpie lets go of the credential it stored for it.

Response 200 OK

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "disconnected": true,
    "canceled_posts": 2
  }
}

Disconnect or deactivate?

Deactivate when you mean to switch the account on again, for example to make room for a different one on the same plan. Disconnect when you are done with it.

Posts a disconnected account published keep their text, status, platform ID and analytics snapshots. They stop reporting that account's handle, because the account is no longer connected.

Errors

Connecting an Account

POST /api/v1/accounts checks the request in this order:

1. platform is validated. An unrecognised value returns 400 bad_request naming the values you can use: Unknown platform 'twitter'. Supported: x, bluesky, linkedin, threads, mastodon, instagram, facebook, telegram. Omitting platform still means "x".
2. Platform availability. A platform that is not connectable returns 501, with code platform_coming_soon or platform_unsupported.
3. Your plan's account limit. A new connection that would take you past the limit returns 429 with code account_limit_reached.

Reconnecting never needs a free slot

If you already have at least one account on that platform, the account limit is not applied. Re-authorizing an X account whose token expired, or reconnecting an X account to move it onto your own X developer app, therefore works on every plan, including Free. Connecting a platform you have no account on still needs a free slot.

Connect Errors

A failed start names the platform and never passes on the platform's raw answer:

{
  "error": {
    "code": "upstream_error",
    "message": "Mastodon refused the connection request. Try again in a moment, and if it keeps happening contact support."
  }
}

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, it defaults to "x". A platform value that is not recognised is rejected, rather than falling back 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"
}

Response 201 Created

Reconnecting an account you already hold returns 200 OK with the same body.

{
  "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 checks that the password has the shape of an app password, and refuses anything else before Bluesky is asked
3. Chirpie validates the credentials against the AT Protocol
4. Chirpie stores the encrypted app password
5. The account appears in GET /api/v1/accounts

Errors

A value that is not shaped like an app password answers 400 bluesky_app_password_required. The message never repeats the value you sent:

{
  "error": {
    "code": "bluesky_app_password_required",
    "message": "Bluesky needs an app password, not your account password. Create one in Bluesky under Settings, Privacy and Security, App Passwords (https://bsky.app/settings/app-passwords). It looks like xxxx-xxxx-xxxx-xxxx."
  }
}

A correctly shaped app password Bluesky does not recognise (revoked, or a typo) answers 401 unauthorized with Bluesky's own reason.

Connect a LinkedIn Account

POST /api/v1/accounts
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json

{
  "platform": "linkedin"
}

Request Fields

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 connected accounts appear in GET /api/v1/accounts

Profiles and Pages (Pages: Coming Soon)

LinkedIn has two kinds of account and they are two separate connections.

Your own LinkedIn profile is the default, and is what you get with no target or with "target": "profile".

The LinkedIn Pages you administer are connected with "target": "pages". Each Page becomes an account with its own id. Connecting Pages does not change or replace your profile connection, and you can have both.

{
  "platform": "linkedin",
  "target": "pages"
}

Each account's account_type says which it is: "member" for your profile, "organization" for a Page. Both post exactly the same way, by passing that account's id as account_id.

Pages count towards your plan's account limit like any other account, so a connection that finds more Pages than your plan has room for stores the extras switched off with inactive_reason: "plan_limit", and you choose which ones to activate. A connection that finds no Pages you administer says so and changes nothing.

Connecting LinkedIn Pages is coming soon. Until it lands, a request with "target": "pages" answers 501 with { "error": { "code": "platform_coming_soon", "message": "LinkedIn Pages support is coming soon." } }. Connecting your profile is unaffected.

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

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"
}

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 server, handle or profile 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

Each connect registers Chirpie on your server afresh, so a server that is down, slow (more than 15 seconds) or refusing new apps answers 502 upstream_error naming Mastodon. Retry once the server is reachable.

A profile URL for an account on another server, such as https://mastodon.social/@you@fosstodon.org, connects you on the account's own server (fosstodon.org). A value that names no server, or one over plain HTTP, answers 400 mastodon_instance_invalid:

{
  "error": {
    "code": "mastodon_instance_invalid",
    "message": "Enter your Mastodon server (mastodon.social), your handle (@you@mastodon.social) or your profile URL (https://mastodon.social/@you)."
  }
}

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://www.instagram.com/oauth/authorize?..."
  }
}

Two ways to connect

Both publish, thread, schedule, and report analytics identically, and every publishing option works on both. They differ in one way: on an account connected via Facebook, DELETE /api/v1/posts/{id} really removes the post from Instagram, and on an account connected through Instagram it answers 501 delete_unsupported.

Each account reports its route as oauth_variant in GET /api/v1/accounts.

Switching an account from one route to the other

Connect an account you already have through the other route and Chirpie moves the connection it already has rather than adding a second one: the account keeps its id and everything it has published, and its oauth_variant changes to the route you just used. Going to "via": "facebook" adds deleting published posts; coming back to "via": "instagram" takes it away again, and everything else is unchanged. Where the two routes report different Instagram accounts you get a second account instead, listed alongside the first. See Connect an Instagram account.

How it Works

1. Call POST /api/v1/accounts with "platform": "instagram", and via if you want the Facebook route
2. Redirect the user to the returned authorization_url
3. The user authorizes Chirpie, on Instagram or on Facebook
4. The platform redirects to Chirpie's callback URL
5. Chirpie stores the encrypted OAuth tokens
6. The account appears in GET /api/v1/accounts

Several accounts from one Facebook authorization

"via": "facebook" connects the Instagram professional account linked to each Facebook Page the user shares, so one authorization can bring in several accounts, one row per Page. They count towards your plan's account limit like any other account, so anything beyond the limit is stored with is_active: false and inactive_reason: "plan_limit" rather than dropped. Choose which ones publish with PATCH /api/v1/accounts/{id}, or upgrade for more account slots.

Two outcomes finish the flow with nothing connected, and each says what to do:

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. The user authorizes Chirpie on Facebook and chooses which Pages to grant
4. Facebook redirects to Chirpie's callback URL
5. Chirpie stores a never-expiring page access token for every granted Page
6. Each Page appears as its own account in GET /api/v1/accounts

Multiple Pages and your plan limit

One Facebook authorization can grant many Pages at once. Choosing "all current and future Pages" grants every Page you manage, including Pages owned by a Business Portfolio. Chirpie imports all of them, in one account row per Page.

Pages you can post to are kept; a Page whose role does not allow creating content is skipped. Then, if your plan includes fewer accounts than you granted Pages, Chirpie switches on as many as it can and stores the rest with is_active: false and inactive_reason: "plan_limit". Nothing is dropped. Choose which Pages publish with PATCH /api/v1/accounts/{id}, or upgrade for more account slots.

Reconnecting Facebook re-runs the import, so Pages added later are picked up without disconnecting anything. Send "reconnect": true alongside "platform": "facebook" when you are re-running the flow for someone who has authorized before, so Facebook asks again about anything they turned down last time.

If a Page is missing after connecting

Facebook only hands over the Pages you tick in its authorization window, so a connect can finish with fewer Pages than you manage. Chirpie tells you which case you hit:

Pages already connected stay connected while you retry, and Pages you manage through a Business Portfolio are imported too, not only the ones under a direct Page role.

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"
}

Response 201 Created

Returns the connected account object. Reconnecting a bot and chat you already hold returns 200 OK with the same body.

More Platforms

Pinterest, TikTok, YouTube, and Google Business Profile are coming soon. Connecting one today answers 501 with { "error": { "code": "platform_coming_soon", "message": "<platform> support is coming soon." } }. Accounts already connected keep posting, scheduling and reporting analytics as normal.

Use Your Own X Developer App

By default, X accounts connect through Chirpie's X developer app. You can instead register your own app from developer.x.com so your X accounts post against your X API credits. Link posts from accounts connected this way are not surcharged.

See the Bring your own X keys guide for the full walkthrough, including the app settings and scopes X requires.

Set or Replace Your Keys

PUT /api/v1/accounts/x/keys
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: application/json

{
  "client_id": "YOUR_X_OAUTH2_CLIENT_ID",
  "client_secret": "YOUR_X_OAUTH2_CLIENT_SECRET",
  "label": "Acme social app"
}

Response 200 OK

{
  "data": {
    "configured": true,
    "label": "Acme social app",
    "client_id_last4": "3456",
    "redirect_uri": "https://chirpie.ai/api/auth/x/callback",
    "required_scopes": ["tweet.read", "tweet.write", "users.read", "offline.access", "media.write"],
    "created_at": "2026-09-05T00:00:00.000Z",
    "updated_at": "2026-09-05T00:00:00.000Z",
    "message": "Saved. Add https://chirpie.ai/api/auth/x/callback as a callback URI on your X app, then reconnect your X account to switch it onto your app."
  }
}

Check Status

GET /api/v1/accounts/x/keys
Authorization: Bearer chirpie_sk_YOUR_KEY

Response 200 OK

{
  "data": {
    "configured": true,
    "label": "Acme social app",
    "client_id_last4": "3456",
    "redirect_uri": "https://chirpie.ai/api/auth/x/callback",
    "created_at": "2026-09-05T00:00:00.000Z",
    "updated_at": "2026-09-05T00:00:00.000Z"
  }
}

The client secret is never returned, only the last four characters of the client ID, so you can confirm which app is stored.

When no keys are registered, the same endpoint returns 200 OK with configured: false rather than a 404:

{
  "data": {
    "configured": false,
    "label": null,
    "client_id_last4": null,
    "redirect_uri": "https://chirpie.ai/api/auth/x/callback",
    "created_at": null,
    "updated_at": null
  }
}

Remove Your Keys

DELETE /api/v1/accounts/x/keys
Authorization: Bearer chirpie_sk_YOUR_KEY

Response 200 OK

{
  "data": {
    "configured": false,
    "removed": true,
    "message": "X developer keys removed. Reconnect any X account that was using them."
  }
}

Returns 404 if no keys are configured.

Account Limits