Facebook Posting API
The Facebook Posting API publishes text, images, videos, and links to connected Facebook Pages through a single endpoint.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "facebook",
"accountId": "fb_123"
}
],
"publishNow": true
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
Use it when you need Facebook Page Posts without building the underlying Graph API workflow yourself, and choose the format and timing fields before you send the request.
Publish to Facebook Pages with text, images, videos, and links through one endpoint
The Facebook Posting API publishes text, images, videos, and links to connected Facebook Pages through a single endpoint. Use it when you need Facebook Page Posts without building the underlying Graph API workflow yourself, and choose the format and timing fields before you send the request.
Destinations are limited to Facebook Pages. Personal profiles cannot be targeted through this API route, since Meta withdrew that option, so a preflight check should reject any workflow that expects a personal profile target. Managed OAuth covers the Facebook authorization flow, the exchange that produces long-lived tokens, and the token arrangement Meta uses for each individual Page, keeping that handling out of your publishing code.
Connect once, then publish, schedule, and read data through the same API. First, get your API key through sign-up with no sales setup. Second, integrate in minutes by connecting once to publish, schedule, analyze, manage comments, and handle messages. Third, support every major platform so users can reach other networks without building and maintaining each integration separately.
Each format uses that one endpoint, with only the fields relevant to the chosen format changing. The exact contract sheet and the Text Post request and 202 response are shown in the code examples titled Text Post Request and Text Post Response. Keep the method, path, field names, and values unchanged when you implement against that sheet.
For Facebook Page Posts, a text post goes to a connected Page, and the integration accountId identifies which Page receives it. Treat a missing accountId as a preflight failure rather than sending the request. Image and Video Posts attach a single image or video to your post, with the media publishing workflow handled for you. Link Sharing works through platformSpecificData.link; Facebook then reads the destination page's Open Graph metadata and builds a link preview.
Scheduled Publishing sends Facebook posts at a future date and time through that same publishing endpoint. Include scheduledFor and, when needed, an IANA timezone, and leave publishNow out or set it to false. Immediate publishing sets publishNow to true, as shown in the Text Post Request example. Do not set both timing modes in a way that makes the intended behavior ambiguous; your validator should require exactly one clear mode before calling the endpoint.
Cross-Post sends identical content to Facebook, Instagram, Twitter/X, and other supported networks in a single request. That suits one campaign across several destinations, but a failure check should inspect each platform entry in the response instead of assuming every destination succeeded because the top-level request was accepted.
Choose the format with a short checklist. Choose a text post when the message needs no media. Choose a single image when one visual carries the post. Choose photo carousels when the story needs multiple images, keeping the count between 2 and 10. Choose a video post when motion is the point, keeping it to one video per post. Choose a link preview when the URL and its Open Graph metadata should do the visual work. Choose Cross-Post only when the same content is genuinely intended for more than one network.
Run a preflight validator before calling the endpoint. Check that accountId is present for the Facebook target. Check that images and videos are not mixed in the same post. Check that a carousel contains 2 to 10 images and that a single-image post contains one image. Check that a video post contains one video within the documented limit of up to 240 minutes and 4 GB, with MP4 or MOV recommended. Check that immediate publishing uses publishNow true, while scheduled publishing uses scheduledFor with publishNow omitted or false and an optional IANA timezone. If any check fails, stop and fix the payload locally instead of sending a request you expect to fail.
Verify publication from the response, not from the fact that the request was sent. The captured response includes success, status, postId, and a platforms entry with success and platformPostUrl. Treat status published together with the per-platform success value and a present platformPostUrl as the confirmation signal, and store postId and platformPostUrl with your own record so a user can open the published post. Post webhooks can also update your application when publishing succeeds or fails.
Beyond publishing, the same connected Facebook Pages can support scheduling, analytics, and comments as separate capabilities. Facebook scheduling queues posts for later and manages upcoming scheduled content. Facebook analytics retrieves performance data for dashboards, reports, and automated workflows. Facebook comments lets users follow discussion around their content and answer it from inside your product. Messaging and comment-to-DM are additional capabilities in the wider set, alongside scheduling, analytics, and comments APIs.
The same publishing workflow can be used from a developer stack with typed SDKs and predictable REST APIs, from no-code tools such as Zapier, Make, and n8n, or from AI agents and MCP through a hosted MCP server, agent skills, and an OpenAI tool-calling schema. The stack changes the caller, not the contract: the endpoint, accountId selection, format fields, timing fields, and response verification stay the same.
Other supported platforms can be reached through the same API after starting with Facebook, including Twitter / X, Instagram, YouTube, TikTok, Threads, Pinterest, LinkedIn, Bluesky, and Google Business. Keep those destinations as cross-references for Cross-Post planning rather than expanding this page into a generic multi-platform guide.
Field map, format choices, and failure checks
The field map below is the implementation reference for the captured contract. It separates fields shown in the exact Text Post example from fields stated elsewhere on the source page, so you do not invent types or requiredness for formats whose full schemas were not supplied. The limits and failure matrix below collects the source-stated constraints you should enforce in a preflight validator before you call the endpoint.
| Field | Location | Contract detail | Preflight check |
|---|---|---|---|
| content | Request body | String value in the captured example: "New product drop today." | Require non-empty content for a text post. |
| platforms[].platform | Request body | Value "facebook" in the captured example. | Require the Facebook platform entry before sending. |
| platforms[].accountId | Request body | Value "fb_123" in the captured example; selects the connected Facebook Page. | Require accountId for the Facebook target; reject a missing value locally. |
| publishNow | Request body | Value true in the captured immediate-publishing example. | Use true for immediate publishing; omit or set false for scheduled publishing. |
| scheduledFor | Request body | Source-stated scheduling field used with the same /v1/posts endpoint. | Require for scheduled publishing; pair with an optional IANA timezone. |
| platformSpecificData.link | Request body | Source-stated field for link sharing; Facebook fetches Open Graph metadata for the preview. | Require a valid URL when using link preview format. |
| success | Response body | Value true in the captured 202 response. | Check the top-level success value after the call. |
| status | Response body | Value "published" in the captured response. | Treat published as the confirmation status. |
| postId | Response body | Value "post_fb123" in the captured response. | Store postId with your own record. |
| platforms[].success | Response body | Value true for the Facebook entry in the captured response. | Check each platform entry separately for Cross-Post. |
| platforms[].platformPostUrl | Response body | Facebook post URL in the captured response. | Require and store platformPostUrl as verification evidence. |
Fields and values preserved from the captured Text Post example and source-stated scheduling/link fields; full schemas for other formats were not supplied and are not invented here. Preflight checks are local validator guidance, not source requiredness.
| Format or decision | Use when | Source-stated limit or rule | Failure check |
|---|---|---|---|
| Text post | The message needs no media. | Publishable to connected Facebook Pages. | Reject if accountId is missing. |
| Single image post | One visual carries the post. | A standard single-image post uses one image. | Reject if more than one image is supplied for a single-image post. |
| Photo carousels | Multiple images tell the story. | 2–10 images. | Reject counts below 2 or above 10. |
| Video post | Motion is the point of the post. | One video per post; up to 240 minutes and 4 GB; MP4 or MOV recommended. | Reject multiple videos, oversized files, or mixed images and videos. |
| Link preview post | A URL should render with its Open Graph preview. | Use platformSpecificData.link. | Reject if the link is missing or invalid. |
| Immediate publishing | The post should go out now. | publishNow true in the captured example. | Reject ambiguous timing when scheduled fields are also set. |
| Scheduled publishing | The post should go out at a future time. | scheduledFor with optional IANA timezone; omit publishNow or set it to false. | Reject scheduled requests missing scheduledFor. |
| Cross-Post | The same content is intended for several networks. | Facebook, Instagram, Twitter/X, and other supported networks in one request. | Inspect every platform entry in the response. |
| Personal profile target | A user asks to post to a personal profile. | API posting to personal Facebook profiles is not supported because Meta deprecated that capability. | Reject profile targets and direct the user to a connected Page. |
Limits are the source-stated FAQ limits; no additional platform limits are invented.
Frequently asked questions
Can I publish to Facebook Pages and personal profiles?
Only Facebook Pages are supported as destinations. Personal profiles cannot be targeted through this API route, since Meta withdrew that option.
What can I publish to Facebook through the Facebook Posting API?
Supported formats include plain text, one image, photo carousels, video, and posts that render a link preview, all directed at a connected Page.
How many images can I add to a Facebook post?
A carousel may contain anywhere from two through ten images. When you want a single-image post, supply exactly one image.
What are the Facebook video limits?
Each post accepts a single video. Stated maximums reach 240 minutes and 4 GB, and MP4 or MOV is the recommended format. A post must not combine image media with video media.
Can I schedule Facebook posts?
Yes. Send the request to /v1/posts, include scheduledFor, and add an IANA timezone if needed. Leave publishNow out, or set it to false.
How do I know whether my Facebook post actually published?
Inspect the returned status together with platformPostUrl for the Facebook entry. Webhooks are also available to notify your application when a publish attempt finishes successfully or fails.
What can I build with the Facebook Posting API?
Typical uses include social media management tools, SaaS products, automated workflows, and AI-powered applications that need Page publishing built in.
202
{
"success": true,
"status": "published",
"postId": "post_fb123",
"platforms": [
{
"platform": "facebook",
"success": true,
"platformPostUrl": "https://www.facebook.com/104251038/posts/998877665"
}
]
}