API | Yaplet

Overview

The Trigger API turns any URL or raw text into ready-to-publish social posts. AI Social Posting reads the source, writes platform-tuned captions, generates the image, and either parks the post in your review queue (default) or publishes it automatically. Typical use: call it from your CMS whenever you publish a blog post.

Everything the call takes from a brand is configured outside AI Social Posting. Which Facebook and Instagram accounts a post can reach comes from the pages assigned to that brand on Settings → Organization settings → Meta integration, and the writing voice, image style and default watermark come from Brand → Brand settings → Social.

Authentication

API Key RequiredInclude the Y-API-Key header in all requests. Create or rotate the key under Settings → Organization settings → API — the same key works for every Yaplet API.

Endpoint

POST `https://yaplet.com/api/social-posting/trigger`

Accepts a JSON body and returns 202 Accepted — generation runs asynchronously and typically completes within ~2 minutes.

Request Fields

Required (one of)

Field	Type	Description
`url`	`string`	Page to post about. Read server-side.
`content`	`string`	Raw text to post about (max 40,000 characters).

Optional

Field	Type	Default	Description
`brand_id`	`string`	The org's only brand	Which brand the post belongs to — the ordinary Yaplet brand from the sidebar's Brand section, not a social-posting-only object. Required only when your organization has several brands.
`platforms`	`string[]`	Both	`"FACEBOOK"`, `"INSTAGRAM"`.
`page_ids`	`string[]`	All the brand's pages	Post to a subset of the brand's pages — the Facebook and Instagram accounts assigned to it on Settings → Organization settings → Meta integration.
`mode`	`string`	`"approval"`	`"approval"` parks the post in the review queue; `"auto"` publishes as soon as it's generated.
`scheduled_at`	`ISO date`	—	Auto mode only: publish at this time instead of immediately (max 1 year ahead).
`generate_image`	`boolean`	`true`	Must stay `true` when INSTAGRAM is targeted, unless you supply `image_url`. Mutually exclusive with `image_url`.
`image_url`	`string`	—	Bring your own image (public https URL) — downloaded, normalized and re-hosted like an upload.
`first_comment`	`boolean`	`false`	The AI writes a per-platform first comment posted right after each post goes live. Soft: a failed comment never blocks the post.
`include_source_link`	`boolean`	`true`	With `first_comment: true` on a URL-sourced post, the Facebook comment carries the source link (the one clickable place). Instagram stays link-free.
`watermark_id`	`string`	The brand's default watermark	A watermark from your library, composited onto the generated image. The brand default is set at Brand settings → Social; send `null` for no watermark.
`length`	`string`	The standard length	`"short"`, `"medium"` or `"long"`. There is no per-brand default any more — omit it and the post is written at the standard length.
`angle`	`string`	—	A ready-made take: `tip`, `faq`, `use_case`, `feature`, `myth_bust`, `behind_the_scenes` or `audience_question`.
`instructions`	`string`	—	Per-post steer for the AI (max 4,000 characters).
`name`	`string`	Generated	Internal name shown in your post list.

Code Examples

const response = await fetch("https://yaplet.com/api/social-posting/trigger", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Y-API-Key": "YOUR_API_KEY",
    },
    body: JSON.stringify({
        url: "https://your-blog.com/new-feature",
        platforms: ["FACEBOOK", "INSTAGRAM"],
        mode: "approval",
        first_comment: true,
        instructions: "Friendly tone, no emojis.",
    }),
});

const result = await response.json();
console.log(result); // { id, status: "PENDING_GENERATION", mode, targets }

curl -X POST https://yaplet.com/api/social-posting/trigger \
  -H "Content-Type: application/json" \
  -H "Y-API-Key: YOUR_API_KEY" \
  -d '{
  "url": "https://your-blog.com/new-feature",
  "platforms": ["FACEBOOK", "INSTAGRAM"],
  "mode": "approval",
  "first_comment": true,
  "instructions": "Friendly tone, no emojis."
}'

<?php

$ch = curl_init("https://yaplet.com/api/social-posting/trigger");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Y-API-Key: YOUR_API_KEY",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "url" => "https://your-blog.com/new-feature",
    "platforms" => ["FACEBOOK", "INSTAGRAM"],
    "mode" => "approval",
    "first_comment" => true,
    "instructions" => "Friendly tone, no emojis.",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response; // { "id": ..., "status": "PENDING_GENERATION", ... }
?>

import requests

response = requests.post(
    "https://yaplet.com/api/social-posting/trigger",
    headers={
        "Content-Type": "application/json",
        "Y-API-Key": "YOUR_API_KEY",
    },
    json={
        "url": "https://your-blog.com/new-feature",
        "platforms": ["FACEBOOK", "INSTAGRAM"],
        "mode": "approval",
        "first_comment": True,
        "instructions": "Friendly tone, no emojis.",
    },
)

print(response.json())  # { "id": ..., "status": "PENDING_GENERATION", ... }

Response

Status: 202 Accepted

{
    "id": "9f4c1e6a-...",
    "status": "PENDING_GENERATION",
    "mode": "approval",
    "targets": 2
}

How a Triggered Post Becomes Live

You call the trigger

The post is validated synchronously — a bad setup (no connected page, no linked Instagram) fails the call immediately instead of failing later.

The generation worker picks it up

Within ~2 minutes it reads the source, writes the captions, hashtags, alt text and first comments, and generates or re-hosts the image.

Approval or auto

In approval mode the finished draft appears in Marketing → AI Social Posting → Review queue (reviewers get an in-app notification). In auto mode it publishes as soon as it's ready, or at scheduled_at.

Each platform publishes independently

Facebook and Instagram targets succeed or fail per page — with the optional first comment posted right after each one goes live.

Errors

Status	Meaning
`401`	Missing or invalid `Y-API-Key`.
`403`	`AI Social Posting is not available on your plan` — the module is not part of your organisation's plan.
`400`	Validation problem — the message says which field.
`404`	A referenced resource (brand, page, watermark) wasn't found.
`422`	No connected Facebook page (or no linked Instagram account) to post to.
`429`	Too many posts already waiting for generation (max 20), or too many requests in a short burst — retry after they finish.

Billing

Billed like the composerCaption generation and images bill softly — prepaid wallet first, then your plan's credit meter. A failed generation never publishes anything and is never charged; the post shows as Failed in your list with the reason.