> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postqueen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Discover connected accounts, settings schemas, and dynamic tools

Every post has to name the channel it goes to. These commands give you the channel IDs, the settings schema each network enforces, and the helper tools it offers.

## Listing Integrations

List all connected social media accounts to get their IDs:

```bash theme={"system"}
postqueen integrations:list
```

<Check>
  A JSON array of your channels comes back. The `id` and `identifier` fields are what the rest of
  these commands take.
</Check>

Use `jq` to extract specific fields:

<CodeGroup>
  ```bash Just the IDs and platforms theme={"system"}
  postqueen integrations:list | tail -n +2 | jq '.[] | {id, identifier}'
  ```

  ```bash Find a specific platform theme={"system"}
  postqueen integrations:list | tail -n +2 | jq '.[] | select(.identifier=="reddit")'
  ```
</CodeGroup>

### Filtering by Group

If your channels are organized into groups (customers), filter the list to a single group with `--group`:

```bash theme={"system"}
postqueen integrations:list --group "customer-id"
```

## Listing Groups

List all groups (customers) for your organization to get their IDs:

```bash theme={"system"}
postqueen integrations:groups
```

This returns a JSON array of `{id, name}` objects. Use a group's `id` with `integrations:list --group` to filter channels:

```bash theme={"system"}
# Find a group by name, then list its integrations
GROUP_ID=$(postqueen integrations:groups | tail -n +2 | jq -r '.[] | select(.name=="My Company") | .id')
postqueen integrations:list --group "$GROUP_ID"
```

## Getting Settings

Each platform has its own settings schema with character limits, required fields, and available options. Retrieve it with:

```bash theme={"system"}
postqueen integrations:settings <integration-id>
```

<Tip>
  Run this before posting to a network for the first time. It is faster than reading a provider page,
  and it answers the question that actually blocks you: which fields will be refused if you leave
  them out.
</Tip>

Four things come back, wrapped in an `output` object:

| Field       | What it is                                                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rules`     | The network's own constraints in plain language                                                                                                                                                         |
| `maxLength` | Character limit for the post content. For channels where a verified account gets more room, this is already the number that applies to yours                                                            |
| `settings`  | The schema for `--settings`: which fields exist, which are required, and what each accepts. Channels with nothing to configure return the string `No additional settings required` instead of an object |
| `tools`     | Helper tools this channel offers. Pass `methodName` to `integrations:trigger`. An empty array means this network has none                                                                               |

<Accordion title="Example response for a Pinterest channel" icon="code">
  ```json theme={"system"}
  {
    "output": {
      "rules": "Pinterest requires at least one media, if posting a video, you must have two attachment, one for video, one for the cover picture, When posting a video, there can be only one, if posting images, there can be maximum 5",
      "maxLength": 500,
      "settings": {
        "type": "object",
        "properties": {
          "board": { "type": "string", "description": "board must be an id" },
          "title": { "type": "string", "maxLength": 100 },
          "link": { "type": "string", "format": "url" },
          "dominant_color": { "type": "string" }
        },
        "required": ["board"]
      },
      "tools": [
        { "methodName": "boards", "description": "List of boards", "dataSchema": [] }
      ]
    }
  }
  ```

  <Note>
    `settings` is a JSON Schema document, generated from that provider's own validation rules, so
    required fields are listed in a `required` array rather than flagged on each property. The block
    above is abridged; a real response carries every constraint the network enforces.
  </Note>
</Accordion>

## Triggering Tools

Some platforms offer dynamic tools, for example fetching Reddit flairs, Pinterest boards, or Discord channels. These return data you need when constructing platform-specific settings.

```bash theme={"system"}
postqueen integrations:trigger <integration-id> <method-name>
```

Pass additional data with `-d`:

```bash theme={"system"}
postqueen integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'
```

### Examples

<AccordionGroup>
  <Accordion title="Reddit: flairs and restrictions for a subreddit" icon="reddit">
    ```bash theme={"system"}
    postqueen integrations:trigger reddit-id restrictions -d '{"subreddit":"/r/programming"}'
    ```
  </Accordion>

  <Accordion title="Reddit: search subreddits by keyword" icon="magnifying-glass">
    ```bash theme={"system"}
    postqueen integrations:trigger reddit-id subreddits -d '{"word":"programming"}'
    ```
  </Accordion>

  <Accordion title="Discord: list channels" icon="discord">
    ```bash theme={"system"}
    postqueen integrations:trigger discord-id channels
    ```
  </Accordion>

  <Accordion title="Whop: list companies" icon="building">
    ```bash theme={"system"}
    postqueen integrations:trigger whop-id companies
    ```
  </Accordion>

  <Accordion title="Pinterest: list boards" icon="pinterest">
    ```bash theme={"system"}
    postqueen integrations:trigger pinterest-id boards
    ```
  </Accordion>

  <Accordion title="Instagram: search audio for a Reel" icon="instagram">
    ```bash theme={"system"}
    postqueen integrations:trigger instagram-id audioSearch -d '{"q":"summer vibes","type":"music"}'
    ```

    <Warning>
      Facebook Business-linked channels only. An empty `q` returns trending audio.
    </Warning>
  </Accordion>
</AccordionGroup>

<Info>
  [Provider Tools](/public-api/integrations/provider-tools) lists every tool each network offers,
  and what it gives back, without needing a connected channel to ask.
</Info>

## Discovery Workflow

When working with a new platform, follow this workflow:

<Steps>
  <Step title="Find the integration ID" icon="magnifying-glass">
    ```bash theme={"system"}
    INTEGRATION_ID=$(postqueen integrations:list | tail -n +2 | jq -r '.[] | select(.identifier=="reddit") | .id')
    ```
  </Step>

  <Step title="Check what settings and tools are available" icon="sliders">
    ```bash theme={"system"}
    postqueen integrations:settings "$INTEGRATION_ID"
    ```
  </Step>

  <Step title="Use tools to fetch dynamic data" icon="wrench">
    Flairs, boards, channels: whatever that network needs you to name.

    ```bash theme={"system"}
    postqueen integrations:trigger "$INTEGRATION_ID" restrictions -d '{"subreddit":"/r/programming"}'
    ```
  </Step>

  <Step title="Create a post with the discovered settings" icon="paper-plane">
    ```bash theme={"system"}
    postqueen posts:create \
      -c "My post" \
      -s "2026-08-01T09:00:00Z" \
      --settings '{"subreddit":[{"value":{"subreddit":"/r/programming","title":"Post Title","type":"text","is_flair_required":false}}]}' \
      -i "$INTEGRATION_ID"
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Provider tools" icon="wrench" href="/public-api/integrations/provider-tools">
    Every helper tool each network exposes, what it takes and what it gives back.
  </Card>

  <Card title="Ready-made commands" icon="grid-2" href="/cli/platform-examples">
    A worked example per network, settings included.
  </Card>

  <Card title="Schedule the post" icon="calendar" href="/cli/managing-posts">
    Threads, drafts, campaigns and the JSON file format.
  </Card>

  <Card title="The settings endpoint" icon="code" href="/public-api/integrations/settings">
    The same schema over HTTP, without the CLI.
  </Card>
</CardGroup>