aidelly_create_post

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "idempotency_key",
    "platform",
    "content"
  ],
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "description": "Workspace to operate in. Do not ask the user for this UUID — call aidelly_list_workspaces and use the `id` of the matching workspace. Optional for read operations; required when creating content."
    },
    "brand_id": {
      "type": "string"
    },
    "idempotency_key": {
      "type": "string"
    },
    "instagram_destination": {
      "type": "string",
      "enum": [
        "post",
        "stories",
        "post_stories"
      ],
      "description": "Instagram-only destination. Use post for feed only, stories for Stories only, or post_stories for both feed and Stories."
    },
    "facebook_destination": {
      "type": "string",
      "enum": [
        "post",
        "stories",
        "post_stories"
      ],
      "description": "Facebook-only destination. Use post for feed only, stories for a Page Story only, or post_stories for both. Behind the FACEBOOK_STORIES_ENABLED feature flag - requests that set it while the flag is off are rejected with a validation error."
    },
    "platform": {
      "type": "string",
      "enum": [
        "facebook",
        "instagram",
        "linkedin",
        "twitter",
        "bluesky",
        "threads",
        "pinterest",
        "youtube",
        "tiktok",
        "google_business",
        "mastodon"
      ],
      "description": "Supported platform identifier. `twitter` and `x` map to the same surface;\nresponses always normalize to `twitter`. `google_business` posts target\na single Google Business Profile location identified by\n`platform_specific.locationName`. `mastodon` accounts are per-instance —\nthe connected account carries its own `instance_url`.\n",
      "example": "linkedin"
    },
    "account_id": {
      "type": "string",
      "example": "social-account-id",
      "description": "The account / sub-account this post should target. Format depends on platform:\n  - **facebook** — Page ID (numeric string from `/accounts`).\n  - **instagram** — Instagram Business Account ID.\n  - **linkedin** — connection ID for personal posts; LinkedIn organization URN for company posts.\n  - **google_business** — GBP location resource name. Either fully-qualified\n    `accounts/{accountId}/locations/{locationId}` or the relative\n    `locations/{locationId}` form. Fetch with `GET /accounts` (rows where\n    `account_type: location`).\n  - **twitter / bluesky / threads / tiktok / youtube / pinterest / mastodon** — single-account\n    platforms; `account_id` is optional and ignored.\n\nWhen omitted, posts use the workspace-level default for that platform.\n"
    },
    "scheduled_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-02-18T17:30:00Z"
    },
    "timezone": {
      "type": "string",
      "example": "UTC"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "example": {
        "campaign": "spring-launch",
        "source": "agent"
      }
    },
    "content": {
      "type": "object",
      "required": [
        "text"
      ],
      "additionalProperties": false,
      "properties": {
        "text": {
          "type": "string",
          "minLength": 1,
          "example": "Launching our new feature today."
        },
        "media": {
          "type": "array",
          "maxItems": 10,
          "description": "Media attachments. Supplying multiple items automatically creates a carousel/slideshow on platforms that support it (Instagram, Facebook, TikTok).\nUse `read_url` returned by `POST /media/upload-url` for each `media[].url`.\nTruncated or corrupt images are rejected at upload and publish preflight with a clear validation error.\nWhen `type` is omitted it is resolved from the media-library row (`application/pdf` → `document`), so an uploaded PDF is no longer stored as an image.\n- **Instagram**: 2–10 images → carousel; 1 video → reel (or `platform_specific.contentType: \"reel\"`)\n- **TikTok**: all images → photo carousel; 1 video → video post or draft\n- **Facebook**: 2+ images → carousel; 1 video → video post\n- **LinkedIn**: one `type: \"document\"` PDF (≤100 MB, ≤300 pages) → swipeable document post. Documents are LinkedIn-only and cannot be mixed with images or videos; other platforms return `422 PUBLIC_API_DOCUMENT_UNSUPPORTED_PLATFORM`. The size and format checks run at create time; the page-count check runs at publish.\n",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "description": "Publishable media URL. Use `read_url` returned by `POST /media/upload-url`."
              },
              "read_url": {
                "type": "string",
                "format": "uri",
                "description": "MCP-friendly alias for `url`."
              },
              "media_id": {
                "type": "string",
                "description": "Media id returned by `POST /media/upload-url`. Accepted when `url`/`read_url` is not available."
              },
              "type": {
                "type": "string",
                "description": "Attachment kind. Optional — resolved from the media-library row when omitted. `document` is LinkedIn-only.",
                "enum": [
                  "image",
                  "video",
                  "gif",
                  "document"
                ]
              }
            },
            "anyOf": [
              {
                "required": [
                  "url"
                ]
              },
              {
                "required": [
                  "read_url"
                ]
              },
              {
                "required": [
                  "media_id"
                ]
              }
            ]
          }
        },
        "media_urls": {
          "type": "array",
          "maxItems": 10,
          "description": "Agent-friendly alias for image URLs. Prefer `content.media[].url` for new calls.",
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "image_url": {
          "type": "string",
          "format": "uri",
          "description": "Single image URL alias. Prefer `content.media[].url` for new calls."
        },
        "link": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        },
        "hashtags": {
          "type": "array",
          "maxItems": 30,
          "items": {
            "type": "string"
          }
        },
        "mentions": {
          "type": "array",
          "maxItems": 30,
          "items": {
            "type": "string"
          }
        },
        "instagram_destination": {
          "type": "string",
          "enum": [
            "post",
            "stories",
            "post_stories"
          ],
          "description": "Instagram destination for posts. Use \"stories\" for Story-only or \"post_stories\" for feed + Story."
        },
        "facebook_destination": {
          "type": "string",
          "enum": [
            "post",
            "stories",
            "post_stories"
          ],
          "description": "Facebook destination for posts. Use \"stories\" for a Page Story only or \"post_stories\" for feed + Story. Behind the FACEBOOK_STORIES_ENABLED feature flag."
        },
        "platform_specific": {
          "type": "object",
          "additionalProperties": true,
          "properties": {
            "board_id": {
              "type": "string",
              "description": "Pinterest board id returned by aidelly_list_pinterest_boards."
            },
            "boardId": {
              "type": "string",
              "description": "Camel-case alias for Pinterest board_id."
            }
          },
          "description": "Platform-specific options. Supported fields per platform:\n\n**Instagram**\n- `contentType` (`string`): `\"post\"` | `\"reel\"` | `\"story\"`. Defaults to `\"reel\"` for a single video, `\"carousel\"` for multiple images, `\"post\"` otherwise.\n- `instagramDestination` / `instagram_destination` (`string`): `\"post\"` | `\"stories\"` | `\"post_stories\"`. Use `stories` for Story-only or `post_stories` for feed + Story.\n- `reelOptions.shareToFeed` (`boolean`): Share reel to feed. Default `true`.\n- `reelOptions.trialReel.enabled` (`boolean`): Publish as a trial reel to non-followers first. When enabled, `shareToFeed` is forced to `false`.\n- `reelOptions.trialReel.graduationStrategy` (`string`): Required for trial reels. `\"MANUAL\"` graduates in Instagram; `\"SS_PERFORMANCE\"` graduates automatically based on performance.\n\n**TikTok**\n- `postMode` (`string`): `\"direct\"` (publish immediately) | `\"draft\"` (save to inbox for review). Default `\"direct\"`.\n- `postAsDraft` (`boolean`): Shorthand for `postMode: \"draft\"`.\n- `title` (`string`): Optional title shown in the TikTok inbox when posting as draft.\n- Aliases accepted for agents and normalized to camelCase: `post_mode`, `post_as_draft`, `publish_immediately`.\n- `photos` (`array`): For photo carousels — array of `{ url, order, caption? }` objects (max 35). When all media items are images, TikTok automatically creates a photo carousel.\n- `allowComments` (`boolean`), `allowDuet` (`boolean`), `allowStitch` (`boolean`): Interaction controls.\n\n**Facebook**\n- `fbPostType` (`string`): `\"photo\"` | `\"carousel\"`. Post type. `\"carousel\"` enables multi-card experience with child attachments. Defaults to `\"photo\"`.\n- `fbCarouselLink` (`string`): Destination link for all cards in a carousel. Required when `fbPostType=\"carousel\"`.\n- `fbCarouselCards` (`array`): Optional per-card copy for carousel posts. Array of objects with `name` and `description` strings (max 5 items), index-aligned with media attachments. Example: `[{ name: \"Card 1\", description: \"First card\" }, { name: \"Card 2\", description: \"Second card\" }]`.\n- `enableFirstComment` (`boolean`): Post an auto-comment after publishing.\n- `firstCommentText` (`string`): Text for the auto-comment.\n- `facebookDestination` / `facebook_destination` (`string`): `\"post\"` | `\"stories\"` | `\"post_stories\"`. Publishes a Page Story via `/photo_stories` or `/video_stories`. Story media must be 9:16; videos 3-60s (MP4/MOV); photos JPEG/PNG/BMP/GIF/TIFF under 10MB. Behind the `FACEBOOK_STORIES_ENABLED` feature flag.\n\n**Facebook Carousel Behavior (backward compatible)**\nSet `fbPostType=\"carousel\"` to opt in to carousel format. When `fbPostType` is absent or set to `\"photo\"`, the default behavior is used (single photo or video post). Absent or `\"photo\"` = backward compatible behavior.\n\n**Pinterest**\n- `board_id` / `boardId` (`string`): Board id returned by `GET /accounts/pinterest/boards`. When omitted, Aidelly resolves a board in this order: (1) value in the request payload, (2) board saved on the connected Pinterest account (`platform_specific`), (3) workspace posting default, (4) user-level posting default. Publishing fails preflight if no board can be resolved.\n\n**LinkedIn**\n- `contentType` (`string`): `\"post\"` | `\"image\"` | `\"video\"` — auto-detected from media if not specified.\n\n**Threads**\n- `replyControl` (`string`): `\"everyone\"` | `\"accounts_you_follow\"` | `\"mentioned_only\"`. Maps to the Threads API `reply_control` field. Defaults to the connection's saved Threads posting default, then `\"everyone\"`.\n- `topicTag` (`string`): A single topic tag (Threads accepts at most one per post). Maps to `topic_tag`.\n- `allowlistedCountryCodes` (`string[]`): ISO-3166 alpha-2 country codes that are allowed to see the post. Maps to `allowlisted_country_codes`. Empty array publishes globally.\n- `linkAttachmentUrl` (`string`): URL to attach as the canonical link preview. Maps to `link_attachment`.\n\n**Google Business** (`google_business`)\n- `locationName` (`string`, required): Full GBP location resource name, e.g. `accounts/{accountId}/locations/{locationId}`. Use the `id` from `/accounts` for a `google_business` row. Falls back to the connection's saved default location when omitted.\n- `topicType` (`string`): `\"STANDARD\"` | `\"EVENT\"` | `\"OFFER\"` | `\"ALERT\"`. Defaults to `\"STANDARD\"`.\n- `languageCode` (`string`): BCP-47 language tag (e.g. `\"en-US\"`). Defaults to `\"en-US\"`.\n- `callToActionType` (`string`): `\"BOOK\"` | `\"ORDER\"` | `\"SHOP\"` | `\"LEARN_MORE\"` | `\"SIGN_UP\"` | `\"CALL\"`. Adds a CTA button to STANDARD posts only.\n- `callToActionUrl` (`string`): Required for every CTA except `CALL`, which uses the phone number on the Business Profile.\n- `event` (`object`, required when `topicType` is `\"EVENT\"`): `{ title, schedule }` where `schedule` accepts ISO `start`/`end` strings or Google date/time objects (`startDate`, `startTime`, `endDate`, `endTime`).\n- `offer` (`object`, required when `topicType` is `\"OFFER\"`): `{ schedule, couponCode?, redeemOnlineUrl?, termsConditions? }`.\n- `alertType` (`string`, required when `topicType` is `\"ALERT\"`): Currently `\"COVID_19\"`.\n",
          "example": {
            "postMode": "draft"
          }
        },
        "platformSpecific": {
          "type": "object",
          "additionalProperties": true,
          "description": "Alias for `platform_specific` (agent compatibility)."
        },
        "first_comment": {
          "type": "object",
          "required": [
            "text"
          ],
          "additionalProperties": false,
          "description": "Auto-posts a comment on the published post. Honored on platforms\nwhose `capabilities.firstComment` is true (Facebook, Instagram,\nLinkedIn, YouTube, X, Bluesky, Threads).\n",
          "properties": {
            "text": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2200,
              "description": "Global comment text. Default for every capable platform."
            },
            "overrides": {
              "type": "object",
              "additionalProperties": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2200
              },
              "description": "Per-platform override (`{ instagram: \"...\", facebook: \"...\" }`).\nFalls back to `text` when missing or empty.\n"
            },
            "delay_minutes": {
              "type": "integer",
              "enum": [
                0,
                5,
                30,
                60,
                360,
                1440
              ],
              "description": "Minutes to wait after the main publish before posting the\ncomment. Fully honored on scheduled posts (Inngest sleep);\nbest-effort on immediate publishes.\n"
            }
          }
        },
        "thread": {
          "type": "object",
          "required": [
            "parts"
          ],
          "additionalProperties": false,
          "description": "Native thread composition. Honored on platforms whose\n`capabilities.thread` is true (X, Bluesky, Threads). Each part\npublishes as a reply chained off the previous one. `parts[0]`\nis the root post and shares text with `content.text`.\n",
          "properties": {
            "parts": {
              "type": "array",
              "minItems": 2,
              "maxItems": 25,
              "items": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1
                  },
                  "media": {
                    "type": "array",
                    "maxItems": 4,
                    "items": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "image",
                            "video",
                            "gif",
                            "document"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "overrides": {
              "type": "object",
              "additionalProperties": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "text": {
                      "type": "string"
                    }
                  }
                }
              },
              "description": "Per-platform override (`{ twitter: [...], bluesky: [...] }`).\nFalls back to `parts` when missing.\n"
            }
          }
        },
        "draft_kind": {
          "type": "string",
          "enum": [
            "post",
            "thread"
          ],
          "description": "Indicates whether the composer authored a single post or a\nthread. Optional — when omitted, threads are inferred from\n`thread.parts.length > 1`.\n"
        }
      }
    },
    "query": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional query overrides for endpoints with sparse parameter schemas."
    },
    "body": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional body override for endpoints with sparse parameter schemas."
    }
  }
}