Facebook Business Manager Posts API

openapi: 3.1.0
info:
  title: Facebook Business Manager Facebook Marketing Ad Accounts Posts API
  description: Create and manage ad campaigns, analyze performance, and automate advertising workflows across Meta platforms. The Marketing API provides programmatic access to Facebook's advertising system, enabling businesses to create campaigns, ad sets, and ads, manage budgets and bidding strategies, define targeting audiences, and retrieve performance metrics.
  version: '25.0'
  contact:
    name: Meta Developer Support
    url: https://developers.facebook.com/support
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com/v25.0
  description: Facebook Graph API Production Server
security:
- bearerAuth: []
tags:
- name: Posts
  description: Create, read, update, and delete posts on a Facebook Page feed.
paths:
  /{page_id}/feed:
    get:
      operationId: getPageFeed
      summary: Facebook Business Manager Get page feed
      description: Retrieves the feed of posts on a Facebook Page. Includes posts published by the page and posts by visitors if allowed.
      tags:
      - Posts
      parameters:
      - $ref: '#/components/parameters/pageId'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/after'
      responses:
        '200':
          description: Successfully retrieved page feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createPagePost
      summary: Facebook Business Manager Create a page post
      description: Publishes a new post to the Facebook Page feed. Supports text posts, link shares, and scheduled posts. Requires a page access token with pages_manage_posts permission.
      tags:
      - Posts
      parameters:
      - $ref: '#/components/parameters/pageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCreate'
      responses:
        '200':
          description: Post created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{post_id}:
    get:
      operationId: getPost
      summary: Facebook Business Manager Get a post
      description: Retrieves the details of a specific post including message, attachments, reactions, and engagement counts.
      tags:
      - Posts
      parameters:
      - $ref: '#/components/parameters/postId'
      - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successfully retrieved post details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updatePost
      summary: Facebook Business Manager Update a post
      description: Updates an existing post on the Page. Only the message field can be updated after publishing.
      tags:
      - Posts
      parameters:
      - $ref: '#/components/parameters/postId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: Updated post message text
      responses:
        '200':
          description: Post updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deletePost
      summary: Facebook Business Manager Delete a post
      description: Deletes a post from the Facebook Page. This action cannot be undone.
      tags:
      - Posts
      parameters:
      - $ref: '#/components/parameters/postId'
      responses:
        '200':
          description: Post deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters or malformed request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or expired access token or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    postId:
      name: post_id
      in: path
      required: true
      description: The ID of the post (format PAGE_ID_POST_ID)
      schema:
        type: string
    pageId:
      name: page_id
      in: path
      required: true
      description: The ID of the Facebook Page
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of objects to return per page
      schema:
        type: integer
        default: 25
        maximum: 100
    after:
      name: after
      in: query
      required: false
      description: Cursor for forward pagination
      schema:
        type: string
    fields:
      name: fields
      in: query
      required: false
      description: Comma-separated list of fields to include in the response
      schema:
        type: string
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message
            type:
              type: string
              description: Error type classification
            code:
              type: integer
              description: Numeric error code
            error_subcode:
              type: integer
              description: Numeric error subcode
            fbtrace_id:
              type: string
              description: Unique trace ID for debugging
    PostList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        paging:
          $ref: '#/components/schemas/Paging'
    Paging:
      type: object
      properties:
        cursors:
          type: object
          properties:
            before:
              type: string
            after:
              type: string
        next:
          type: string
        previous:
          type: string
    PostCreate:
      type: object
      properties:
        message:
          type: string
          description: The text content for the post
        link:
          type: string
          format: uri
          description: URL to share in the post
        published:
          type: boolean
          description: Whether to publish the post immediately
          default: true
        scheduled_publish_time:
          type: integer
          description: Unix timestamp for when to publish the post. Must be between 10 minutes and 6 months from now.
        targeting:
          type: object
          description: Targeting specification for the post audience
    CreateResponse:
      type: object
      properties:
        id:
          type: string
          description: The ID of the newly created object
    Post:
      type: object
      properties:
        id:
          type: string
          description: The ID of the post
        message:
          type: string
          description: The text content of the post
        story:
          type: string
          description: Auto-generated story text for the post
        created_time:
          type: string
          format: date-time
          description: When the post was created
        updated_time:
          type: string
          format: date-time
          description: When the post was last updated
        full_picture:
          type: string
          format: uri
          description: URL of the full-size post image
        permalink_url:
          type: string
          format: uri
          description: Permanent URL to the post
        type:
          type: string
          description: Type of post content
          enum:
          - link
          - status
          - photo
          - video
          - offer
        shares:
          type: object
          properties:
            count:
              type: integer
          description: Share count information
        likes:
          type: object
          properties:
            summary:
              type: object
              properties:
                total_count:
                  type: integer
        comments:
          type: object
          properties:
            summary:
              type: object
              properties:
                total_count:
                  type: integer
        attachments:
          type: object
          description: Media and link attachments on the post
        is_published:
          type: boolean
          description: Whether the post is published
        scheduled_publish_time:
          type: string
          description: Unix timestamp for scheduled posts
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token with ads_management or ads_read permissions. Obtain tokens via the Facebook Login flow.
externalDocs:
  description: Facebook Marketing API Documentation
  url: https://developers.facebook.com/docs/marketing-api