Skip to main content

​
Authentication

We use API Key authentication. Simple, secure, boring.
Don’t have an API Key?
Sign up here and grab one from the API Keys section in your dashboard.

​
The Header

To make a request, add the x-api-key header with your key. 
{
  "x-api-key": "pk_live_..."
}

​
Authorization Scheme

All endpoints are protected. If you don’t send the key, you get a 401 Unauthorized. If you send a bad key, you get a 403 Forbidden. 
"security": [
  { 
    "ApiKeyAuth": [] 
  }
]

​
Base URL

https://api.bundle.social
Everything is prefixed with /api/v1, but check the specific endpoint reference to be sure.

​
Organizations vs Teams

This is important. Almost every API call involves a teamId, so you need to understand the hierarchy: 
Organization (your account)
  ├── Team A (e.g. "Marketing")
  │   ├── Social Accounts (Instagram, TikTok, ...)
  │   ├── Posts
  │   └── Uploads
  ├── Team B (e.g. "Client: Acme Corp")
  │   ├── Social Accounts
  │   ├── Posts
  │   └── Uploads
  ├── API Keys (shared across all teams)
  ├── Webhooks (shared across all teams)
  └── Subscription & Billing

​
What lives where

LevelWhat belongs here
OrganizationAPI keys, webhooks, subscription/billing, compression settings
TeamSocial accounts, posts, uploads, bots, invitations, bio/link-in-bio

​
Why this matters for you

  • teamId is required on most endpoints (creating posts, uploading media, connecting accounts). Think of a team as a “workspace” or “project” - it groups related social accounts together.
  • API keys are org-level. One key gives you access to all teams in the organization.
  • Webhooks are org-level. You get events for all teams from a single webhook endpoint.
  • Rate limits are per team. Each team has its own daily posting quota. Five teams means five independent limits. See Rate Limits.
  • Monthly post caps are org-level. The total monthly posts across all teams are capped by your subscription tier.
If you’re building a SaaS where each of your customers needs their own social accounts, create a team per customer. They won’t step on each other’s toes.

​
Rate Limits

We have sensible rate limits to protect the system. If you hit them, you’ll get a 429 Too Many Requests. Check the Rate Limits page for the full breakdown - including burst protection, per-minute caps, and daily posting limits per platform.