buffer-openapi-spec.yaml

swagger: '2.0'

info:
  title: Buffer OpenAPI Spec
  description: |
    OpenAPI Spec for Buffer, handcrafted by [Rodolfo Carvalho](http://rodolfocarvalho.net).

    **Note**: This is not an official spec. This is not endorsed by Buffer.
  version: 1.0.0
  license:
    name: MIT License
    url: https://github.com/rhcarvalho/buffer-openapi-spec/blob/master/LICENSE

externalDocs:
  description: Official Buffer API documentation
  url: https://buffer.com/developers/api

host: api.bufferapp.com
basePath: '/1'
schemes:
  - https

consumes:
  - application/x-www-form-urlencoded

produces:
  - application/json

tags:
  - name: auth
    description: Authentication with Buffer is the first step in building your app.
    externalDocs:
      url: https://buffer.com/developers/api/oauth
  - name: user
    description: A user represents a single Buffer user account.
    externalDocs:
      url: https://buffer.com/developers/api/user
  - name: profiles
    description: A Buffer profile represents a connection to a single social media account.
    externalDocs:
      url: https://buffer.com/developers/api/profiles

securityDefinitions:
  Bearer:
    # header must be set to "Authorization: Bearer ${AccessToken}"
    type: apiKey
    in: header
    name: Authorization

security:
  - Bearer: []

paths:
  /oauth2/token.json:
    post:
      summary: Getting an Access Token
      security: []
      parameters:
        - in: formData
          name: client_id
          required: true
          type: string
        - in: formData
          name: client_secret
          required: true
          type: string
        - in: formData
          name: redirect_uri
          required: true
          type: string
        - in: formData
          name: code
          required: true
          type: string
        - in: formData
          name: grant_type
          required: true
          type: string
          enum: [authorization_code]
      responses:
        200:
          description: >
            If your request is successful we will return a long-lived access
            token which can be used to access the users account details for
            all further api requests.
          schema:
            type: object
            properties:
              access_token:
                type: string
      tags:
        - auth

  /user.json:
    get:
      summary: Returns a single user.
      responses:
        200:
          description: Returns a single user.
          schema:
            $ref: '#/definitions/User'
      tags:
        - user

  /user/deauthorize.json:
    post:
      summary: Deauthorize your client for the user.
      responses:
        200:
          description: Deauthorize your client for the user.
          schema:
            type: object
            properties:
              success:
                type: boolean
              message:
                type: string
            example:
              success: true
              message: Access successfully revoked!
      tags:
        - user

  /profiles.json:
    get:
      summary: Returns an array of social media profiles connected to a users account.
      responses:
        200:
          description: Returns an array of social media profiles connected to a users account.
          schema:
            type: array
            items:
              $ref: '#/definitions/Profile'
      tags:
        - profiles

  /profiles/{id}.json:
    get:
      summary: Returns details of the single specified social media profile.
      parameters:
        - in: path
          name: id
          required: true
          type: string
      responses:
        200:
          description: Returns details of the single specified social media profile.
          schema:
            $ref: '#/definitions/Profile'
      tags:
        - profiles

  /profiles/{id}/schedules.json:
    get:
      summary: Returns details of the posting schedules associated with a social media profile.
      parameters:
        - in: path
          name: id
          required: true
          type: string
      responses:
        200:
          description: Returns details of the posting schedules associated with a social media profile.
          schema:
            type: array
            items:
              $ref: '#/definitions/Schedule'
      tags:
        - profiles

  /profiles/{id}/schedules/update.json:
    post:
      summary: Set the posting schedules for the specified social media profile.
      parameters:
        - in: path
          name: id
          required: true
          type: string
      responses:
        200:
          description: Set the posting schedules for the specified social media profile.
      tags:
        - profiles

definitions:
  User:
    type: object
    properties:
      # '_id' is the same as 'id'; ommited because it is unnecessary and because
      # it causes swagger-codegen to generate broken clients.
      #_id:
      #  type: string
      id:
        type: string
      activity_at:
        type: integer
        format: int32
      created_at:
        type: integer
        format: int32
      plan:
        type: string
      timezone:
        type: string
    example:
      _id: '4f0c0a06512f7ef214000000'
      activity_at: 1343654640
      created_at: 1326189062
      id: '4f0c0a06512f7ef214000000'
      plan: free
      timezone: Asia/Tel_Aviv
  Profile:
    type: object
    properties:
      avatar:
        type: string
      created_at:
        type: integer
        format: int32
      default:
        type: boolean
      formatted_username:
        type: string
      id:
        type: string
      schedules:
        type: array
        items:
          $ref: '#/definitions/Schedule'
      service:
        type: string
      service_id:
        type: string
      service_username:
        type: string
      statistics:
        type: object
        properties:
          followers:
            type: integer
            format: int32
      team_members:
        type: array
        items:
          type: string
      timezone:
        type: string
      user_id:
        type: string
    example:
      avatar: 'http://a3.twimg.com/profile_images/1405180232.png'
      created_at: 1320703028
      default: true
      formatted_username: '@skinnyoteam'
      id: '4eb854340acb04e870000010'
      schedules:
        - days:
            - mon
            - tue
            - wed
            - thu
            - fri
          times:
            - '12:00'
            - '17:00'
            - '18:00'
      service: twitter
      service_id: '164724445'
      service_username: skinnyoteam
      statistics:
        followers: 246
      team_members:
        - '4eb867340acb04e670000001'
      timezone: Europe/London
      user_id: '4eb854340acb04e870000010'
  Schedule:
    type: object
    properties:
      days:
        type: 'array'
        items:
          type: 'string'
          enum:
          - 'mon'
          - 'tue'
          - 'wed'
          - 'thu'
          - 'fri'
          - 'sat'
          - 'sun'
      times:
        type: 'array'
        items:
          type: 'string'
    required:
      - days
      - times
    example:
      days:
        - mon
        - tue
        - wed
        - thu
        - fri
      times:
        - '12:00'
        - '17:00'
        - '18:00'