openapi: 3.1.0
info:
  title: Facebook Business Manager Facebook Pages API
  description: >-
    Manage Facebook Pages, publish and manage posts, moderate comments, and
    track engagement through the Graph API. The Pages API allows businesses
    to programmatically manage their Facebook presence, publish content,
    respond to comments and messages, and retrieve page-level analytics.
  version: '25.0'
  contact:
    name: Meta Developer Support
    url: https://developers.facebook.com/support
  termsOfService: https://developers.facebook.com/terms
externalDocs:
  description: Facebook Pages API Documentation
  url: https://developers.facebook.com/docs/pages-api
servers:
  - url: https://graph.facebook.com/v25.0
    description: Facebook Graph API Production Server
tags:
  - name: Comments
    description: >-
      Manage comments on Page posts including reading, replying, and
      moderating.
  - name: Page Insights
    description: >-
      Retrieve analytics and engagement metrics for a Facebook Page.
  - name: Pages
    description: >-
      Retrieve and manage Facebook Page settings, information, and
      metadata.
  - name: Photos
    description: >-
      Upload and manage photos on a Facebook Page.
  - name: Posts
    description: >-
      Create, read, update, and delete posts on a Facebook Page feed.
  - name: Videos
    description: >-
      Upload and manage videos on a Facebook Page.
security:
  - bearerAuth: []
paths:
  /{page_id}:
    get:
      operationId: getPage
      summary: Facebook Business Manager Get page details
      description: >-
        Retrieves information about a Facebook Page including name,
        category, description, fan count, and other metadata.
      tags:
        - Pages
      parameters:
        - $ref: '#/components/parameters/pageId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Successfully retrieved page details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /{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'
  /{post_id}/comments:
    get:
      operationId: getPostComments
      summary: Facebook Business Manager Get post comments
      description: >-
        Retrieves comments on a specific post. Supports pagination and
        filtering by order.
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/postId'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/after'
        - name: filter
          in: query
          description: Filter for comment type
          required: false
          schema:
            type: string
            enum:
              - stream
              - toplevel
        - name: order
          in: query
          description: Order of comments
          required: false
          schema:
            type: string
            enum:
              - chronological
              - reverse_chronological
      responses:
        '200':
          description: Successfully retrieved comments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createComment
      summary: Facebook Business Manager Create a comment
      description: >-
        Posts a comment on a Page post as the Page. Requires a page
        access token with pages_manage_engagement permission.
      tags:
        - Comments
      parameters:
        - $ref: '#/components/parameters/postId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  description: The comment text
                attachment_url:
                  type: string
                  format: uri
                  description: URL of an image to include with the comment
      responses:
        '200':
          description: Comment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{comment_id}:
    delete:
      operationId: deleteComment
      summary: Facebook Business Manager Delete a comment
      description: >-
        Deletes a comment from a Page post. The Page must own the
        comment or the post the comment is on.
      tags:
        - Comments
      parameters:
        - name: comment_id
          in: path
          required: true
          description: The ID of the comment to delete
          schema:
            type: string
      responses:
        '200':
          description: Comment deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /{page_id}/photos:
    post:
      operationId: uploadPagePhoto
      summary: Facebook Business Manager Upload a page photo
      description: >-
        Uploads a photo to the Facebook Page. Can be published directly
        or uploaded as unpublished for later use in posts.
      tags:
        - Photos
      parameters:
        - $ref: '#/components/parameters/pageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: URL of the photo to upload
                caption:
                  type: string
                  description: Caption for the photo
                published:
                  type: boolean
                  description: Whether to publish the photo immediately
                  default: true
      responses:
        '200':
          description: Photo uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{page_id}/videos:
    post:
      operationId: uploadPageVideo
      summary: Facebook Business Manager Upload a page video
      description: >-
        Uploads a video to the Facebook Page. Supports direct upload
        via URL or resumable upload for large files.
      tags:
        - Videos
      parameters:
        - $ref: '#/components/parameters/pageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                file_url:
                  type: string
                  format: uri
                  description: URL of the video file to upload
                title:
                  type: string
                  description: Title of the video
                description:
                  type: string
                  description: Description of the video
                published:
                  type: boolean
                  description: Whether to publish the video immediately
                  default: true
      responses:
        '200':
          description: Video uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{page_id}/insights:
    get:
      operationId: getPageInsights
      summary: Facebook Business Manager Get page insights
      description: >-
        Retrieves analytics metrics for the Facebook Page including
        reach, impressions, engagement, and audience demographics.
      tags:
        - Page Insights
      parameters:
        - $ref: '#/components/parameters/pageId'
        - name: metric
          in: query
          description: >-
            Comma-separated list of metrics to retrieve such as
            page_impressions, page_engaged_users, page_fans.
          required: true
          schema:
            type: string
        - name: period
          in: query
          description: Aggregation period for the metrics
          required: false
          schema:
            type: string
            enum:
              - day
              - week
              - days_28
              - month
              - lifetime
              - total_over_range
        - name: since
          in: query
          description: Start of the date range in Unix timestamp or YYYY-MM-DD format
          required: false
          schema:
            type: string
        - name: until
          in: query
          description: End of the date range in Unix timestamp or YYYY-MM-DD format
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved page insights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageInsightsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{page_id}/subscribed_apps:
    post:
      operationId: subscribePageApp
      summary: Facebook Business Manager Subscribe app to page
      description: >-
        Installs a Webhooks-configured app on the Page so the app can
        receive real-time updates about changes to the Page.
      tags:
        - Pages
      parameters:
        - $ref: '#/components/parameters/pageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subscribed_fields
              properties:
                subscribed_fields:
                  type: array
                  items:
                    type: string
                  description: >-
                    List of Page fields to subscribe to, such as feed,
                    messages, messaging_postbacks.
      responses:
        '200':
          description: App subscribed to page successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Page access token with appropriate permissions such as
        pages_manage_posts, pages_read_engagement, pages_manage_metadata.
  parameters:
    pageId:
      name: page_id
      in: path
      required: true
      description: The ID of the Facebook Page
      schema:
        type: string
    postId:
      name: post_id
      in: path
      required: true
      description: The ID of the post (format PAGE_ID_POST_ID)
      schema:
        type: string
    fields:
      name: fields
      in: query
      required: false
      description: Comma-separated list of fields to include in the response
      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
  responses:
    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'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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
    Paging:
      type: object
      properties:
        cursors:
          type: object
          properties:
            before:
              type: string
            after:
              type: string
        next:
          type: string
        previous:
          type: string
    CreateResponse:
      type: object
      properties:
        id:
          type: string
          description: The ID of the newly created object
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
    Page:
      type: object
      properties:
        id:
          type: string
          description: The ID of the Page
        name:
          type: string
          description: The name of the Page
        category:
          type: string
          description: The primary category of the Page
        category_list:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
          description: List of categories associated with the Page
        about:
          type: string
          description: Short description of the Page
        description:
          type: string
          description: Detailed description of the Page
        fan_count:
          type: integer
          description: Total number of Page likes
        followers_count:
          type: integer
          description: Total number of Page followers
        link:
          type: string
          format: uri
          description: The URL of the Page on Facebook
        website:
          type: string
          format: uri
          description: The website listed on the Page
        phone:
          type: string
          description: Phone number listed on the Page
        emails:
          type: array
          items:
            type: string
          description: Email addresses listed on the Page
        location:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            country:
              type: string
            zip:
              type: string
            latitude:
              type: number
            longitude:
              type: number
        cover:
          type: object
          properties:
            id:
              type: string
            source:
              type: string
              format: uri
          description: The Page cover photo
        picture:
          type: object
          properties:
            data:
              type: object
              properties:
                url:
                  type: string
                  format: uri
          description: The Page profile picture
        verification_status:
          type: string
          description: Verification status of the Page
        is_published:
          type: boolean
          description: Whether the Page is published and visible
    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
    PostList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        paging:
          $ref: '#/components/schemas/Paging'
    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
    Comment:
      type: object
      properties:
        id:
          type: string
          description: The ID of the comment
        message:
          type: string
          description: The text content of the comment
        from:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
          description: The person or Page that made the comment
        created_time:
          type: string
          format: date-time
          description: When the comment was created
        like_count:
          type: integer
          description: Number of likes on the comment
        comment_count:
          type: integer
          description: Number of replies to the comment
        is_hidden:
          type: boolean
          description: Whether the comment is hidden
        attachment:
          type: object
          description: Media attachment on the comment
    CommentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
        paging:
          $ref: '#/components/schemas/Paging'
    PageInsightsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The metric name
              period:
                type: string
                description: The aggregation period
              values:
                type: array
                items:
                  type: object
                  properties:
                    value:
                      description: The metric value (integer or object)
                    end_time:
                      type: string
                      format: date-time
              title:
                type: string
                description: Human-readable metric title
              description:
                type: string
                description: Description of what the metric measures
              id:
                type: string
                description: Metric identifier
        paging:
          $ref: '#/components/schemas/Paging'