# Blotato

Source: https://opvs.ai/docs/tools/blotato

> Developer reference for @opvs-ai/blotato v2.1.1: listAccounts, listSubaccounts, listPinterestBoards, createPost, and getPostStatus across ten social platforms.

> **Tip:** Watch the Blotato launch film on [opvs.ai/skills/blotato](https://opvs.ai/skills/blotato) or view the [embedded video player](https://videos.spideriq.ai/videos/embed/cf85b398-67ff-4ac7-aa54-07dc935f1ab4?title=0&warningTitle=0&peertubeLink=0&p2p=0).

**Current package:** `@opvs-ai/blotato` `v2.1.1` (`beta`, `public`, 5 methods) · **Upstream:** `https://backend.blotato.com` · **Auth:** `blotato-api-key` header (resolved per brand via `Settings → Integrations`, provider `blotato`, or `BLOTATO_API_KEY`).

`@opvs-ai/blotato` replaces `@opvs-ai/vibe-publish` (`2.1.0+`) with a unified social publishing skill across ten platforms: `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, `youtube`, and `slack`. It adds three read-only lookup and verification methods (`listSubaccounts`, `listPinterestBoards`, `getPostStatus`), optional `platform` filtering on `listAccounts`, and full platform target declarations on `createPost`.

## Methods

### `listAccounts({ platform? })`

`GET /v2/users/me/accounts`

List all connected social media accounts for the authenticated Blotato user. Filter by `platform` when you already know the target network (`twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, `youtube`, `slack`).

**Parameters**

Parameter

Type

Required

Description

`platform`

`string`

No

Filter connected accounts by platform name.

**Example**

```bash
opvs -w opvs tools call @opvs-ai/blotato listAccounts \
  --input '{"platform":"linkedin"}'
```

**Response**

```json
{
  "items": [
    {
      "id": "acc_12345",
      "platform": "linkedin",
      "fullname": "OPVS AI"
    }
  ]
}
```

**Errors**

Error

Trigger

Resolution

`401 Unauthorized`

Missing or invalid `blotato-api-key` in brand integrations

Save a valid Blotato API key in **Settings → Integrations** (provider `blotato`).

`400 Bad Request`

Unsupported `platform` string passed

Use one of the 10 supported platform identifiers (`twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, `youtube`, `slack`).

`200 []` (empty list)

No social accounts connected in Blotato for that platform

Connect the social account inside the Blotato dashboard before calling `createPost`.

---

### `listSubaccounts({ accountId })`

`GET /v2/users/me/accounts/{accountId}/subaccounts`

List the Facebook Pages, LinkedIn company Pages, YouTube playlists, and Slack channels connected under an account. Pass the returned item `id` as `target.pageId` (Facebook, LinkedIn Page), `target.playlistIds` entry (YouTube), or `target.channelId` (Slack). Omitting `pageId` on LinkedIn posts to the personal profile.

**Parameters**

Parameter

Type

Required

Description

`accountId`

`string`

Yes

Account ID returned by `listAccounts`.

**Example**

```bash
opvs -w opvs tools call @opvs-ai/blotato listSubaccounts \
  --input '{"accountId":"acc_12345"}'
```

**Response**

```json
{
  "items": [
    {
      "id": "page_98765",
      "name": "OPVS Company Page"
    }
  ]
}
```

**Errors**

Error

Trigger

Resolution

`401 Unauthorized`

Missing or invalid `blotato-api-key`

Verify the Blotato key in **Settings → Integrations**.

`404 Not Found`

`accountId` does not exist on this Blotato account

Re-run `listAccounts` and pass a valid `id`.

`200 []` (empty list)

No Pages, playlists, or channels connected under the account

Connect the Page or channel inside Blotato; empty is not proof that none exist.

---

### `listPinterestBoards({ accountId })`

`GET /v2/social/pinterest/boards`

List the boards owned by a connected Pinterest account. Pass the returned `id` as `target.boardId` when creating a pin with `createPost`.

**Parameters**

Parameter

Type

Required

Description

`accountId`

`string`

Yes

Pinterest account ID returned by `listAccounts`.

**Example**

```bash
opvs -w opvs tools call @opvs-ai/blotato listPinterestBoards \
  --input '{"accountId":"acc_pin_01"}'
```

**Response**

```json
{
  "items": [
    {
      "id": "board_4567",
      "name": "Product Launches"
    }
  ]
}
```

**Errors**

Error

Trigger

Resolution

`401 Unauthorized`

Missing or invalid `blotato-api-key`

Verify the Blotato key in **Settings → Integrations**.

`400 Bad Request`

`accountId` is not a Pinterest account

Call `listAccounts` with `platform: "pinterest"` and pass that `id`.

---

### `createPost({ post, scheduledTime?, useNextFreeSlot? })`

`POST /v2/posts`

Create and optionally schedule a social media post. `post.content` is an object (`text`, `mediaUrls`, `platform`, and optional `additionalPosts` for threads on `twitter`, `bluesky`, and `threads`). `post.target` is a per-platform object (`targetType` plus platform-specific fields such as `pageId`, `boardId`, `channelId`, `mediaType`, `title`, `privacyStatus`, `trial: { graduationStrategy }`, TikTok disclosure flags, and YouTube `isMadeForKids` / `containsSyntheticMedia`).

**Parameters**

Parameter

Type

Required

Description

`post`

`object`

Yes

`{ accountId, content: { text, mediaUrls[], platform, additionalPosts? }, target: { targetType, ... } }`.

`scheduledTime`

`string`

No

ISO 8601 timestamp for scheduled publishing (e.g. `2026-11-15T14:00:00Z`).

`useNextFreeSlot`

`boolean`

No

Schedule into the account's next open Blotato queue slot.

**Example**

```bash
opvs -w opvs tools call @opvs-ai/blotato createPost \
  --input '{
    "post": {
      "accountId": "acc_12345",
      "content": {
        "text": "Give your agent the publishing job.",
        "mediaUrls": [],
        "platform": "linkedin"
      },
      "target": {
        "targetType": "linkedin",
        "pageId": "page_98765"
      }
    },
    "scheduledTime": "2026-11-15T14:00:00Z"
  }'
```

**Response**

```json
{
  "postSubmissionId": "sub_abc123"
}
```

**Errors**

Error

Trigger

Resolution

`400 Bad Request`

Missing required `target` fields (e.g. YouTube `title` + `privacyStatus`, Pinterest `boardId`, Facebook `pageId`)

Include all required platform fields in `post.target` or look up IDs via `listSubaccounts` / `listPinterestBoards`.

`400 Bad Request`

Invalid `scheduledTime` format or past timestamp

Pass a future ISO 8601 timestamp in `scheduledTime` or use `useNextFreeSlot: true`.

`401 Unauthorized`

Missing or invalid `blotato-api-key`

Verify the Blotato key in **Settings → Integrations**.

---

### `getPostStatus({ postSubmissionId })`

`GET /v2/posts/{postSubmissionId}`

Read the outcome of a `createPost` submission: `in-progress`, `scheduled` (with `scheduledTime`), `published` (with `publicUrl` when supplied), or `failed` (with `errorMessage`). Always pass the `postSubmissionId` returned by `createPost`, never a published post ID. Note that `in-progress` is also returned for an unknown ID; poll at intervals of at least 10 seconds with a retry limit.

**Parameters**

Parameter

Type

Required

Description

`postSubmissionId`

`string`

Yes

The `postSubmissionId` returned by `createPost`.

**Example**

```bash
opvs -w opvs tools call @opvs-ai/blotato getPostStatus \
  --input '{"postSubmissionId":"sub_abc123"}'
```

**Response**

```json
{
  "postSubmissionId": "sub_abc123",
  "status": "published",
  "publicUrl": "https://www.linkedin.com/feed/update/urn:li:share:12345"
}
```

**Errors**

Error

Trigger

Resolution

`401 Unauthorized`

Missing or invalid `blotato-api-key`

Verify the Blotato key in **Settings → Integrations**.

`404 Not Found`

Submission record expired or invalid endpoint path

Confirm `postSubmissionId` came directly from `createPost`.

`status: "failed"`

Upstream platform rejected the post (returned in `errorMessage`)

Fix the missing field, media format, or account permission reported in `errorMessage` and resubmit with `createPost`.