API
Create AI-generated Facebook and Instagram posts from your own systems with the Trigger API — one HTTP call from "new blog post" to platform-tuned posts in your review queue.
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 → Connections → Meta integration, and the writing voice, image style and default watermark (the brand's logo) come from Brand → Brand settings → Social.
In the dashboard, Marketing → AI Social Posting → API opens with the plain-language part — Create posts from your other apps, How it works and Before you start (links to your API key, your connected pages, your logo and the Review queue) — and puts the technical reference below a For developers divider, with Post angles after it.
Authentication
Y-API-Key header in all requests. Create or rotate the key under Settings → Connections → MCP & API keys — 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 | Your only brand | Which brand the post belongs to, which decides the pages it goes to — the ordinary Yaplet brand from the sidebar's brand card. Leave it out if you have only one brand, or if only one of your brands has connected pages; with several brands you must send it. |
platforms | string[] | Every platform the brand has connected | "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 → Connections → 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 logo | A logo (watermark) from your library, placed on the generated image. Its id is what this field refers to. The brand default is set at Brand settings → Social; send null for no logo. |
length | string | The standard length | "short", "medium" or "long". 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 | A name for the post, shown only 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 It Works
Your app sends content
It sends a link or some text with your API key. The post is checked right away — a bad setup (no connected page, no linked Instagram) fails the call immediately instead of failing later.
Yaplet writes the post
Within about 2 minutes it reads the source, writes the captions, hashtags, alt text and first comments, and creates (or re-hosts) the image with your logo.
You approve it, or it goes out
In approval mode the finished draft appears in Marketing → AI Social Posting → Review queue and reviewers get an in-app notification. In auto mode it publishes as soon as it's ready, or at scheduled_at.
It's published
Each Facebook page and Instagram account gets its own post and succeeds or fails on its own — the optional first comment is posted right after each one goes live. If writing fails, nothing is published and the post shows why.
Post Angles
The optional angle field takes one of these ready-made approaches:
| Value | What the post does |
|---|---|
tip | Shares one practical tip from the source that people can use right away. |
faq | Answers one common customer question on the topic, plainly and helpfully. |
use_case | Tells a short, real story of solving a problem: the situation, what was done, the result. |
feature | Highlights one feature or offer and the clear benefit it brings. |
myth_bust | Clears up one common misconception and explains what's actually true. |
behind_the_scenes | Shows how something works or is made, in an honest, human way. |
audience_question | Starts a conversation with one easy question to your audience. |
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 organization's plan. |
400 | Validation problem — the message says which field. That includes sending both url and content (or neither), a page_ids entry that isn't one of the brand's pages, and leaving out brand_id when you have several brands. |
404 | The brand_id or watermark_id wasn't found (a brand that isn't yours, or a logo that isn't in your library). |
422 | The brand has no connected Facebook page, or you asked for Instagram but no page has an Instagram account linked — or you have no brand yet. |
429 | More than 20 posts are already waiting to be written, or too many requests in a short burst — try again shortly. |
500 | Something went wrong on our side while creating the post. |