openapi: 3.1.0
info:
  title: Patreon API v2
  description: |
    Patreon's APIv2 exposes identity, campaign, member, post, livestream and
    webhook resources for creator integrations. Authentication uses OAuth2
    Bearer tokens issued via the Patreon OAuth flow.
  version: "2.0.0"
  contact:
    name: Patreon Developers
    url: https://docs.patreon.com/
servers:
  - url: https://www.patreon.com
    description: Patreon production
security:
  - BearerAuth: []
paths:
  /oauth2/authorize:
    get:
      summary: OAuth2 authorization request
      parameters:
        - in: query
          name: response_type
          required: true
          schema:
            type: string
            example: code
        - in: query
          name: client_id
          required: true
          schema:
            type: string
        - in: query
          name: redirect_uri
          required: true
          schema:
            type: string
        - in: query
          name: scope
          schema:
            type: string
        - in: query
          name: state
          schema:
            type: string
      responses:
        '302':
          description: Redirect to the configured redirect URI with an authorization code.
      security: []
  /api/oauth2/token:
    post:
      summary: Exchange a code or refresh token for an access token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: authorization_code
                code:
                  type: string
                refresh_token:
                  type: string
                client_id:
                  type: string
                client_secret:
                  type: string
                redirect_uri:
                  type: string
      responses:
        '200':
          description: Access token issued.
      security: []
  /api/oauth2/v2/identity:
    get:
      summary: Fetch the current user's profile
      responses:
        '200':
          description: Current user identity.
  /api/oauth2/v2/campaigns:
    get:
      summary: List campaigns owned by the authorized user
      responses:
        '200':
          description: A list of campaigns.
  /api/oauth2/v2/campaigns/{campaign_id}:
    get:
      summary: Get a single campaign
      parameters:
        - in: path
          name: campaign_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Campaign details.
  /api/oauth2/v2/campaigns/{campaign_id}/members:
    get:
      summary: List members of a campaign
      parameters:
        - in: path
          name: campaign_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of members.
  /api/oauth2/v2/members/{member_id}:
    get:
      summary: Get an individual member
      parameters:
        - in: path
          name: member_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Member details.
  /api/oauth2/v2/campaigns/{campaign_id}/posts:
    get:
      summary: List posts on a campaign
      parameters:
        - in: path
          name: campaign_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A paginated list of posts.
  /api/oauth2/v2/posts/{id}:
    get:
      summary: Get an individual post
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Post details.
  /api/oauth2/v2/lives:
    post:
      summary: Create a livestream event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Livestream created.
  /api/oauth2/v2/lives/{id}:
    get:
      summary: Get livestream details
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Livestream details.
    patch:
      summary: Update livestream state
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Livestream updated.
  /api/oauth2/v2/webhooks:
    get:
      summary: List webhooks for a campaign
      responses:
        '200':
          description: A list of webhooks.
    post:
      summary: Create a webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Webhook created.
  /api/oauth2/v2/webhooks/{id}:
    patch:
      summary: Update a webhook
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Webhook updated.
    delete:
      summary: Delete a webhook
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook deleted.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2 access token
      description: |
        Pass `Authorization: Bearer {access_token}`. Tokens are issued via
        the Patreon OAuth flow (`/oauth2/authorize` and `/api/oauth2/token`).