openapi: 3.1.0
info:
  title: Meta Graph API - Pages
  description: |
    Graph API endpoints for reading and managing Facebook Pages -
    publishing posts and photos, retrieving Page insights, moderating
    comments, configuring Page metadata, and subscribing to webhook
    events. Authentication uses a Page access token obtained via OAuth
    2.0 with scopes such as pages_manage_posts, pages_read_engagement,
    pages_manage_metadata, pages_messaging, and pages_show_list.
  version: "v22.0"
  contact:
    name: Meta for Developers
    url: https://developers.facebook.com/docs/pages-api
servers:
  - url: https://graph.facebook.com/v22.0
    description: Meta Graph API
paths:
  /{page-id}:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: Get Page metadata
      operationId: getPage
      parameters:
        - $ref: '#/components/parameters/Fields'
      responses:
        "200":
          description: Page object
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Page' }
    post:
      summary: Update Page settings or metadata
      operationId: updatePage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                about: { type: string }
                description: { type: string }
                phone: { type: string }
                website: { type: string }
      responses:
        "200":
          description: Update confirmation
  /{page-id}/feed:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: List Page feed posts
      operationId: listPageFeed
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        "200":
          description: Feed collection
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GraphCollection' }
    post:
      summary: Publish a post to the Page feed
      operationId: publishPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message: { type: string }
                link: { type: string, format: uri }
                published: { type: boolean }
                scheduled_publish_time: { type: integer }
      responses:
        "200":
          description: Post created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
  /{page-id}/posts:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: List posts published by the Page
      operationId: listPagePosts
      parameters:
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Limit'
      responses:
        "200":
          description: Posts collection
  /{page-id}/photos:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: List Page photos
      operationId: listPagePhotos
      responses:
        "200":
          description: Photos collection
    post:
      summary: Upload a Page photo
      operationId: uploadPagePhoto
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                source: { type: string, format: binary }
                url: { type: string, format: uri }
                caption: { type: string }
                published: { type: boolean }
      responses:
        "200":
          description: Photo uploaded
  /{page-id}/insights:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: Get Page insights metrics
      operationId: getPageInsights
      parameters:
        - name: metric
          in: query
          required: true
          schema: { type: string }
          description: Comma-separated metric names, e.g. page_impressions,page_fans
        - name: period
          in: query
          schema:
            type: string
            enum: [day, week, days_28, month, lifetime]
        - name: since
          in: query
          schema: { type: string }
        - name: until
          in: query
          schema: { type: string }
      responses:
        "200":
          description: Insights values
  /{page-id}/conversations:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: List Page Messenger conversations
      operationId: listPageConversations
      parameters:
        - $ref: '#/components/parameters/Fields'
      responses:
        "200":
          description: Conversation collection
  /{page-id}/tagged:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: List posts the Page is tagged in
      operationId: listPageTagged
      responses:
        "200":
          description: Tagged posts
  /{page-id}/settings:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: Get Page settings
      operationId: getPageSettings
      responses:
        "200":
          description: Settings
    post:
      summary: Update a Page setting
      operationId: updatePageSetting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                setting: { type: string }
                value: { type: string }
      responses:
        "200":
          description: Setting updated
  /{object-id}/comments:
    parameters:
      - name: object-id
        in: path
        required: true
        schema: { type: string }
        description: Post, photo, or other commentable object ID.
    get:
      summary: List comments on an object
      operationId: listComments
      parameters:
        - $ref: '#/components/parameters/Fields'
      responses:
        "200":
          description: Comment collection
    post:
      summary: Post a comment on an object
      operationId: createComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message: { type: string }
                attachment_url: { type: string, format: uri }
      responses:
        "200":
          description: Comment created
  /{comment-id}:
    parameters:
      - name: comment-id
        in: path
        required: true
        schema: { type: string }
    delete:
      summary: Delete a comment
      operationId: deleteComment
      responses:
        "200":
          description: Deleted
  /{page-id}/subscribed_apps:
    parameters:
      - $ref: '#/components/parameters/PageId'
    get:
      summary: List apps subscribed to the Page
      operationId: listSubscribedApps
      responses:
        "200":
          description: Subscribed apps
    post:
      summary: Subscribe an app to Page webhook events
      operationId: subscribePageApp
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                subscribed_fields:
                  type: string
                  description: Comma-separated event fields, e.g. feed,messages,mention.
      responses:
        "200":
          description: Subscription created
  /me/accounts:
    get:
      summary: List Pages the user manages
      operationId: listMyPages
      parameters:
        - $ref: '#/components/parameters/Fields'
      responses:
        "200":
          description: Pages the authenticated user manages
components:
  parameters:
    PageId:
      name: page-id
      in: path
      required: true
      schema: { type: string }
      description: Facebook Page ID
    Fields:
      name: fields
      in: query
      schema: { type: string }
      description: Comma-separated list of fields to return.
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 25
      description: Number of items per page.
  schemas:
    Page:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        about: { type: string }
        category: { type: string }
        fan_count: { type: integer }
        link: { type: string, format: uri }
    GraphCollection:
      type: object
      properties:
        data:
          type: array
          items: { type: object }
        paging:
          type: object
          properties:
            cursors:
              type: object
              properties:
                before: { type: string }
                after: { type: string }
            next: { type: string }
            previous: { type: string }
  securitySchemes:
    PageAccessToken:
      type: oauth2
      description: |
        OAuth 2.0 Page access token. Granted scopes determine which
        endpoints can be called. Send as a Bearer token or as the
        access_token query parameter.
      flows:
        authorizationCode:
          authorizationUrl: https://www.facebook.com/v22.0/dialog/oauth
          tokenUrl: https://graph.facebook.com/v22.0/oauth/access_token
          scopes:
            pages_show_list: List Pages the user manages
            pages_manage_posts: Publish and edit posts
            pages_read_engagement: Read Page content and engagement
            pages_manage_metadata: Manage Page settings and subscribed apps
            pages_messaging: Send and receive Messenger messages
            pages_read_user_content: Read user-generated content on a Page
            pages_manage_engagement: Moderate comments and reactions
security:
  - PageAccessToken:
    - pages_show_list
    - pages_manage_posts
    - pages_read_engagement
    - pages_manage_metadata