openapi: 3.0.3
info:
  title: Forem API V1 agent_sessions followers API
  version: 1.0.0
  description: "Access Forem articles, users and other resources via API.\n        For a real-world example of Forem in action, check out [DEV](https://www.dev.to).\n        All endpoints can be accessed with the 'api-key' header and a accept header, but\n        some of them are accessible publicly without authentication.\n\n        Dates and date times, unless otherwise specified, must be in\n        the [RFC 3339](https://tools.ietf.org/html/rfc3339) format."
servers:
- url: https://dev.to/api
  description: Production server
security:
- api-key: []
tags:
- name: followers
paths:
  /api/followers/users:
    get:
      summary: Followers
      tags:
      - followers
      description: "This endpoint allows the client to retrieve a list of the followers they have.\n        \"Followers\" are users that are following other users on the website.\n        It supports pagination, each page will contain 80 followers by default."
      operationId: getFollowers
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      - name: sort
        in: query
        required: false
        description: "Default is 'created_at'. Specifies the sort order for the created_at param of the follow\n                                relationship. To sort by newest followers first (descending order) specify\n                                ?sort=-created_at."
        schema:
          type: string
        example: created_at
      responses:
        '200':
          description: A List of followers
          content:
            application/json:
              example:
              - type_of: user_follower
                id: 91
                created_at: '2026-05-28T18:45:24Z'
                user_id: 4186
                name: Duane "Douglass" \:/ Muller
                path: /username138
                username: username138
                profile_image: /uploads/user/profile_image/4186/c74aadc6-5b29-4f73-b23b-6908a8e9f105.jpeg
              - type_of: user_follower
                id: 90
                created_at: '2026-05-28T18:45:24Z'
                user_id: 4184
                name: Nicki "Alysa" \:/ Heathcote
                path: /username136
                username: username136
                profile_image: /uploads/user/profile_image/4184/5d771299-1520-4435-8380-e9a7697c7c8c.jpeg
              schema:
                type: array
                items:
                  description: A follower
                  type: object
                  properties:
                    type_of:
                      description: user_follower by default
                      type: string
                    id:
                      type: integer
                      format: int32
                    user_id:
                      description: The follower's user id
                      type: integer
                      format: int32
                    name:
                      description: The follower's name
                      type: string
                    path:
                      description: A path to the follower's profile
                      type: string
                    profile_image:
                      description: Profile image (640x640)
                      type: string
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /followers/users:
    get:
      summary: Followers
      tags:
      - followers
      description: "This endpoint allows the client to retrieve a list of the followers they have.\n        \"Followers\" are users that are following other users on the website.\n        It supports pagination, each page will contain 80 followers by default."
      operationId: getFollowers
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      - name: sort
        in: query
        required: false
        description: "Default is 'created_at'. Specifies the sort order for the created_at param of the follow\n                                relationship. To sort by newest followers first (descending order) specify\n                                ?sort=-created_at."
        schema:
          type: string
        example: created_at
      responses:
        '200':
          description: A List of followers
          content:
            application/json:
              example:
              - type_of: user_follower
                id: 72
                created_at: '2023-04-14T14:45:36Z'
                user_id: 1375
                name: Taylor "Chrystal" \:/ Pfannerstill
                path: /username435
                username: username435
                profile_image: /uploads/user/profile_image/1375/11fa0607-0d22-4c3c-b339-490ff1e25e8d.jpeg
              - type_of: user_follower
                id: 71
                created_at: '2023-04-14T14:45:36Z'
                user_id: 1372
                name: Carisa "Thurman" \:/ Senger
                path: /username433
                username: username433
                profile_image: /uploads/user/profile_image/1372/bb3c148a-71d4-467d-b25f-ddeb78a6ed63.jpeg
              schema:
                type: array
                items:
                  description: A follower
                  type: object
                  properties:
                    type_of:
                      description: user_follower by default
                      type: string
                    id:
                      type: integer
                      format: int32
                    user_id:
                      description: The follower's user id
                      type: integer
                      format: int32
                    name:
                      description: The follower's name
                      type: string
                    path:
                      description: A path to the follower's profile
                      type: string
                    profile_image:
                      description: Profile image (640x640)
                      type: string
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
components:
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      description: Pagination page
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
    perPageParam30to1000:
      in: query
      name: per_page
      required: false
      description: Page size (the number of items to return per page). The default maximum value can be overridden by "API_PER_PAGE_MAX" environment variable.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 30
  securitySchemes:
    api-key:
      type: apiKey
      name: api-key
      in: header
      description: "API Key authentication.\n\nAuthentication for some endpoints, like write operations on the\nArticles API require a DEV API key.\n\nAll authenticated endpoints are CORS disabled, the API key is intended for non-browser scripts.\n\n### Getting an API key\n\nTo obtain one, please follow these steps:\n\n  - visit https://dev.to/settings/extensions\n  - in the \"DEV API Keys\" section create a new key by adding a\n    description and clicking on \"Generate API Key\"\n\n    ![obtain a DEV API Key](https://user-images.githubusercontent.com/37842/172718105-bd93664e-76e0-477d-99c4-265dda0b06c5.png)\n\n  - You'll see the newly generated key in the same view\n    ![generated DEV API Key](https://user-images.githubusercontent.com/37842/172718151-e7fe26a0-9937-42e8-96c6-333acdab9e49.png)"