openapi: 3.0.3
info:
  title: Forem API V1
  version: 1.0.0
  description: |-
    Access Forem articles, users and other resources via API.
            For a real-world example of Forem in action, check out [DEV](https://www.dev.to).
            All endpoints can be accessed with the 'api-key' header and a accept header, but
            some of them are accessible publicly without authentication.

            Dates and date times, unless otherwise specified, must be in
            the [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
paths:
  /articles:
    post:
      summary: Publish article
      tags:
        - articles
      description: >-
        This endpoint allows the client to create a new article.


        "Articles" are all the posts that users create on DEV that typically
        show up in the feed. They can be a blog post, a discussion question, a
        help thread etc. but is referred to as article within the code.
      operationId: createArticle
      parameters: []
      responses:
        '201':
          description: An Article
          content:
            application/json:
              example:
                type_of: article
                id: 251
                title: New article
                description: New post example
                readable_publish_date: Apr 14
                slug: new-article-4aca
                path: /username383/new-article-4aca
                url: http://localhost:3000/username383/new-article-4aca
                comments_count: 0
                public_reactions_count: 0
                collection_id: 11
                published_timestamp: '2023-04-14T14:45:32Z'
                positive_reactions_count: 0
                cover_image: >-
                  https://thepracticaldev.s3.amazonaws.com/i/5wfo25724gzgk5e5j50g.jpg
                social_image: >-
                  https://thepracticaldev.s3.amazonaws.com/i/5wfo25724gzgk5e5j50g.jpg
                canonical_url: >-
                  https://dev.to/fdocr/headless-chrome-dual-mode-tests-for-ruby-on-rails-4p6g
                created_at: '2023-04-14T14:45:32Z'
                edited_at: null
                crossposted_at: null
                published_at: '2023-04-14T14:45:32Z'
                last_comment_at: '2023-04-14T14:45:32Z'
                reading_time_minutes: 1
                tag_list: ''
                tags: []
                body_html: |+
                  <p><strong>New</strong> body for the article</p>

                body_markdown: '**New** body for the article'
                user:
                  name: Nu "Otis" \:/ Stehr
                  username: username383
                  twitter_username: twitter383
                  github_username: github383
                  user_id: 1304
                  website_url: null
                  profile_image: >-
                    /uploads/user/profile_image/1304/ceaf627b-1551-4771-8d35-a93b40989584.jpeg
                  profile_image_90: >-
                    /uploads/user/profile_image/1304/ceaf627b-1551-4771-8d35-a93b40989584.jpeg
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              example:
                error: 'param is missing or the value is empty: article'
                status: 422
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Article'
    get:
      summary: Published articles
      security: []
      tags:
        - articles
      description: |-
        This endpoint allows the client to retrieve a list of articles.

        "Articles" are all the posts that users create on DEV that typically
        show up in the feed. They can be a blog post, a discussion question,
        a help thread etc. but is referred to as article within the code.

        By default it will return featured, published articles ordered
        by descending popularity.

        It supports pagination, each page will contain `30` articles by default.
      operationId: getArticles
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
        - name: tag
          in: query
          required: false
          description: >-
            Using this parameter will retrieve articles that contain the
            requested tag. Articles

            will be ordered by descending popularity.This parameter can be used
            in conjuction with `top`.
          schema:
            type: string
          example: discuss
        - name: tags
          in: query
          required: false
          description: >-
            Using this parameter will retrieve articles with any of the
            comma-separated tags.

            Articles will be ordered by descending popularity.
          schema:
            type: string
          example: javascript, css
        - name: tags_exclude
          in: query
          required: false
          description: >-
            Using this parameter will retrieve articles that do _not_ contain
            _any_

            of comma-separated tags. Articles will be ordered by descending
            popularity.
          schema:
            type: string
          example: node, java
        - name: username
          in: query
          required: false
          description: |-
            Using this parameter will retrieve articles belonging
                        to a User or Organization ordered by descending publication date.
                        If `state=all` the number of items returned will be `1000` instead of the default `30`.
                        This parameter can be used in conjuction with `state`.
          schema:
            type: string
          example: ben
        - name: state
          in: query
          required: false
          description: >-
            Using this parameter will allow the client to check which articles
            are fresh or rising.
                        If `state=fresh` the server will return fresh articles.
                        If `state=rising` the server will return rising articles.
                        This param can be used in conjuction with `username`, only if set to `all`.
          schema:
            type: string
            enum:
              - fresh
              - rising
              - all
          example: fresh
        - name: top
          in: query
          required: false
          description: >-
            Using this parameter will allow the client to return the most
            popular articles

            in the last `N` days.

            `top` indicates the number of days since publication of the articles
            returned.

            This param can be used in conjuction with `tag`.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 2
        - name: collection_id
          in: query
          required: false
          description: >-
            Adding this will allow the client to return the list of articles

            belonging to the requested collection, ordered by ascending
            publication date.
          schema:
            type: integer
            format: int32
          example: 99
      responses:
        '200':
          description: A List of Articles
          content:
            application/json:
              example:
                - type_of: article
                  id: 254
                  title: All the King's Men175
                  description: >-
                    Typewriter crucifix forage. Pug put a bird on it art party
                    taxidermy asymmetrical xoxo. Sustainable...
                  readable_publish_date: Apr 14
                  slug: all-the-kings-men175-794
                  path: /username387/all-the-kings-men175-794
                  url: http://localhost:3000/username387/all-the-kings-men175-794
                  comments_count: 0
                  public_reactions_count: 0
                  collection_id: null
                  published_timestamp: '2023-04-14T14:45:32Z'
                  positive_reactions_count: 0
                  cover_image: >-
                    http://localhost:3000/assets/36-83d24fbff858b9dd4035d1e7d2df14090946ae4fed631055fc1d5862e7018348.png
                  social_image: >-
                    http://localhost:3000/assets/36-83d24fbff858b9dd4035d1e7d2df14090946ae4fed631055fc1d5862e7018348.png
                  canonical_url: http://localhost:3000/username387/all-the-kings-men175-794
                  created_at: '2023-04-14T14:45:32Z'
                  edited_at: null
                  crossposted_at: null
                  published_at: '2023-04-14T14:45:32Z'
                  last_comment_at: '2023-04-14T14:45:32Z'
                  reading_time_minutes: 1
                  tag_list:
                    - discuss
                  tags: discuss
                  user:
                    name: Versie "Luana" \:/ Runolfsson
                    username: username387
                    twitter_username: twitter387
                    github_username: github387
                    user_id: 1308
                    website_url: null
                    profile_image: >-
                      /uploads/user/profile_image/1308/dfa25219-dfea-4d9a-93ec-403a5f51a29e.jpeg
                    profile_image_90: >-
                      /uploads/user/profile_image/1308/dfa25219-dfea-4d9a-93ec-403a5f51a29e.jpeg
                  organization:
                    name: Ledner, Jaskolski and Bednar
                    username: org70
                    slug: org70
                    profile_image: >-
                      /uploads/organization/profile_image/295/216d3fb5-bd3c-459a-a9d8-572e8332fd88.png
                    profile_image_90: >-
                      /uploads/organization/profile_image/295/216d3fb5-bd3c-459a-a9d8-572e8332fd88.png
                  flare_tag:
                    name: discuss
                    bg_color_hex: '#000000'
                    text_color_hex: '#ffffff'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
  /articles/latest:
    get:
      summary: Published articles sorted by published date
      security: []
      tags:
        - articles
      description: >-
        This endpoint allows the client to retrieve a list of articles. ordered
        by descending publish date.


        It supports pagination, each page will contain 30 articles by default.
      operationId: getLatestArticles
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A List of Articles
          content:
            application/json:
              example:
                - type_of: article
                  id: 257
                  title: East of Eden178
                  description: >-
                    Readymade diy ennui humblebrag 8-bit. Brooklyn hoodie
                    pickled art party vinyl small batch roof. 8-bit...
                  readable_publish_date: Apr 14
                  slug: east-of-eden178-3on4
                  path: /username390/east-of-eden178-3on4
                  url: http://localhost:3000/username390/east-of-eden178-3on4
                  comments_count: 0
                  public_reactions_count: 0
                  collection_id: null
                  published_timestamp: '2023-04-14T14:45:32Z'
                  positive_reactions_count: 0
                  cover_image: >-
                    http://localhost:3000/assets/16-77521848e7b5fcc073ac3e0bb004826e97f737238194e4c79330f662cc946ab2.png
                  social_image: >-
                    http://localhost:3000/assets/16-77521848e7b5fcc073ac3e0bb004826e97f737238194e4c79330f662cc946ab2.png
                  canonical_url: http://localhost:3000/username390/east-of-eden178-3on4
                  created_at: '2023-04-14T14:45:32Z'
                  edited_at: null
                  crossposted_at: null
                  published_at: '2023-04-14T14:45:32Z'
                  last_comment_at: '2023-04-14T14:45:32Z'
                  reading_time_minutes: 1
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  user:
                    name: Starla "Eric" \:/ Kunde
                    username: username390
                    twitter_username: twitter390
                    github_username: github390
                    user_id: 1311
                    website_url: null
                    profile_image: >-
                      /uploads/user/profile_image/1311/11a4ee42-e02e-4b2f-87c1-6123579350b7.jpeg
                    profile_image_90: >-
                      /uploads/user/profile_image/1311/11a4ee42-e02e-4b2f-87c1-6123579350b7.jpeg
                  flare_tag:
                    name: discuss
                    bg_color_hex: '#000000'
                    text_color_hex: '#ffffff'
                - type_of: article
                  id: 256
                  title: A Many-Splendoured Thing177
                  description: >-
                    Letterpress neutra vice raw denim mumblecore organic small
                    batch. Bushwick viral freegan photo booth...
                  readable_publish_date: Apr 14
                  slug: a-many-splendoured-thing177-314b
                  path: /username389/a-many-splendoured-thing177-314b
                  url: >-
                    http://localhost:3000/username389/a-many-splendoured-thing177-314b
                  comments_count: 0
                  public_reactions_count: 0
                  collection_id: null
                  published_timestamp: '2023-04-14T14:45:32Z'
                  positive_reactions_count: 0
                  cover_image: >-
                    http://localhost:3000/assets/27-441873f471d98b5358beff7d47a211e58b9979c6453794f9a7abfd5709c33322.png
                  social_image: >-
                    http://localhost:3000/assets/27-441873f471d98b5358beff7d47a211e58b9979c6453794f9a7abfd5709c33322.png
                  canonical_url: >-
                    http://localhost:3000/username389/a-many-splendoured-thing177-314b
                  created_at: '2023-04-14T14:45:32Z'
                  edited_at: null
                  crossposted_at: null
                  published_at: '2023-04-14T14:45:32Z'
                  last_comment_at: '2023-04-14T14:45:32Z'
                  reading_time_minutes: 1
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  user:
                    name: Jeanne "Donnette" \:/ Waelchi
                    username: username389
                    twitter_username: twitter389
                    github_username: github389
                    user_id: 1310
                    website_url: null
                    profile_image: >-
                      /uploads/user/profile_image/1310/67d345a8-f64b-407f-a802-6f5286b5c4a2.jpeg
                    profile_image_90: >-
                      /uploads/user/profile_image/1310/67d345a8-f64b-407f-a802-6f5286b5c4a2.jpeg
                  flare_tag:
                    name: discuss
                    bg_color_hex: '#000000'
                    text_color_hex: '#ffffff'
                - type_of: article
                  id: 255
                  title: What's Become of Waring176
                  description: >-
                    Whatever church-key irony next level tacos banh mi. Brooklyn
                    wayfarers occupy tacos austin marfa...
                  readable_publish_date: Apr 14
                  slug: whats-become-of-waring176-2lgk
                  path: /username388/whats-become-of-waring176-2lgk
                  url: >-
                    http://localhost:3000/username388/whats-become-of-waring176-2lgk
                  comments_count: 0
                  public_reactions_count: 0
                  collection_id: null
                  published_timestamp: '2023-04-14T14:45:32Z'
                  positive_reactions_count: 0
                  cover_image: >-
                    http://localhost:3000/assets/31-2a89a91581ce9080fed8d62dd9c70a3fd5f92472da8c023e7b29256e04811b2e.png
                  social_image: >-
                    http://localhost:3000/assets/31-2a89a91581ce9080fed8d62dd9c70a3fd5f92472da8c023e7b29256e04811b2e.png
                  canonical_url: >-
                    http://localhost:3000/username388/whats-become-of-waring176-2lgk
                  created_at: '2023-04-14T14:45:32Z'
                  edited_at: null
                  crossposted_at: null
                  published_at: '2023-04-14T14:45:32Z'
                  last_comment_at: '2023-04-14T14:45:32Z'
                  reading_time_minutes: 1
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  user:
                    name: Jerrell "Essie" \:/ Runolfsdottir
                    username: username388
                    twitter_username: twitter388
                    github_username: github388
                    user_id: 1309
                    website_url: null
                    profile_image: >-
                      /uploads/user/profile_image/1309/eaae0231-0ff6-49da-960c-cd30e2486bed.jpeg
                    profile_image_90: >-
                      /uploads/user/profile_image/1309/eaae0231-0ff6-49da-960c-cd30e2486bed.jpeg
                  flare_tag:
                    name: discuss
                    bg_color_hex: '#000000'
                    text_color_hex: '#ffffff'
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
  /articles/{id}:
    get:
      summary: Published article by id
      security: []
      tags:
        - articles
      description: >-
        This endpoint allows the client to retrieve a single published article
        given its `id`.
      operationId: getArticleById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: An Article
          content:
            application/json:
              example:
                type_of: article
                id: 258
                title: Pale Kings and Princes179
                description: >-
                  Etsy you probably haven't heard of them carry humblebrag 90's
                  try-hard. Distillery asymmetrical...
                readable_publish_date: Apr 14
                slug: pale-kings-and-princes179-381c
                path: /username391/pale-kings-and-princes179-381c
                url: >-
                  http://localhost:3000/username391/pale-kings-and-princes179-381c
                comments_count: 0
                public_reactions_count: 0
                collection_id: null
                published_timestamp: '2023-04-14T14:45:32Z'
                positive_reactions_count: 0
                cover_image: >-
                  http://localhost:3000/assets/19-ed58d3e8defcefc445020631589697a05e725243e834b5192aee4e6b91a3e927.png
                social_image: >-
                  http://localhost:3000/assets/19-ed58d3e8defcefc445020631589697a05e725243e834b5192aee4e6b91a3e927.png
                canonical_url: >-
                  http://localhost:3000/username391/pale-kings-and-princes179-381c
                created_at: '2023-04-14T14:45:32Z'
                edited_at: null
                crossposted_at: null
                published_at: '2023-04-14T14:45:32Z'
                last_comment_at: '2023-04-14T14:45:32Z'
                reading_time_minutes: 1
                tag_list: discuss
                tags:
                  - discuss
                body_html: >+
                  <p>Etsy you probably haven't heard of them carry humblebrag
                  90's try-hard. Distillery asymmetrical godard trust fund
                  quinoa pug paleo. Letterpress green juice plaid.</p>


                  <p>Organic +1 pour-over banh mi disrupt listicle. Cronut offal
                  flexitarian twee health poutine cred. Hashtag godard
                  church-key etsy put a bird on it.</p>

                body_markdown: >+
                  ---

                  title: Pale Kings and Princes179

                  published: true

                  tags: discuss

                  date: 

                  series: 

                  canonical_url: 


                  ---


                  Etsy you probably haven't heard of them carry humblebrag 90's
                  try-hard. Distillery asymmetrical godard trust fund quinoa pug
                  paleo. Letterpress green juice plaid.



                  Organic +1 pour-over banh mi disrupt listicle. Cronut offal
                  flexitarian twee health poutine cred. Hashtag godard
                  church-key etsy put a bird on it.

                user:
                  name: Val "Antonina" \:/ Gleichner
                  username: username391
                  twitter_username: twitter391
                  github_username: github391
                  user_id: 1312
                  website_url: null
                  profile_image: >-
                    /uploads/user/profile_image/1312/2eec3cd5-e7fe-42ac-bbfa-27c84d847596.jpeg
                  profile_image_90: >-
                    /uploads/user/profile_image/1312/2eec3cd5-e7fe-42ac-bbfa-27c84d847596.jpeg
                flare_tag:
                  name: discuss
                  bg_color_hex: '#000000'
                  text_color_hex: '#ffffff'
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '404':
          description: Article Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
    put:
      summary: Update an article by id
      tags:
        - articles
      description: >-
        This endpoint allows the client to update an existing article.


        "Articles" are all the posts that users create on DEV that typically
        show up in the feed. They can be a blog post, a discussion question, a
        help thread etc. but is referred to as article within the code.
      operationId: updateArticle
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to unpublish.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 123
      responses:
        '200':
          description: An Article
          content:
            application/json:
              example:
                type_of: article
                id: 259
                title: Noli Me Tangere180
                description: >-
                  Hoodie meh knausgaard bespoke actually shabby chic polaroid.
                  Tumblr ennui semiotics freegan diy...
                readable_publish_date: Apr 14
                slug: noli-me-tangere180-55bp
                path: /username392/noli-me-tangere180-55bp
                url: http://localhost:3000/username392/noli-me-tangere180-55bp
                comments_count: 0
                public_reactions_count: 0
                collection_id: null
                published_timestamp: '2023-04-14T14:45:33Z'
                positive_reactions_count: 0
                cover_image: >-
                  http://localhost:3000/assets/3-93b6b57b5a6115cffe5d63d29a22825eb9e65f647bfef57a88244bc2b98186f0.png
                social_image: >-
                  http://localhost:3000/assets/3-93b6b57b5a6115cffe5d63d29a22825eb9e65f647bfef57a88244bc2b98186f0.png
                canonical_url: http://localhost:3000/username392/noli-me-tangere180-55bp
                created_at: '2023-04-14T14:45:33Z'
                edited_at: '2023-04-14T14:45:33Z'
                crossposted_at: null
                published_at: '2023-04-14T14:45:33Z'
                last_comment_at: '2023-04-14T14:45:33Z'
                reading_time_minutes: 1
                tag_list: ''
                tags: []
                body_html: |+
                  <p><strong>New</strong> body for the article</p>

                body_markdown: '**New** body for the article'
                user:
                  name: Lai "Aide" \:/ Will
                  username: username392
                  twitter_username: twitter392
                  github_username: github392
                  user_id: 1313
                  website_url: null
                  profile_image: >-
                    /uploads/user/profile_image/1313/731805e8-95f2-4260-89f1-489df0c9e945.jpeg
                  profile_image_90: >-
                    /uploads/user/profile_image/1313/731805e8-95f2-4260-89f1-489df0c9e945.jpeg
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '404':
          description: Article Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              example:
                error: 'param is missing or the value is empty: article'
                status: 422
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Article'
  /articles/{username}/{slug}:
    get:
      summary: Published article by path
      security: []
      tags:
        - articles
      description: >-
        This endpoint allows the client to retrieve a single published article
        given its `path`.
      operationId: getArticleByPath
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An Article
          content:
            application/json:
              example:
                type_of: article
                id: 262
                title: Noli Me Tangere183
                description: >-
                  Normcore williamsburg try-hard artisan. Vinyl park shoreditch
                  gastropub vegan knausgaard.  Ethical...
                readable_publish_date: Apr 14
                slug: noli-me-tangere183-1lj5
                path: /username396/noli-me-tangere183-1lj5
                url: http://localhost:3000/username396/noli-me-tangere183-1lj5
                comments_count: 0
                public_reactions_count: 0
                collection_id: null
                published_timestamp: '2023-04-14T14:45:33Z'
                positive_reactions_count: 0
                cover_image: >-
                  http://localhost:3000/assets/37-94b286825ffd9f2b47c9842cf4f262b7c89e789797eba40196bc14b5c2359e75.png
                social_image: >-
                  http://localhost:3000/assets/37-94b286825ffd9f2b47c9842cf4f262b7c89e789797eba40196bc14b5c2359e75.png
                canonical_url: http://localhost:3000/username396/noli-me-tangere183-1lj5
                created_at: '2023-04-14T14:45:33Z'
                edited_at: null
                crossposted_at: null
                published_at: '2023-04-14T14:45:33Z'
                last_comment_at: '2023-04-14T14:45:33Z'
                reading_time_minutes: 1
                tag_list: discuss
                tags:
                  - discuss
                body_html: >+
                  <p>Normcore williamsburg try-hard artisan. Vinyl park
                  shoreditch gastropub vegan knausgaard.</p>


                  <p>Ethical trust fund intelligentsia pbr&amp;b. Brunch seitan
                  pug waistcoat farm-to-table flexitarian health. Tumblr banh mi
                  goth retro diy.</p>

                body_markdown: >+
                  ---

                  title: Noli Me Tangere183

                  published: true

                  tags: discuss

                  date: 

                  series: 

                  canonical_url: 


                  ---


                  Normcore williamsburg try-hard artisan. Vinyl park shoreditch
                  gastropub vegan knausgaard.



                  Ethical trust fund intelligentsia pbr&b. Brunch seitan pug
                  waistcoat farm-to-table flexitarian health. Tumblr banh mi
                  goth retro diy.

                user:
                  name: Ashely "Erich" \:/ Waters
                  username: username396
                  twitter_username: twitter396
                  github_username: github396
                  user_id: 1317
                  website_url: null
                  profile_image: >-
                    /uploads/user/profile_image/1317/e7282d93-954d-4b13-805e-9e5636ad9d63.jpeg
                  profile_image_90: >-
                    /uploads/user/profile_image/1317/e7282d93-954d-4b13-805e-9e5636ad9d63.jpeg
                flare_tag:
                  name: discuss
                  bg_color_hex: '#000000'
                  text_color_hex: '#ffffff'
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '404':
          description: Article Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /articles/me:
    get:
      summary: User's articles
      tags:
        - articles
        - users
      description: >-
        This endpoint allows the client to retrieve a list of published articles
        on behalf of an authenticated user.


        "Articles" are all the posts that users create on DEV that typically
        show up in the feed. They can be a blog post, a discussion question, a
        help thread etc. but is referred to as article within the code.


        Published articles will be in reverse chronological publication order.


        It will return published articles with pagination. By default a page
        will contain 30 articles.
      operationId: getUserArticles
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A List of the authenticated user's Articles
          content:
            application/json:
              example: []
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /articles/me/published:
    get:
      summary: User's published articles
      tags:
        - articles
        - users
      description: >-
        This endpoint allows the client to retrieve a list of published articles
        on behalf of an authenticated user.


        "Articles" are all the posts that users create on DEV that typically
        show up in the feed. They can be a blog post, a discussion question, a
        help thread etc. but is referred to as article within the code.


        Published articles will be in reverse chronological publication order.


        It will return published articles with pagination. By default a page
        will contain 30 articles.
      operationId: getUserPublishedArticles
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A List of the authenticated user's Articles
          content:
            application/json:
              example: []
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /articles/me/unpublished:
    get:
      summary: User's unpublished articles
      tags:
        - articles
        - users
      description: >-
        This endpoint allows the client to retrieve a list of unpublished
        articles on behalf of an authenticated user.


        "Articles" are all the posts that users create on DEV that typically
        show up in the feed. They can be a blog post, a discussion question, a
        help thread etc. but is referred to as article within the code.


        Unpublished articles will be in reverse chronological creation order.


        It will return unpublished articles with pagination. By default a page
        will contain 30 articles.
      operationId: getUserUnpublishedArticles
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A List of the authenticated user's Articles
          content:
            application/json:
              example: []
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /articles/me/all:
    get:
      summary: User's all articles
      tags:
        - articles
        - users
      description: >-
        This endpoint allows the client to retrieve a list of all articles on
        behalf of an authenticated user.


        "Articles" are all the posts that users create on DEV that typically
        show up in the feed. They can be a blog post, a discussion question, a
        help thread etc. but is referred to as article within the code.


        It will return both published and unpublished articles with pagination.


        Unpublished articles will be at the top of the list in reverse
        chronological creation order. Published articles will follow in reverse
        chronological publication order.


        By default a page will contain 30 articles.
      operationId: getUserAllArticles
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A List of the authenticated user's Articles
          content:
            application/json:
              example: []
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /articles/{id}/unpublish:
    put:
      summary: Unpublish an article
      tags:
        - articles
      description: >-
        This endpoint allows the client to unpublish an article.


        The user associated with the API key must have any 'admin' or
        'moderator' role.


        The article will be unpublished and will no longer be visible to the
        public. It will remain

        in the database and will set back to draft status on the author's posts
        dashboard. Any

        notifications associated with the article will be deleted. Any comments
        on the article

        will remain.
      operationId: unpublishArticle
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the article to unpublish.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 1
        - name: note
          in: query
          required: false
          description: Content for the note that's created along with unpublishing
          schema:
            type: string
          example: Admin requested unpublishing all articles via API
      responses:
        '204':
          description: Article successfully unpublished
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '404':
          description: Article Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /comments:
    get:
      summary: Comments
      security: []
      tags:
        - comments
      description: >-
        This endpoint allows the client to retrieve all comments belonging to an
        article or podcast episode as threaded conversations.


        It will return the all top level comments with their nested comments as
        threads. See the format specification for further details.
      operationId: getCommentsByArticleId
      parameters:
        - name: a_id
          in: query
          required: false
          description: Article identifier.
          schema:
            type: string
          example: '321'
        - name: p_id
          in: query
          required: false
          description: Podcast Episode identifier.
          schema:
            type: string
          example: '321'
      responses:
        '200':
          description: A List of Comments
          content:
            application/json:
              example:
                - type_of: comment
                  id_code: '52'
                  created_at: '2023-04-14T14:45:34Z'
                  body_html: >+
                    <p>Pop-up salvia vhs gluten-free tilde cleanse. Gastropub
                    offal next level. Gluten-free health stumptown kale chips
                    wolf.</p>

                  user:
                    name: Luigi "Ryann" \:/ Wuckert
                    username: username410
                    twitter_username: twitter410
                    github_username: github410
                    user_id: 1332
                    website_url: null
                    profile_image: >-
                      /uploads/user/profile_image/1332/241b2d6f-ec6d-4590-b57f-3a2ce673f9de.jpeg
                    profile_image_90: >-
                      /uploads/user/profile_image/1332/241b2d6f-ec6d-4590-b57f-3a2ce673f9de.jpeg
                  children: []
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
        '404':
          description: Resource Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /comments/{id}:
    get:
      summary: Comment by id
      security: []
      tags:
        - comments
      description: >-
        This endpoint allows the client to retrieve a comment as well as his
        descendants comments.

          It will return the required comment (the root) with its nested descendants as a thread.

          See the format specification for further details.
      operationId: getCommentById
      parameters:
        - name: id
          in: path
          required: true
          description: Comment identifier.
          schema:
            type: integer
          example: '321'
      responses:
        '200':
          description: A List of the Comments
          content:
            application/json:
              example:
                type_of: comment
                id_code: '54'
                created_at: '2023-04-14T14:45:35Z'
                body_html: >+
                  <p>Ramps tacos jean shorts humblebrag street bicycle rights
                  paleo. Actually green juice chartreuse tattooed cliche. 8-bit
                  bushwick diy aesthetic.</p>

                user:
                  name: Santos "Broderick" \:/ Lemke
                  username: username414
                  twitter_username: twitter414
                  github_username: github414
                  user_id: 1339
                  website_url: null
                  profile_image: >-
                    /uploads/user/profile_image/1339/08f5cd26-743e-4957-af23-540b7ded60d6.jpeg
                  profile_image_90: >-
                    /uploads/user/profile_image/1339/08f5cd26-743e-4957-af23-540b7ded60d6.jpeg
                children: []
        '404':
          description: Comment Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /display_ads:
    get:
      summary: display ads
      tags:
        - display ads
      description: This endpoint allows the client to retrieve a list of all display ads.
      responses:
        '200':
          description: successful
          content:
            application/json:
              example: []
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DisplayAd'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
    post:
      summary: display ads
      tags:
        - display ads
      description: This endpoint allows the client to create a new display ad.
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 193
                approved: true
                body_markdown: |-
                  # Hi, this is ad
                  Yep, it's an ad
                cached_tag_list: ''
                clicks_count: 0
                created_at: '2023-04-14T18:45:35.606+04:00'
                creator_id: null
                display_to: all
                exclude_article_ids: ''
                impressions_count: 0
                name: Example Ad
                organization_id: null
                placement_area: post_comments
                processed_html: >-
                  <h1>  <a href="#hi-this-is-ad" class="anchor">  </a>  Hi, this
                  is ad</h1><p>Yep, it's an ad</p>
                published: true
                success_rate: 0
                type_of: in_house
                updated_at: '2023-04-14T18:45:35.606+04:00'
                audience_segment_type: null
                tag_list: ''
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/DisplayAd'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '422':
          description: unprocessable
          content:
            application/json:
              example:
                id: null
                approved: true
                body_markdown: |-
                  # Hi, this is ad
                  Yep, it's an ad
                cached_tag_list: null
                clicks_count: 0
                created_at: null
                creator_id: null
                display_to: all
                exclude_article_ids: ''
                impressions_count: 0
                name: Example Ad
                organization_id: null
                placement_area: moon
                processed_html: null
                published: true
                success_rate: 0
                type_of: in_house
                updated_at: null
                audience_segment_type: null
                tag_list: null
      requestBody:
        content:
          application/json:
            schema:
              type: object
              items:
                $ref: '#/components/schemas/DisplayAd'
  /display_ads/{id}:
    get:
      summary: display ad
      tags:
        - display ads
      description: >-
        This endpoint allows the client to retrieve a single display ad, via its
        id.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the display ad.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 123
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 196
                approved: false
                body_markdown: Hello _hey_ Hey hey 9
                cached_tag_list: ''
                clicks_count: 0
                created_at: '2023-04-14T18:45:35.813+04:00'
                creator_id: null
                display_to: all
                exclude_article_ids: ''
                impressions_count: 0
                name: Display Ad 196
                organization_id: 304
                placement_area: sidebar_left
                processed_html: <p>Hello <em>hey</em> Hey hey 9</p>
                published: false
                success_rate: 0
                type_of: in_house
                updated_at: '2023-04-14T18:45:35.817+04:00'
                audience_segment_type: null
                tag_list: ''
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '404':
          description: Unknown DisplayAd ID
          content:
            application/json:
              example:
                error: not found
                status: 404
    put:
      summary: display ads
      tags:
        - display ads
      description: >-
        This endpoint allows the client to update the attributes of a single
        display ad, via its id.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the display ad.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 123
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                approved: false
                body_markdown: Hello _hey_ Hey hey 10
                creator_id: null
                display_to: all
                name: Display Ad 198
                organization_id: 306
                placement_area: sidebar_left
                published: false
                type_of: in_house
                exclude_article_ids: ''
                cached_tag_list: ''
                id: 198
                clicks_count: 0
                created_at: '2023-04-14T18:45:36.047+04:00'
                impressions_count: 0
                processed_html: <p>Hello <em>hey</em> Hey hey 10</p>
                success_rate: 0
                updated_at: '2023-04-14T18:45:36.051+04:00'
                audience_segment_type: null
                tag_list: ''
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/DisplayAd'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '404':
          description: not found
          content:
            application/json:
              example:
                error: not found
                status: 404
      requestBody:
        content:
          application/json:
            schema:
              type: object
              items:
                $ref: '#/components/schemas/DisplayAd'
  /display_ads/{id}/unpublish:
    put:
      summary: unpublish
      tags:
        - display ads
      description: >-
        This endpoint allows the client to remove a display ad from rotation by
        un-publishing it.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the display ad to unpublish.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 123
      responses:
        '204':
          description: no content
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '404':
          description: not found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /follows/tags:
    get:
      summary: Followed Tags
      tags:
        - followed_tags
        - tags
      description: >-
        This endpoint allows the client to retrieve a list of the tags they
        follow.
      operationId: getFollowedTags
      responses:
        '200':
          description: A List of followed tags
          content:
            application/json:
              example:
                - id: 701
                  name: tag3
                  points: 1
                - id: 702
                  name: tag4
                  points: 1
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FollowedTag'
        '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.
                "Followers" are users that are following other users on the website.
                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
                                            relationship. To sort by newest followers first (descending order) specify
                                            ?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
  /organizations/{username}:
    get:
      summary: An organization
      tags:
        - organizations
      security: []
      description: >-
        This endpoint allows the client to retrieve a single organization by
        their username
      operationId: getOrganization
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An Organization
          content:
            application/json:
              example:
                type_of: organization
                id: 323
                username: org77
                name: Skiles-Frami
                summary: >-
                  Franzen seitan mustache cred. Gluten-free flannel gastropub
                  hoodie vinegar wolf mixtape.
                twitter_username: org26
                github_username: org5524
                url: http://jacobs.com/assunta.rau
                location: null
                tech_stack: null
                tag_line: null
                story: null
                joined_at: '2023-04-14T14:45:37Z'
                profile_image: >-
                  /uploads/organization/profile_image/323/d1677329-759a-44e1-866e-c5be50e9593b.png
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/Organization'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /organizations/{username}/users:
    get:
      summary: Organization's users
      tags:
        - organizations
        - users
      security: []
      description: >-
        This endpoint allows the client to retrieve a list of users belonging to
        the organization


        It supports pagination, each page will contain `30` users by default.
      operationId: getOrgUsers
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: An Organization's users
          content:
            application/json:
              example:
                - type_of: user
                  id: 1390
                  username: username445
                  name: Ute "Doreen" \:/ Tillman
                  twitter_username: twitter445
                  github_username: github445
                  summary: null
                  location: null
                  website_url: null
                  joined_at: Apr 14, 2023
                  profile_image: >-
                    /uploads/user/profile_image/1390/7b885cdf-c1c6-481a-a6d8-19f0404da87a.jpeg
                - type_of: user
                  id: 1391
                  username: username446
                  name: Abraham "Colton" \:/ Ritchie
                  twitter_username: twitter446
                  github_username: github446
                  summary: null
                  location: null
                  website_url: null
                  joined_at: Apr 14, 2023
                  profile_image: >-
                    /uploads/user/profile_image/1391/273ffa06-dc97-4b84-ba4c-43d24efb55e5.jpeg
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /organizations/{username}/articles:
    get:
      summary: Organization's Articles
      tags:
        - organizations
        - articles
      security: []
      description: >-
        This endpoint allows the client to retrieve a list of Articles belonging
        to the organization


        It supports pagination, each page will contain `30` users by default.
      operationId: getOrgArticles
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: An Organization's Articles
          content:
            application/json:
              example:
                - type_of: article
                  id: 276
                  title: Down to a Sunless Sea195
                  description: >-
                    Scenester occupy swag. Yr godard single-origin coffee
                    biodiesel beard artisan. Wes anderson yolo...
                  readable_publish_date: Apr 14
                  slug: down-to-a-sunless-sea195-51d4
                  path: /org81/down-to-a-sunless-sea195-51d4
                  url: http://localhost:3000/org81/down-to-a-sunless-sea195-51d4
                  comments_count: 0
                  public_reactions_count: 0
                  collection_id: null
                  published_timestamp: '2023-04-14T14:45:38Z'
                  positive_reactions_count: 0
                  cover_image: >-
                    http://localhost:3000/assets/38-3b0c46cc0d5367229799d282c99b2c42f33501201cac1ceb5c643f9ee11f06c6.png
                  social_image: >-
                    http://localhost:3000/assets/38-3b0c46cc0d5367229799d282c99b2c42f33501201cac1ceb5c643f9ee11f06c6.png
                  canonical_url: http://localhost:3000/org81/down-to-a-sunless-sea195-51d4
                  created_at: '2023-04-14T14:45:38Z'
                  edited_at: null
                  crossposted_at: null
                  published_at: '2023-04-14T14:45:38Z'
                  last_comment_at: '2023-04-14T14:45:38Z'
                  reading_time_minutes: 1
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  user:
                    name: Annabell "Tyron" \:/ West
                    username: username453
                    twitter_username: twitter453
                    github_username: github453
                    user_id: 1399
                    website_url: null
                    profile_image: >-
                      /uploads/user/profile_image/1399/15f1c715-4e10-4f57-9cca-7a2071dfdf23.jpeg
                    profile_image_90: >-
                      /uploads/user/profile_image/1399/15f1c715-4e10-4f57-9cca-7a2071dfdf23.jpeg
                  organization:
                    name: Schuster LLC
                    username: org81
                    slug: org81
                    profile_image: >-
                      /uploads/organization/profile_image/334/824e9ec6-b41c-4824-87e8-ae7721868787.png
                    profile_image_90: >-
                      /uploads/organization/profile_image/334/824e9ec6-b41c-4824-87e8-ae7721868787.png
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /pages:
    get:
      summary: show details for all pages
      security: []
      tags:
        - pages
      description: >-
        This endpoint allows the client to retrieve details for all Page
        objects.
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                - id: 5
                  title: An Instant In The Wind
                  slug: trivial_exaggerate
                  description: Excepturi illum tenetur nisi.
                  is_top_level_path: false
                  landing_page: false
                  body_html: null
                  body_json: null
                  body_markdown: Et voluptas cupiditate voluptatibus.
                  processed_html: |+
                    <p>Et voluptas cupiditate voluptatibus.</p>

                  social_image:
                    url: null
                  template: contained
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Page'
    post:
      summary: pages
      tags:
        - pages
      description: This endpoint allows the client to create a new page.
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 7
                title: Example Page
                slug: example1
                description: a new page
                is_top_level_path: false
                landing_page: false
                body_html: null
                body_json: null
                body_markdown: |-
                  # Hi, this is a New Page
                  Yep, it's an a new page
                processed_html: |+
                  <h1>
                    <a name="hi-this-is-a-new-page" href="#hi-this-is-a-new-page">
                    </a>
                    Hi, this is a New Page
                  </h1>

                  <p>Yep, it's an a new page</p>

                social_image:
                  url: null
                template: contained
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '422':
          description: unprocessable
          content:
            application/json:
              example:
                id: null
                title: Example Page
                slug: example1
                description: a new page
                is_top_level_path: false
                landing_page: false
                body_html: null
                body_json: null
                body_markdown: |-
                  # Hi, this is a New Page
                  Yep, it's an a new page
                processed_html: null
                social_image:
                  url: null
                template: moon
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Title of the page
                slug:
                  type: string
                  description: >-
                    Used to link to this page in URLs, must be unique and
                    URL-safe
                description:
                  type: string
                  description: For internal use, helps similar pages from one another
                body_markdown:
                  type: string
                  description: The text (in markdown) of the ad (required)
                body_json:
                  type: string
                  description: For JSON pages, the JSON body
                is_top_level_path:
                  type: boolean
                  description: >-
                    If true, the page is available at '/{slug}' instead of
                    '/page/{slug}', use with caution
                template:
                  type: string
                  enum:
                    - contained
                    - full_within_layout
                    - nav_bar_included
                    - json
                  default: contained
                  description: Controls what kind of layout the page is rendered in
  /pages/{id}:
    get:
      summary: show details for a page
      security: []
      tags:
        - pages
      description: >-
        This endpoint allows the client to retrieve details for a single Page
        object, specified by ID.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 1
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 10
                title: A Swiftly Tilting Planet
                slug: corn-laser
                description: Inventore ad qui dolore.
                is_top_level_path: false
                landing_page: false
                body_html: null
                body_json: null
                body_markdown: In sit sit voluptas.
                processed_html: |+
                  <p>In sit sit voluptas.</p>

                social_image:
                  url: null
                template: contained
              schema:
                $ref: '#/components/schemas/Page'
    put:
      summary: update details for a page
      tags:
        - pages
      description: >-
        This endpoint allows the client to retrieve details for a single Page
        object, specified by ID.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 1
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 11
                title: New Title
                slug: authority-figure
                description: Et odio nostrum dolorem.
                is_top_level_path: false
                landing_page: false
                body_html: null
                body_json: null
                body_markdown: Consequatur ex soluta libero.
                processed_html: |+
                  <p>Consequatur ex soluta libero.</p>

                social_image:
                  url: null
                template: contained
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '422':
          description: unprocessable
          content:
            application/json:
              example:
                id: 13
                title: Little Hands Clapping
                slug: horizon_nursery
                description: Vel tenetur aspernatur mollitia.
                is_top_level_path: false
                landing_page: false
                body_html: null
                body_json: null
                body_markdown: Omnis quia eaque aliquam.
                processed_html: |+
                  <p>Consequatur sit illum voluptas.</p>

                social_image:
                  url: null
                template: moon
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Page'
    delete:
      summary: remove a page
      tags:
        - pages
      description: >-
        This endpoint allows the client to delete a single Page object,
        specified by ID.
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 1
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 14
                title: The Skull Beneath the Skin
                slug: appointment-provision
                description: Et error fuga natus.
                is_top_level_path: false
                landing_page: false
                body_html: null
                body_json: null
                body_markdown: Quo quibusdam nisi numquam.
                processed_html: |+
                  <p>Quo quibusdam nisi numquam.</p>

                social_image:
                  url: null
                template: contained
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '422':
          description: unprocessable
          content:
            application/json:
              example:
                doubled_module:
                  const_name: Page
                  object: Page
                __expired: false
                name: null
                __sending_message: null
  /podcast_episodes:
    get:
      summary: Podcast Episodes
      security: []
      tags:
        - podcast_episodes
      description: |-
        This endpoint allows the client to retrieve a list of podcast episodes.
                "Podcast episodes" are episodes belonging to podcasts.
                It will only return active (reachable) podcast episodes that belong to published podcasts available on the platform, ordered by descending publication date.
                It supports pagination, each page will contain 30 articles by default.
      operationId: getPodcastEpisodes
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
        - name: username
          in: query
          required: false
          description: >-
            Using this parameter will retrieve episodes belonging to a specific
            podcast.
          schema:
            type: string
          example: codenewbie
      responses:
        '200':
          description: A List of Podcast episodes filtered by username
          content:
            application/json:
              example:
                - type_of: podcast_episodes
                  class_name: PodcastEpisode
                  id: 4
                  path: /codenewbie/slug-4
                  title: '5'
                  image_url: >-
                    /uploads/podcast/image/8/624a3c09-8036-43e4-9187-4cbf6d3c1fd6.jpeg
                  podcast:
                    title: Maudite
                    slug: codenewbie
                    image_url: >-
                      /uploads/podcast/image/8/624a3c09-8036-43e4-9187-4cbf6d3c1fd6.jpeg
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PodcastEpisodeIndex'
        '404':
          description: Unknown Podcast username
          content:
            application/json:
              example:
                error: not found
                status: 404
  /profile_images/{username}:
    get:
      summary: A Users or organizations profile image
      tags:
        - profile images
      description: >-
        This endpoint allows the client to retrieve a user or organization
        profile image information by its
                corresponding username.
      operationId: getProfileImage
      parameters:
        - name: username
          in: path
          required: true
          description: >-
            The parameter is the username of the user or the username of the
            organization.
          schema:
            type: string
          example: janedoe
      responses:
        '200':
          description: An object containing profile image details
          content:
            application/json:
              example:
                type_of: profile_image
                image_of: user
                profile_image: >-
                  /uploads/user/profile_image/1419/f2b13e85-a3a0-49cf-9da0-7922248be024.jpeg
                profile_image_90: >-
                  /uploads/user/profile_image/1419/f2b13e85-a3a0-49cf-9da0-7922248be024.jpeg
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/ProfileImage'
        '404':
          description: Resource Not Found
          content:
            application/json:
              example:
                error: not found
                status: 404
  /reactions/toggle:
    post:
      summary: toggle reaction
      tags:
        - reactions
      description: >-
        This endpoint allows the client to toggle the user's reaction to a
        specified reactable (eg, Article, Comment, or User). For examples:
                * "Like"ing an Article will create a new "like" Reaction from the user for that Articles
                * "Like"ing that Article a second time will remove the "like" from the user
      parameters:
        - name: category
          in: query
          required: true
          schema:
            type: string
            enum:
              - like
              - unicorn
              - exploding_head
              - raised_hands
              - fire
        - name: reactable_id
          in: query
          required: true
          schema:
            type: integer
            format: int32
        - name: reactable_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - Comment
              - Article
              - User
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                result: create
                category: like
                id: 13
                reactable_id: 283
                reactable_type: Article
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /reactions:
    post:
      summary: create reaction
      tags:
        - reactions
      description: >-
        This endpoint allows the client to create a reaction to a specified
        reactable (eg, Article, Comment, or User). For examples:
                * "Like"ing an Article will create a new "like" Reaction from the user for that Articles
                * "Like"ing that Article a second time will return the previous "like"
      parameters:
        - name: category
          in: query
          required: true
          schema:
            type: string
            enum:
              - like
              - unicorn
              - exploding_head
              - raised_hands
              - fire
        - name: reactable_id
          in: query
          required: true
          schema:
            type: integer
            format: int32
        - name: reactable_type
          in: query
          required: true
          schema:
            type: string
            enum:
              - Comment
              - Article
              - User
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                result: none
                category: like
                id: 15
                reactable_id: 285
                reactable_type: Article
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /readinglist:
    get:
      summary: Readinglist
      tags:
        - readinglist
      description: >-
        This endpoint allows the client to retrieve a list of articles that were
        saved to a Users readinglist.
                It supports pagination, each page will contain `30` articles by default
      operationId: getReadinglist
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A list of articles in the users readinglist
          content:
            application/json:
              example: []
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /tags:
    get:
      summary: Tags
      tags:
        - tags
      security: []
      description: >-
        This endpoint allows the client to retrieve a list of tags that can be
        used to tag articles.


        It will return tags ordered by popularity.


        It supports pagination, each page will contain 10 tags by default.
      operationId: getTags
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam10to1000'
      responses:
        '200':
          description: A List of all tags
          content:
            application/json:
              example:
                - id: 806
                  name: tag5
                  bg_color_hex: null
                  text_color_hex: null
                - id: 808
                  name: tag6
                  bg_color_hex: null
                  text_color_hex: null
                - id: 809
                  name: tag7
                  bg_color_hex: null
                  text_color_hex: null
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
  /users/me:
    get:
      summary: The authenticated user
      tags:
        - users
      description: >-
        This endpoint allows the client to retrieve information about the
        authenticated user
      operationId: getUserMe
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                type_of: user
                id: 1431
                username: username480
                name: Willy "Myron" \:/ Herzog
                twitter_username: twitter480
                github_username: github480
                summary: null
                location: null
                website_url: null
                joined_at: Apr 14, 2023
                profile_image: >-
                  /uploads/user/profile_image/1431/b547e3a6-5076-44dd-a4f6-9b85022b4e76.jpeg
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
  /users/{id}:
    get:
      summary: A User
      tags:
        - users
      description: >-
        This endpoint allows the client to retrieve a single user, either by id

        or by the user's username.


        For complete documentation, see the v0 API docs:
        https://developers.forem.com/api/v0#tag/users/operation/getUser
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/User'
  /users/{id}/unpublish:
    put:
      summary: Unpublish a User's Articles and Comments
      tags:
        - users
      description: >-
        This endpoint allows the client to unpublish all of the articles and

        comments created by a user.


        The user associated with the API key must have any 'admin' or
        'moderator' role.


        This specified user's articles and comments will be unpublished and will
        no longer be

        visible to the public. They will remain in the database and will set
        back to draft status

        on the specified user's  dashboard. Any notifications associated with
        the specified user's

        articles and comments will be deleted.


        Note this endpoint unpublishes articles and comments asychronously: it
        will return a 204 NO CONTENT

        status code immediately, but the articles and comments will not be
        unpublished until the

        request is completed on the server.
      operationId: unpublishUser
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to unpublish.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 1
      responses:
        '204':
          description: User's articles and comments successfully unpublished
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '404':
          description: Unknown User ID (still accepted for async processing)
          content:
            application/json:
              example:
                error: not found
                status: 404
  /users/{id}/suspend:
    put:
      summary: Suspend a User
      tags:
        - users
      description: >-
        This endpoint allows the client to suspend a user.


        The user associated with the API key must have any 'admin' or
        'moderator' role.


        This specified user will be assigned the 'suspended' role. Suspending a
        user will stop the

        user from posting new posts and comments. It doesn't delete any of the
        user's content, just

        prevents them from creating new content while suspended. Users are not
        notified of their suspension

        in the UI, so if you want them to know about this, you must notify them.
      operationId: suspendUser
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to suspend.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 1
      responses:
        '204':
          description: User successfully unpublished
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '404':
          description: Unknown User ID
          content:
            application/json:
              example:
                error: not found
                status: 404
  /admin/users:
    post:
      summary: Invite a User
      tags:
        - users
      description: >-
        This endpoint allows the client to trigger an invitation to the provided
        email address.

                It requires a token from a user with `super_admin` privileges.
      operationId: postAdminUsersCreate
      parameters: []
      responses:
        '200':
          description: Successful
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              example:
                error: 'param is missing or the value is empty: email'
                status: 422
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInviteParam'
  /videos:
    get:
      summary: Articles with a video
      tags:
        - videos
        - articles
      security: []
      description: >-
        This endpoint allows the client to retrieve a list of articles that are
        uploaded with a video.


        It will only return published video articles ordered by descending
        popularity.


        It supports pagination, each page will contain 24 articles by default.
      operationId: videos
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam24to1000'
      responses:
        '200':
          description: A List of all articles with videos
          content:
            application/json:
              example:
                - type_of: video_article
                  id: 287
                  path: /username499/the-millstone201-1kgb
                  cloudinary_video_url: >-
                    https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/thumbs-video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f-00001.png
                  title: The Millstone201
                  user_id: 1452
                  video_duration_in_minutes: '00:00'
                  video_source_url: >-
                    https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f.m3u8
                  user:
                    name: Edgardo "Monroe" \:/ Gusikowski
                - type_of: video_article
                  id: 288
                  path: /username500/a-many-splendoured-thing202-4gnk
                  cloudinary_video_url: >-
                    https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/thumbs-video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f-00001.png
                  title: A Many-Splendoured Thing202
                  user_id: 1453
                  video_duration_in_minutes: '00:00'
                  video_source_url: >-
                    https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f.m3u8
                  user:
                    name: Arlena "Catarina" \:/ Zulauf
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VideoArticle'
servers:
  - url: https://dev.to/api
    description: Production server
security:
  - api-key: []
components:
  securitySchemes:
    api-key:
      type: apiKey
      name: api-key
      in: header
      description: >-
        API Key authentication.


        Authentication for some endpoints, like write operations on the

        Articles API require a DEV API key.


        All authenticated endpoints are CORS disabled, the API key is intended
        for non-browser scripts.


        ### Getting an API key


        To obtain one, please follow these steps:

          - visit https://dev.to/settings/extensions
          - in the "DEV API Keys" section create a new key by adding a
            description and clicking on "Generate API Key"

            ![obtain a DEV API Key](https://user-images.githubusercontent.com/37842/172718105-bd93664e-76e0-477d-99c4-265dda0b06c5.png)

          - You'll see the newly generated key in the same view
            ![generated DEV API Key](https://user-images.githubusercontent.com/37842/172718151-e7fe26a0-9937-42e8-96c6-333acdab9e49.png)
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      description: Pagination page
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
    perPageParam10to1000:
      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: 10
    perPageParam24to1000:
      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: 24
    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
    perPageParam30to100:
      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: 100
        default: 30
    perPageParam80to1000:
      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: 80
    listingCategoryParam:
      name: category
      in: query
      description: |-
        Using this parameter will return listings belonging to the
                      requested category.
      schema:
        type: string
      example: cfp
  schemas:
    ArticleFlareTag:
      description: Flare tag of the article
      type: object
      properties:
        name:
          type: string
        bg_color_hex:
          description: Background color (hexadecimal)
          type: string
          nullable: true
        text_color_hex:
          description: Text color (hexadecimal)
          type: string
          nullable: true
    ArticleIndex:
      description: Representation of an article or post returned in a list
      type: object
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        title:
          type: string
        description:
          type: string
        cover_image:
          type: string
          format: url
          nullable: true
        readable_publish_date:
          type: string
        social_image:
          type: string
          format: url
        tag_list:
          type: array
          items:
            type: string
        tags:
          type: string
        slug:
          type: string
        path:
          type: string
          format: path
        url:
          type: string
          format: url
        canonical_url:
          type: string
          format: url
        positive_reactions_count:
          type: integer
          format: int32
        public_reactions_count:
          type: integer
          format: int32
        created_at:
          type: string
          format: date-time
        edited_at:
          type: string
          format: date-time
          nullable: true
        crossposted_at:
          type: string
          format: date-time
          nullable: true
        published_at:
          type: string
          format: date-time
        last_comment_at:
          type: string
          format: date-time
        published_timestamp:
          description: Crossposting or published date time
          type: string
          format: date-time
        reading_time_minutes:
          description: Reading time, in minutes
          type: integer
          format: int32
        user:
          $ref: '#/components/schemas/SharedUser'
        flare_tag:
          $ref: '#/components/schemas/ArticleFlareTag'
        organization:
          $ref: '#/components/schemas/SharedOrganization'
      required:
        - type_of
        - id
        - title
        - description
        - cover_image
        - readable_publish_date
        - social_image
        - tag_list
        - tags
        - slug
        - path
        - url
        - canonical_url
        - comments_count
        - positive_reactions_count
        - public_reactions_count
        - created_at
        - edited_at
        - crossposted_at
        - published_at
        - last_comment_at
        - published_timestamp
        - user
        - reading_time_minutes
    VideoArticle:
      description: Representation of an Article with video
      type: object
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int64
        path:
          type: string
        cloudinary_video_url:
          type: string
        title:
          type: string
        user_id:
          type: integer
          format: int64
        video_duration_in_minutes:
          type: string
        video_source_url:
          type: string
        user:
          description: Author of the article
          type: object
          properties:
            name:
              type: string
    Article:
      description: Representation of an Article to be created/updated
      type: object
      properties:
        article:
          type: object
          properties:
            title:
              type: string
            body_markdown:
              type: string
            published:
              type: boolean
              default: false
            series:
              type: string
              nullable: true
            main_image:
              type: string
              nullable: true
            canonical_url:
              type: string
              nullable: true
            description:
              type: string
            tags:
              type: string
            organization_id:
              type: integer
              nullable: true
    Organization:
      description: Representation of an Organization
      type: object
      properties:
        type_of:
          type: string
        username:
          type: string
        name:
          type: string
        summary:
          type: string
        twitter_username:
          type: string
        github_username:
          type: string
        url:
          type: string
        location:
          type: string
        joined_at:
          type: string
        tech_stack:
          type: string
        tag_line:
          type: string
          nullable: true
        story:
          type: string
          nullable: true
    FollowedTag:
      description: Representation of a followed tag
      type: object
      properties:
        id:
          description: Tag id
          type: integer
          format: int64
        name:
          type: string
        points:
          type: number
          format: float
      required:
        - id
        - name
        - points
    Tag:
      description: Representation of a tag
      type: object
      properties:
        id:
          description: Tag id
          type: integer
          format: int64
        name:
          type: string
        bg_color_hex:
          type: string
          nullable: true
        text_color_hex:
          type: string
          nullable: true
    Page:
      description: Representation of a page object
      type: object
      properties:
        title:
          type: string
          description: Title of the page
        slug:
          type: string
          description: Used to link to this page in URLs, must be unique and URL-safe
        description:
          type: string
          description: For internal use, helps similar pages from one another
        body_markdown:
          type: string
          description: The text (in markdown) of the ad (required)
          nullable: true
        body_json:
          type: string
          description: For JSON pages, the JSON body
          nullable: true
        is_top_level_path:
          type: boolean
          description: >-
            If true, the page is available at '/{slug}' instead of
            '/page/{slug}', use with caution
        social_image:
          type: object
          nullable: true
        template:
          type: string
          enum:
            - contained
            - full_within_layout
            - nav_bar_included
            - json
          default: contained
          description: Controls what kind of layout the page is rendered in
      required:
        - title
        - slug
        - description
        - template
    PodcastEpisodeIndex:
      description: Representation of a podcast episode returned in a list
      type: object
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        class_name:
          type: string
        path:
          type: string
          format: path
        title:
          type: string
        image_url:
          description: Podcast episode image url or podcast image url
          type: string
          format: url
        podcast:
          $ref: '#/components/schemas/SharedPodcast'
      required:
        - type_of
        - class_name
        - id
        - path
        - title
        - image_url
        - podcast
    ProfileImage:
      description: A profile image object
      type: object
      properties:
        type_of:
          description: Return profile_image
          type: string
        image_of:
          description: >-
            Determines the type of the profile image owner (user or
            organization)
          type: string
        profile_image:
          description: Profile image (640x640)
          type: string
        profile_image_90:
          description: Profile image (90x90)
          type: string
    SharedUser:
      description: The resource creator
      type: object
      properties:
        name:
          type: string
        username:
          type: string
        twitter_username:
          type: string
          nullable: true
        github_username:
          type: string
          nullable: true
        website_url:
          type: string
          format: url
          nullable: true
        profile_image:
          description: Profile image (640x640)
          type: string
        profile_image_90:
          description: Profile image (90x90)
          type: string
    SharedOrganization:
      description: The organization the resource belongs to
      type: object
      properties:
        name:
          type: string
        username:
          type: string
        slug:
          type: string
        profile_image:
          description: Profile image (640x640)
          type: string
          format: url
        profile_image_90:
          description: Profile image (90x90)
          type: string
          format: url
    User:
      description: The representation of a user
      type: object
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int64
        username:
          type: string
        name:
          type: string
        summary:
          type: string
          nullable: true
        twitter_username:
          type: string
        github_username:
          type: string
        website_url:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        joined_at:
          type: string
        profile_image:
          type: string
    SharedPodcast:
      description: The podcast that the resource belongs to
      type: object
      properties:
        title:
          type: string
        slug:
          type: string
        image_url:
          description: Podcast image url
          type: string
          format: url
    Comment:
      description: A Comment on an Article or Podcast Episode
      type: object
      properties:
        type_of:
          type: string
        id_code:
          type: string
        created_at:
          type: string
          format: date-time
        image_url:
          description: Podcast image url
          type: string
          format: url
    UserInviteParam:
      description: User invite parameters
      type: object
      properties:
        email:
          type: string
        name:
          type: string
          nullable: true
    DisplayAd:
      description: A Display Ad, aka Billboard, aka Widget
      type: object
      properties:
        id:
          type: integer
          description: The ID of the Display Ad
        name:
          type: string
          description: For internal use, helps distinguish ads from one another
        body_markdown:
          type: string
          description: The text (in markdown) of the ad (required)
        approved:
          type: boolean
          description: Ad must be both published and approved to be in rotation
        published:
          type: boolean
          description: Ad must be both published and approved to be in rotation
        organization_id:
          type: integer
          description: Identifies the organization to which the ad belongs
          nullable: true
        creator_id:
          type: integer
          description: Identifies the user who created the ad.
          nullable: true
        placement_area:
          type: string
          enum:
            - sidebar_left
            - sidebar_left_2
            - sidebar_right
            - feed_first
            - feed_second
            - feed_third
            - post_sidebar
            - post_comments
          description: Identifies which area of site layout the ad can appear in
        tag_list:
          type: string
          description: Tags on which this ad can be displayed (blank is all/any tags)
        article_exclude_ids:
          type: string
          nullable: true
          description: >-
            Articles this ad should *not* appear on (blank means no articles are
            disallowed, and this ad can appear next to any/all articles).
            Comma-separated list of integer Article IDs
        audience_segment_type:
          type: string
          enum:
            - testing
            - trusted
            - posted
            - no_posts_yet
            - dark_theme
            - light_theme
            - no_experience
            - experience1
            - experience2
            - experience3
            - experience4
            - experience5
          description: >-
            Specifies an group of users to show this ad to (only works with
            logged-in users)
        display_to:
          type: string
          enum:
            - all
            - logged_in
            - logged_out
          default: all
          description: Potentially limits visitors to whom the ad is visible
        type_of:
          type: string
          enum:
            - in_house
            - community
            - external
          default: in_house
          description: >
            Types of the billboards:

            in_house (created by admins),

            community (created by an entity, appears on entity's content),

            external ( created by an entity, or a non-entity, can appear
            everywhere)
      required:
        - name
        - body_markdown
        - placement_area
