### Installation

Source: https://info.bundle.social/api-reference/sdk

Install the bundlesocial SDK using npm or pnpm.

```bash
npm install bundlesocial
# or
pnpm add bundlesocial
```

--------------------------------

### cURL Request Example

Source: https://info.bundle.social/api-reference/client/post/get-posts-that-can-be-reconnected-to-a-social-account

Example of how to make a GET request to the API endpoint to retrieve posts that can be reconnected to a social account.

```bash
curl --request GET \
  --url https://api.bundle.social/api/v1/post/reconnect-social-account/candidates \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Quick Setup

Source: https://info.bundle.social/api-reference/sdk

Initialize the BundleSocial client with your live API key.

```typescript
import { BundleSocial } from 'bundlesocial';

const bundle = new BundleSocial('pk_live_...';
```

--------------------------------

### Get health

Source: https://info.bundle.social/api-reference/client

Example of how to get the health status of the API using cURL.

```bash
curl --request GET \
  --url https://api.bundle.social/api/v1/ \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### CLI Examples

Source: https://info.bundle.social/api-reference/cli

Examples of using the Bundle Social CLI for various social media tasks.

```bash
# text post to X and Bluesky
bundle-social posts:create -c "We just shipped dark mode 🌙" -i x -i bluesky

# TikTok video with the required privacy level
bundle-social posts:create -c "BTS" -i tiktok -m ./demo.mp4 \
  --platform-settings '{"TIKTOK":{"privacy":"PUBLIC_TO_EVERYONE"}}'

# schedule a thread: post, then add replies as comments
POST=$(bundle-social posts:create -i linkedin -c "1/ A thread 🧵")
ID=$(printf '%s' "$POST" | jq -r .id)
bundle-social comments:create --post-id "$ID" -c "2/ more…" -c "3/ even more…"

# Reddit, done right: check requirements + flairs first
bundle-social integrations:trigger reddit:requirements --data '{"subreddit":"r/test"}'
bundle-social integrations:trigger reddit:flairs --data '{"subreddit":"r/test"}'
bundle-social posts:create --data '{"REDDIT":{"sr":"r/test","text":"Title","flairId":"<id>","uploadIds":[]}}'
```

--------------------------------

### cURL Request Example

Source: https://info.bundle.social/api-reference/client/socialaccount/get-paginated-social-accounts-scheduled-to-delete

Example of how to make a GET request to the API endpoint using cURL to retrieve social accounts scheduled for deletion.

```bash
curl --request GET \
  --url https://api.bundle.social/api/v1/social-account/to-delete \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Response Body Example

Source: https://info.bundle.social/api-reference/client/socialaccount/get-paginated-social-accounts-scheduled-to-delete

Example JSON response body for a successful GET request, showing the structure of social accounts scheduled for deletion and pagination details.

```json
{
  "items": [
    {
      "id": "<string>",
      "teamId": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "username": "<string>",
      "displayName": "<string>",
      "avatarUrl": "<string>",
      "externalId": "<string>",
      "userUsername": "<string>",
      "userDisplayName": "<string>",
      "userId": "<string>",
      "channels": [
        {
          "id": "<string>",
          "name": "<string>",
          "username": "<string>",
          "address": "<string>",
          "avatarUrl": "<string>",
          "webhook": {
            "id": "<string>",
            "name": "<string>",
            "avatar": "<string>",
            "url": "<string>"
          },
          "metadata": {
            "allowImages": true,
            "allowVideos": true,
            "allowGalleries": true,
            "linkFlairEnabled": true
          }
        }
      ],
      "mastodonServerId": "<string>",
      "isTiktokBusinessAccount": true,
      "disconnectedCheckTryAt": "2023-11-07T05:31:56Z",
      "deleteOn": "2023-11-07T05:31:56Z",
      "deletedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "page": 123,
    "pageSize": 123,
    "total": 123,
    "totalPages": 123
  }
}
```

--------------------------------

### Authorization Scheme Example

Source: https://info.bundle.social/api-reference/introduction

Illustrates the security scheme for API authentication.

```json
"security": [
  {
    "ApiKeyAuth": []
  }
]
```

--------------------------------

### Install and Run MCP Server

Source: https://info.bundle.social/api-reference/mcp

Install and run the MCP server locally using npm.

```bash
npx bundlesocial-mcp
```

--------------------------------

### Example Response

Source: https://info.bundle.social/api-reference/comments

An example response from the GET /api/v1/comment/import/comments endpoint, showing imported comments.

```json
{
  "items": [
    {
      "id": "fetched_1",
      "platform": "INSTAGRAM",
      "externalId": "18001234567890",
      "externalParentId": null,
      "text": "Top level comment",
      "authorName": "janedoe",
      "likesCount": 12,
      "repliesCount": 2,
      "publishedAt": "2026-04-13T09:30:00.000Z"
    },
    {
      "id": "fetched_2",
      "platform": "INSTAGRAM",
      "externalId": "18001234567999",
      "externalParentId": "18001234567890",
      "text": "Reply comment",
      "authorName": "bundle_user",
      "likesCount": 1,
      "repliesCount": 0,
      "publishedAt": "2026-04-13T09:35:00.000Z"
    }
  ],
  "total": 2
}
```

--------------------------------

### Response Body Example

Source: https://info.bundle.social/api-reference/client/post/get-posts-that-can-be-reconnected-to-a-social-account

Example of the JSON response body when successfully retrieving posts that can be reconnected to a social account.

```json
{
  "items": [
    {
      "id": "<string>",
      "title": "<string>",
      "postDate": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "total": 123
}
```

--------------------------------

### OpenAPI Specification Example

Source: https://info.bundle.social/api-reference/client/misc/create-google-business-place-action-link

This snippet shows a portion of the OpenAPI specification, detailing error responses and security schemes.

```yaml
openapi: 3.0.0
info:
  title: Google Business Profile API
  version: v1
paths:
  /locations/{locationId}/actions/createLink:
    post:
      summary: Creates a link to a Google Business Profile action.
      operationId: createLink
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLinkRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLinkResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    nullable: true
                  message:
                    type: string
                required:
                  - message
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    nullable: true
                  message:
                    type: string
                required:
                  - message
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    nullable: true
                  message:
                    type: string
                required:
                  - message
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    nullable: true
                  message:
                    type: string
                required:
                  - message
        '429':
          description: '429'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    nullable: true
                  message:
                    type: string
                required:
                  - message
        '500':
          description: '500'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    nullable: true
                  message:
                    type: string
                required:
                  - message
components:
  schemas:
    CreateLinkRequest:
      type: object
      properties:
        displayName:
          type: string
          description: The display name of the link.
        url:
          type: string
          description: The URL for the link.
    CreateLinkResponse:
      type: object
      properties:
        linkUri:
          type: string
          description: The URI of the created link.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header

```

--------------------------------

### Get trending tracks

Source: https://info.bundle.social/api-reference/platforms/tiktok-music

Example endpoint to retrieve a list of trending tracks on TikTok.

```HTTP
GET /api/v1/misc/tiktok/cml/trending-list?teamId=...&genre=POP&dateRange=7DAY
```

--------------------------------

### Install CLI

Source: https://info.bundle.social/api-reference/cli

Install the bundlesocial-cli globally or run it as a one-off.

```bash
npx bundlesocial-cli --help     # one-off
npm install -g bundlesocial-cli # global → `bundle-social`
```

--------------------------------

### Base URL

Source: https://info.bundle.social/api-reference/introduction

The base URL for all API requests.

```bash
https://api.bundle.social
```

--------------------------------

### Trending Tracks Response

Source: https://info.bundle.social/api-reference/platforms/tiktok-music

Example JSON response for the GET /api/v1/misc/tiktok/cml/trending-list endpoint, showing the structure of a trending track object.

```json
[
  {
    "commercial_music_name": "Lo-Fi analog beat",
    "duration": 183,
    "thumbnail_url": "https://...",
    "artist": "Gloveity",
    "preview_url": "https://...",
    "genres": ["HIP_HOP/RAP", "LO-FI"],
    "rank_position": "1",
    "trending_history": [
      { "date": "2026-02-15", "rank_position_daily": "1" }
    ],
    "full_duration_song_clip": {
      "preview_url": "https://...",
      "duration": 183,
      "song_clip_id": "6817312022837872642"
    },
    "trending_song_clip": {
      "preview_url": "https://...",
      "duration": 183,
      "song_clip_id": "6817312022837872642"
    }
  }
]
```

--------------------------------

### API Key Header

Source: https://info.bundle.social/api-reference/introduction

Example of how to include the API key in the request header.

```json
{
  "x-api-key": "pk_live_..."
}
```

--------------------------------

### Social Account Raw Analytics Endpoint

Source: https://info.bundle.social/api-reference/analytics

Example GET request for retrieving raw analytics data for a social account.

```http
GET /api/v1/analytics/social-account/raw?teamId=team_123&platformType=FACEBOOK
```

--------------------------------

### Example for Update link

Source: https://info.bundle.social/api-reference/platforms/google-business-place-action-links

This example demonstrates the payload for updating a place action link.

```json
{
  "teamId": "team_123",
  "name": "locations/12345678901234567890/placeActionLinks/abcdef",
  "fields": ["uri", "isPreferred"],
  "placeActionLink": {
    "uri": "https://example.com/new-order",
    "isPreferred": true
  }
}
```

--------------------------------

### Post Raw Analytics Endpoint (by Post ID)

Source: https://info.bundle.social/api-reference/analytics

Example GET request for retrieving raw analytics data for a specific post using its ID.

```http
GET /api/v1/analytics/post/raw?postId=post_123&platformType=FACEBOOK
```

--------------------------------

### Post Raw Analytics Endpoint (by Imported Post ID)

Source: https://info.bundle.social/api-reference/analytics

Example GET request for retrieving raw analytics data for a post using its imported ID.

```http
GET /api/v1/analytics/post/raw?importedPostId=profile_post_123
```

--------------------------------

### Code Generation Tools

Source: https://info.bundle.social/api-reference/openapi

Examples of commands to use with code generation tools based on the OpenAPI spec.

```bash
openapi-generator generate -i https://api.bundle.social/swagger-json -g typescript-fetch -o ./client
```

```bash
npx openapi-typescript https://api.bundle.social/swagger-json -o ./types.ts
```