Accounts API

The /v1/accounts endpoints manage the social accounts connected to your organization. You'll need account IDs to target posts.

Requires authentication. All data is scoped to your organization.

---

List accounts

GET /api/v1/accounts

Returns the connected social accounts in your organization. Disconnected accounts (those with a disconnectedAt timestamp) are excluded.

Example

curl https://<your-api-origin>/api/v1/accounts \
  -H "Authorization: Bearer sx_live_YOUR_API_KEY"

Response — 200 OK

{
  "data": [
    {
      "id": "acc_abc123",
      "platform": "instagram",
      "username": "postbuzz",
      "displayName": "post.buzz"
    },
    {
      "id": "acc_def456",
      "platform": "x",
      "username": "postbuzz",
      "displayName": "post.buzz"
    }
  ]
}

Fields

Field	Description
id	The account ID. Use this as accountId when creating posts.
platform	One of the supported platforms (e.g. instagram, x).
username	The handle/username on the platform.
displayName	The display name, where available.

---

Get a connect URL

GET /api/v1/accounts/connect-url?platform=<platform>&client=web|mobile

Returns an OAuth authorization URL for connecting a new account. State and PKCE are handled server-side — you only need to send the user to the URL and wait for the account to appear in GET /v1/accounts.

Query parameters

Parameter	Type	Required	Description
platform	string	yes	Platform identifier (see Platforms)
client	string	no	web (default) or mobile (deep-link completion)

Response — 200 OK

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

Errors

Status	When
400	Platform doesn't use OAuth (e.g. Telegram, Bluesky) or isn't configured

---

Get an account

GET /api/v1/accounts/{id}

Returns the full profile for one account.

Response — 200 OK

{
  "data": {
    "id": "acc_abc123",
    "platform": "instagram",
    "platformId": "17841400000000000",
    "username": "postbuzz",
    "displayName": "post.buzz",
    "bio": "Schedule everything.",
    "avatarUrl": "https://...",
    "signature": null,
    "minPostGapMinutes": 0,
    "followersCount": 12000,
    "followersSyncedAt": "2026-07-01T00:10:00.000Z",
    "tier": null,
    "tokenExpiresAt": "2026-08-01T00:00:00.000Z",
    "disconnectedAt": null,
    "createdAt": "2026-01-15T09:00:00.000Z",
    "updatedAt": "2026-07-01T00:10:00.000Z"
  }
}

note

The response never includes platform access tokens — tokens stay server-side.

Errors

Status	Body
404	{ "error": { "code": "not_found", ... } }

---

Refresh an account

POST /api/v1/accounts/{id}/refresh

Performs a server-side OAuth token refresh for the account. Returns the updated profile (same shape as get). Useful when tokenExpiresAt is approaching.

---

Disconnect an account

DELETE /api/v1/accounts/{id}

Disconnects the account from post.buzz.

Response — 200 OK

{ "data": { "success": true } }

---

Account tools

GET  /api/v1/accounts/{id}/tools
POST /api/v1/accounts/{id}/tools/{tool}

Some platforms expose extra data that a connection flow needs before posting. GET lists the tools available for the account; POST runs one and returns its result inside data.

Tool	Platform	Result
reddit-flairs	Reddit	Available user flairs for the subreddit
pinterest-boards	Pinterest	The account's boards

Errors

Status	Body
400	{ "error": { "code": "unknown_tool", "details": { "available": [...] } } }

---

Account analytics

Account-level analysis (GET /v1/accounts/{id}/analytics) and forced insight refreshes (POST /v1/accounts/{id}/analytics/refresh) are documented on the Analytics page.

Related

• Posts API — use these account IDs to create posts.
• Analytics — account analytics + refresh.
• Platforms — capability and limit reference.