openapi: 3.0.3
servers:
  - description: Production server
    url: https://dev.to/api
info:
  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.
  title: Forem API V1
  version: 1.0.0
  x-apisguru-categories:
    - social
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/forem/forem/main/swagger/v1/api_v1.json
      version: "3.0"
  x-providerName: dev.to
security:
  - api-key: []
paths:
  /api/admin/users:
    post:
      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: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserInviteParam"
      responses:
        "200":
          description: Successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
        "422":
          content:
            application/json:
              example:
                error: "param is missing or the value is empty: email"
                status: 422
          description: Unprocessable Entity
      summary: Invite a User
      tags:
        - users
  /api/articles:
    get:
      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"
        - 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`.
          example: discuss
          in: query
          name: tag
          required: false
          schema:
            type: string
        - description: |-
            Using this parameter will retrieve articles with any of the comma-separated tags.
            Articles will be ordered by descending popularity.
          example: javascript, css
          in: query
          name: tags
          required: false
          schema:
            type: string
        - description: |-
            Using this parameter will retrieve articles that do _not_ contain _any_
            of comma-separated tags. Articles will be ordered by descending popularity.
          example: node, java
          in: query
          name: tags_exclude
          required: false
          schema:
            type: string
        - 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`.
          example: ben
          in: query
          name: username
          required: false
          schema:
            type: string
        - 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`.
          example: fresh
          in: query
          name: state
          required: false
          schema:
            enum:
              - fresh
              - rising
              - all
            type: string
        - 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`.
          example: 2
          in: query
          name: top
          required: false
          schema:
            format: int32
            minimum: 1
            type: integer
        - description: |-
            Adding this will allow the client to return the list of articles
            belonging to the requested collection, ordered by ascending publication date.
          example: 99
          in: query
          name: collection_id
          required: false
          schema:
            format: int32
            type: integer
      responses:
        "200":
          content:
            application/json:
              example:
                - canonical_url: http://localhost:3000/username387/ah-wilderness175-1gok
                  collection_id: null
                  comments_count: 0
                  cover_image: http://localhost:3000/assets/34-d27f3a4a9f6f1f373003c74b31749764691f510b2a18b55039478583864a067e.png
                  created_at: 2023-04-07T11:16:58Z
                  crossposted_at: null
                  description: Thundercats iphone mumblecore pop-up cray dreamcatcher typewriter. 3 wolf moon hoodie bitters...
                  edited_at: null
                  flare_tag:
                    bg_color_hex: "#000000"
                    name: discuss
                    text_color_hex: "#ffffff"
                  id: 791
                  last_comment_at: 2023-04-07T11:16:58Z
                  organization:
                    name: Rogahn Group
                    profile_image: /uploads/organization/profile_image/326/438cc370-6426-4da7-bec2-8ec0759cd1d7.png
                    profile_image_90: /uploads/organization/profile_image/326/438cc370-6426-4da7-bec2-8ec0759cd1d7.png
                    slug: org70
                    username: org70
                  path: /username387/ah-wilderness175-1gok
                  positive_reactions_count: 0
                  public_reactions_count: 0
                  published_at: 2023-04-07T11:16:58Z
                  published_timestamp: 2023-04-07T11:16:58Z
                  readable_publish_date: Apr 7
                  reading_time_minutes: 1
                  slug: ah-wilderness175-1gok
                  social_image: http://localhost:3000/assets/34-d27f3a4a9f6f1f373003c74b31749764691f510b2a18b55039478583864a067e.png
                  tag_list:
                    - discuss
                  tags: discuss
                  title: Ah, Wilderness!175
                  type_of: article
                  url: http://localhost:3000/username387/ah-wilderness175-1gok
                  user:
                    github_username: github387
                    name: Arden "Vera" \:/ Gorczany
                    profile_image: /uploads/user/profile_image/1826/f6365991-cba0-43a1-914e-1c7eddb7618b.jpeg
                    profile_image_90: /uploads/user/profile_image/1826/f6365991-cba0-43a1-914e-1c7eddb7618b.jpeg
                    twitter_username: twitter387
                    user_id: 1826
                    username: username387
                    website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: A List of Articles
      security: []
      summary: Published articles
      tags:
        - articles
    post:
      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: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Article"
      responses:
        "201":
          content:
            application/json:
              example:
                body_html: |+
                  <p><strong>New</strong> body for the article</p>

                body_markdown: "**New** body for the article"
                canonical_url: https://dev.to/fdocr/headless-chrome-dual-mode-tests-for-ruby-on-rails-4p6g
                collection_id: 33
                comments_count: 0
                cover_image: https://thepracticaldev.s3.amazonaws.com/i/5wfo25724gzgk5e5j50g.jpg
                created_at: 2023-04-07T11:16:58Z
                crossposted_at: null
                description: New post example
                edited_at: null
                id: 788
                last_comment_at: 2023-04-07T11:16:58Z
                path: /username383/new-article-4l9a
                positive_reactions_count: 0
                public_reactions_count: 0
                published_at: 2023-04-07T11:16:58Z
                published_timestamp: 2023-04-07T11:16:58Z
                readable_publish_date: Apr 7
                reading_time_minutes: 1
                slug: new-article-4l9a
                social_image: https://thepracticaldev.s3.amazonaws.com/i/5wfo25724gzgk5e5j50g.jpg
                tag_list: ""
                tags: []
                title: New article
                type_of: article
                url: http://localhost:3000/username383/new-article-4l9a
                user:
                  github_username: github383
                  name: Felicita "Doug" \:/ Conroy
                  profile_image: /uploads/user/profile_image/1822/9d77b0c7-c1cd-4661-86aa-fabe8b5634bd.jpeg
                  profile_image_90: /uploads/user/profile_image/1822/9d77b0c7-c1cd-4661-86aa-fabe8b5634bd.jpeg
                  twitter_username: twitter383
                  user_id: 1822
                  username: username383
                  website_url: null
          description: An Article
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
        "422":
          content:
            application/json:
              example:
                error: "param is missing or the value is empty: article"
                status: 422
          description: Unprocessable Entity
      summary: Publish article
      tags:
        - articles
  /api/articles/latest:
    get:
      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":
          content:
            application/json:
              example:
                - canonical_url: http://localhost:3000/username390/a-summer-bird-cage178-48nc
                  collection_id: null
                  comments_count: 0
                  cover_image: http://localhost:3000/assets/23-33ea5a2b5af3dc15b9ed90de0b850f67e2390eaec3361d6687d3b9750c699f84.png
                  created_at: 2023-04-07T11:16:58Z
                  crossposted_at: null
                  description: Portland waistcoat fingerstache vinyl butcher. Tumblr kale chips mixtape.  Direct trade stumptown vhs...
                  edited_at: null
                  flare_tag:
                    bg_color_hex: "#000000"
                    name: discuss
                    text_color_hex: "#ffffff"
                  id: 794
                  last_comment_at: 2023-04-07T11:16:58Z
                  path: /username390/a-summer-bird-cage178-48nc
                  positive_reactions_count: 0
                  public_reactions_count: 0
                  published_at: 2023-04-07T11:16:58Z
                  published_timestamp: 2023-04-07T11:16:58Z
                  readable_publish_date: Apr 7
                  reading_time_minutes: 1
                  slug: a-summer-bird-cage178-48nc
                  social_image: http://localhost:3000/assets/23-33ea5a2b5af3dc15b9ed90de0b850f67e2390eaec3361d6687d3b9750c699f84.png
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  title: A Summer Bird-Cage178
                  type_of: article
                  url: http://localhost:3000/username390/a-summer-bird-cage178-48nc
                  user:
                    github_username: github390
                    name: Florencio "Lorie" \:/ Heidenreich
                    profile_image: /uploads/user/profile_image/1829/425917eb-2b42-4fa5-ad6c-1c28e0758af6.jpeg
                    profile_image_90: /uploads/user/profile_image/1829/425917eb-2b42-4fa5-ad6c-1c28e0758af6.jpeg
                    twitter_username: twitter390
                    user_id: 1829
                    username: username390
                    website_url: null
                - canonical_url: http://localhost:3000/username389/the-road-less-traveled177-3pbl
                  collection_id: null
                  comments_count: 0
                  cover_image: http://localhost:3000/assets/4-dcfcc4d8dd259bc0751c2de24b1cf244b181c789934368ca1cb471f0944b695d.png
                  created_at: 2023-04-07T11:16:58Z
                  crossposted_at: null
                  description: Kale chips lo-fi godard. Knausgaard meggings chillwave gluten-free keytar etsy. Diy phlogiston godard...
                  edited_at: null
                  flare_tag:
                    bg_color_hex: "#000000"
                    name: discuss
                    text_color_hex: "#ffffff"
                  id: 793
                  last_comment_at: 2023-04-07T11:16:58Z
                  path: /username389/the-road-less-traveled177-3pbl
                  positive_reactions_count: 0
                  public_reactions_count: 0
                  published_at: 2023-04-07T11:16:58Z
                  published_timestamp: 2023-04-07T11:16:58Z
                  readable_publish_date: Apr 7
                  reading_time_minutes: 1
                  slug: the-road-less-traveled177-3pbl
                  social_image: http://localhost:3000/assets/4-dcfcc4d8dd259bc0751c2de24b1cf244b181c789934368ca1cb471f0944b695d.png
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  title: The Road Less Traveled177
                  type_of: article
                  url: http://localhost:3000/username389/the-road-less-traveled177-3pbl
                  user:
                    github_username: github389
                    name: Mark "Gina" \:/ Grimes
                    profile_image: /uploads/user/profile_image/1828/c3970f90-a350-41e1-b563-9d7feea34839.jpeg
                    profile_image_90: /uploads/user/profile_image/1828/c3970f90-a350-41e1-b563-9d7feea34839.jpeg
                    twitter_username: twitter389
                    user_id: 1828
                    username: username389
                    website_url: null
                - canonical_url: http://localhost:3000/username388/where-angels-fear-to-tread176-4e3g
                  collection_id: null
                  comments_count: 0
                  cover_image: http://localhost:3000/assets/14-5e64731cc7cd63e3b689647d9d3c3e4e1d907690c716d3dd1e356466726a2c2d.png
                  created_at: 2023-04-07T11:16:58Z
                  crossposted_at: null
                  description: Cronut forage normcore +1. Readymade whatever typewriter keffiyeh etsy sustainable. Twee asymmetrical...
                  edited_at: null
                  flare_tag:
                    bg_color_hex: "#000000"
                    name: discuss
                    text_color_hex: "#ffffff"
                  id: 792
                  last_comment_at: 2023-04-07T11:16:58Z
                  path: /username388/where-angels-fear-to-tread176-4e3g
                  positive_reactions_count: 0
                  public_reactions_count: 0
                  published_at: 2023-04-07T11:16:58Z
                  published_timestamp: 2023-04-07T11:16:58Z
                  readable_publish_date: Apr 7
                  reading_time_minutes: 1
                  slug: where-angels-fear-to-tread176-4e3g
                  social_image: http://localhost:3000/assets/14-5e64731cc7cd63e3b689647d9d3c3e4e1d907690c716d3dd1e356466726a2c2d.png
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  title: Where Angels Fear to Tread176
                  type_of: article
                  url: http://localhost:3000/username388/where-angels-fear-to-tread176-4e3g
                  user:
                    github_username: github388
                    name: Olimpia "Claudette" \:/ Hyatt
                    profile_image: /uploads/user/profile_image/1827/48a841be-542f-48ba-a84f-b12521bddc1a.jpeg
                    profile_image_90: /uploads/user/profile_image/1827/48a841be-542f-48ba-a84f-b12521bddc1a.jpeg
                    twitter_username: twitter388
                    user_id: 1827
                    username: username388
                    website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: A List of Articles
      security: []
      summary: Published articles sorted by published date
      tags:
        - articles
  /api/articles/me:
    get:
      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":
          content:
            application/json:
              example: []
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: A List of the authenticated user's Articles
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
      summary: User's articles
      tags:
        - articles
        - users
  /api/articles/me/all:
    get:
      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":
          content:
            application/json:
              example: []
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: A List of the authenticated user's Articles
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
      summary: User's all articles
      tags:
        - articles
        - users
  /api/articles/me/published:
    get:
      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":
          content:
            application/json:
              example: []
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: A List of the authenticated user's Articles
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
      summary: User's published articles
      tags:
        - articles
        - users
  /api/articles/me/unpublished:
    get:
      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":
          content:
            application/json:
              example: []
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: A List of the authenticated user's Articles
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
      summary: User's unpublished articles
      tags:
        - articles
        - users
  "/api/articles/{id}":
    get:
      description: This endpoint allows the client to retrieve a single published article given its `id`.
      operationId: getArticleById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: |+
                  <p>Asymmetrical knausgaard bicycle rights. Intelligentsia mumblecore 8-bit celiac. You probably haven't heard of them +1 marfa. Semiotics godard kitsch shabby chic hashtag knausgaard normcore cornhole.</p>

                  <p>Typewriter bespoke farm-to-table gastropub. Helvetica fanny pack etsy cardigan typewriter kitsch aesthetic.</p>

                body_markdown: |+
                  ---
                  title: The Moving Toyshop179
                  published: true
                  tags: discuss
                  date: 
                  series: 
                  canonical_url: 

                  ---

                  Asymmetrical knausgaard bicycle rights. Intelligentsia mumblecore 8-bit celiac. You probably haven't heard of them +1 marfa. Semiotics godard kitsch shabby chic hashtag knausgaard normcore cornhole.


                  Typewriter bespoke farm-to-table gastropub. Helvetica fanny pack etsy cardigan typewriter kitsch aesthetic.

                canonical_url: http://localhost:3000/username391/the-moving-toyshop179-10fb
                collection_id: null
                comments_count: 0
                cover_image: http://localhost:3000/assets/26-90c7a1dfb33e271f477a60763fa64d842858635cdd7a508d0ffa2df59ced9d1d.png
                created_at: 2023-04-07T11:16:59Z
                crossposted_at: null
                description: Asymmetrical knausgaard bicycle rights. Intelligentsia mumblecore 8-bit celiac. You probably haven't...
                edited_at: null
                flare_tag:
                  bg_color_hex: "#000000"
                  name: discuss
                  text_color_hex: "#ffffff"
                id: 795
                last_comment_at: 2023-04-07T11:16:59Z
                path: /username391/the-moving-toyshop179-10fb
                positive_reactions_count: 0
                public_reactions_count: 0
                published_at: 2023-04-07T11:16:59Z
                published_timestamp: 2023-04-07T11:16:59Z
                readable_publish_date: Apr 7
                reading_time_minutes: 1
                slug: the-moving-toyshop179-10fb
                social_image: http://localhost:3000/assets/26-90c7a1dfb33e271f477a60763fa64d842858635cdd7a508d0ffa2df59ced9d1d.png
                tag_list: discuss
                tags:
                  - discuss
                title: The Moving Toyshop179
                type_of: article
                url: http://localhost:3000/username391/the-moving-toyshop179-10fb
                user:
                  github_username: github391
                  name: Mitchel "Fernando" \:/ Dibbert
                  profile_image: /uploads/user/profile_image/1830/e8182814-666a-48bb-bdb7-208f1b9755ab.jpeg
                  profile_image_90: /uploads/user/profile_image/1830/e8182814-666a-48bb-bdb7-208f1b9755ab.jpeg
                  twitter_username: twitter391
                  user_id: 1830
                  username: username391
                  website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: object
          description: An Article
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Article Not Found
      security: []
      summary: Published article by id
      tags:
        - articles
    put:
      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:
        - description: The ID of the user to unpublish.
          example: 123
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Article"
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: |+
                  <p><strong>New</strong> body for the article</p>

                body_markdown: "**New** body for the article"
                canonical_url: http://localhost:3000/username392/the-millstone180-m1p
                collection_id: null
                comments_count: 0
                cover_image: http://localhost:3000/assets/25-b4bb206b62bee552880440f638594e41dcd649ed9bd821af2e8dfc671d1d6813.png
                created_at: 2023-04-07T11:16:59Z
                crossposted_at: null
                description: Meggings schlitz letterpress. Diy loko polaroid literally. Narwhal pinterest flexitarian...
                edited_at: 2023-04-07T11:16:59Z
                id: 796
                last_comment_at: 2023-04-07T11:16:59Z
                path: /username392/the-millstone180-m1p
                positive_reactions_count: 0
                public_reactions_count: 0
                published_at: 2023-04-07T11:16:59Z
                published_timestamp: 2023-04-07T11:16:59Z
                readable_publish_date: Apr 7
                reading_time_minutes: 1
                slug: the-millstone180-m1p
                social_image: http://localhost:3000/assets/25-b4bb206b62bee552880440f638594e41dcd649ed9bd821af2e8dfc671d1d6813.png
                tag_list: ""
                tags: []
                title: The Millstone180
                type_of: article
                url: http://localhost:3000/username392/the-millstone180-m1p
                user:
                  github_username: github392
                  name: Taylor "Boyd" \:/ Kilback
                  profile_image: /uploads/user/profile_image/1831/d54b1eb6-ab6d-493f-8153-8478f95ed9a6.jpeg
                  profile_image_90: /uploads/user/profile_image/1831/d54b1eb6-ab6d-493f-8153-8478f95ed9a6.jpeg
                  twitter_username: twitter392
                  user_id: 1831
                  username: username392
                  website_url: null
          description: An Article
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Article Not Found
        "422":
          content:
            application/json:
              example:
                error: "param is missing or the value is empty: article"
                status: 422
          description: Unprocessable Entity
      summary: Update an article by id
      tags:
        - articles
  "/api/articles/{id}/unpublish":
    put:
      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:
        - description: The ID of the article to unpublish.
          example: 1
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
        - description: Content for the note that's created along with unpublishing
          example: Admin requested unpublishing all articles via API
          in: query
          name: note
          required: false
          schema:
            type: string
      responses:
        "204":
          description: Article successfully unpublished
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Article Not Found
      summary: Unpublish an article
      tags:
        - articles
  "/api/articles/{username}/{slug}":
    get:
      description: This endpoint allows the client to retrieve a single published article given its `path`.
      operationId: getArticleByPath
      parameters:
        - in: path
          name: username
          required: true
          schema:
            type: string
        - in: path
          name: slug
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: |+
                  <p>Single-origin coffee brooklyn raw denim goth. Deep v mustache gentrify pabst small batch locavore occupy.</p>

                  <p>Kinfolk ramps deep v small batch. Scenester lumbersexual selvage fashion axe offal synth. Pork belly cornhole cleanse next level letterpress fixie.</p>

                body_markdown: |+
                  ---
                  title: I Will Fear No Evil183
                  published: true
                  tags: discuss
                  date: 
                  series: 
                  canonical_url: 

                  ---

                  Single-origin coffee brooklyn raw denim goth. Deep v mustache gentrify pabst small batch locavore occupy.


                  Kinfolk ramps deep v small batch. Scenester lumbersexual selvage fashion axe offal synth. Pork belly cornhole cleanse next level letterpress fixie.

                canonical_url: http://localhost:3000/username396/i-will-fear-no-evil183-3e61
                collection_id: null
                comments_count: 0
                cover_image: http://localhost:3000/assets/18-0c8db7667732647d3000787a9481d38dc0dbe1b8ebc0b097db816f8db8cd097a.png
                created_at: 2023-04-07T11:16:59Z
                crossposted_at: null
                description: Single-origin coffee brooklyn raw denim goth. Deep v mustache gentrify pabst small batch locavore...
                edited_at: null
                flare_tag:
                  bg_color_hex: "#000000"
                  name: discuss
                  text_color_hex: "#ffffff"
                id: 799
                last_comment_at: 2023-04-07T11:16:59Z
                path: /username396/i-will-fear-no-evil183-3e61
                positive_reactions_count: 0
                public_reactions_count: 0
                published_at: 2023-04-07T11:16:59Z
                published_timestamp: 2023-04-07T11:16:59Z
                readable_publish_date: Apr 7
                reading_time_minutes: 1
                slug: i-will-fear-no-evil183-3e61
                social_image: http://localhost:3000/assets/18-0c8db7667732647d3000787a9481d38dc0dbe1b8ebc0b097db816f8db8cd097a.png
                tag_list: discuss
                tags:
                  - discuss
                title: I Will Fear No Evil183
                type_of: article
                url: http://localhost:3000/username396/i-will-fear-no-evil183-3e61
                user:
                  github_username: github396
                  name: Inell "Peggy" \:/ Schoen
                  profile_image: /uploads/user/profile_image/1835/54bee5ff-3e71-4470-98a8-b9c9cd4156af.jpeg
                  profile_image_90: /uploads/user/profile_image/1835/54bee5ff-3e71-4470-98a8-b9c9cd4156af.jpeg
                  twitter_username: twitter396
                  user_id: 1835
                  username: username396
                  website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: object
          description: An Article
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Article Not Found
      security: []
      summary: Published article by path
      tags:
        - articles
  /api/comments:
    get:
      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:
        - description: Article identifier.
          example: "321"
          in: query
          name: a_id
          required: false
          schema:
            type: string
        - description: Podcast Episode identifier.
          example: "321"
          in: query
          name: p_id
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                - body_html: |+
                    <p>Lumbersexual green juice normcore fixie letterpress. Wayfarers stumptown hashtag bicycle rights biodiesel.</p>

                  children: []
                  created_at: 2023-04-07T11:17:00Z
                  id_code: h4
                  type_of: comment
                  user:
                    github_username: github410
                    name: Stacy "Lindsey" \:/ Hettinger
                    profile_image: /uploads/user/profile_image/1849/f7041c95-37d3-48e6-9aa6-54ed750fc2a5.jpeg
                    profile_image_90: /uploads/user/profile_image/1849/f7041c95-37d3-48e6-9aa6-54ed750fc2a5.jpeg
                    twitter_username: twitter410
                    user_id: 1849
                    username: username410
                    website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/Comment"
                type: array
          description: A List of Comments
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Resource Not Found
      security: []
      summary: Comments
      tags:
        - comments
  "/api/comments/{id}":
    get:
      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:
        - description: Comment identifier.
          example: "321"
          in: path
          name: id
          required: true
          schema:
            type: integer
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: |+
                  <p>Meh viral church-key cronut intelligentsia you probably haven't heard of them literally. Chambray taxidermy beard ennui gastropub. Cardigan keytar crucifix selvage vinegar.</p>

                children: []
                created_at: 2023-04-07T11:17:00Z
                id_code: h6
                type_of: comment
                user:
                  github_username: github414
                  name: Elise "Dede" \:/ Donnelly
                  profile_image: /uploads/user/profile_image/1853/c9595b8c-9d79-4e88-816a-25e36cf7bc11.jpeg
                  profile_image_90: /uploads/user/profile_image/1853/c9595b8c-9d79-4e88-816a-25e36cf7bc11.jpeg
                  twitter_username: twitter414
                  user_id: 1853
                  username: username414
                  website_url: null
          description: A List of the Comments
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Comment Not Found
      security: []
      summary: Comment by id
      tags:
        - comments
  /api/display_ads:
    get:
      description: This endpoint allows the client to retrieve a list of all display ads.
      responses:
        "200":
          content:
            application/json:
              example: []
              schema:
                items:
                  $ref: "#/components/schemas/DisplayAd"
                type: array
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
      summary: display ads
      tags:
        - display ads
    post:
      description: This endpoint allows the client to create a new display ad.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: "#/components/schemas/DisplayAd"
              type: object
      responses:
        "200":
          content:
            application/json:
              example:
                approved: true
                body_markdown: |-
                  # Hi, this is ad
                  Yep, it's an ad
                cached_tag_list: ""
                clicks_count: 0
                created_at: 2023-04-07T14:17:00.899+03:00
                creator_id: null
                display_to: all
                exclude_article_ids: ""
                id: 42
                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
                tag_list: ""
                type_of: in_house
                updated_at: 2023-04-07T14:17:00.899+03:00
              schema:
                items:
                  $ref: "#/components/schemas/DisplayAd"
                type: object
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
        "422":
          content:
            application/json:
              example:
                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: ""
                id: null
                impressions_count: 0
                name: Example Ad
                organization_id: null
                placement_area: moon
                processed_html: null
                published: true
                success_rate: 0
                tag_list: null
                type_of: in_house
                updated_at: null
          description: unprocessable
      summary: display ads
      tags:
        - display ads
  "/api/display_ads/{id}":
    get:
      description: This endpoint allows the client to retrieve a single display ad, via its id.
      parameters:
        - description: The ID of the display ad.
          example: 123
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              example:
                approved: false
                body_markdown: Hello _hey_ Hey hey 9
                cached_tag_list: ""
                clicks_count: 0
                created_at: 2023-04-07T14:17:01.032+03:00
                creator_id: null
                display_to: all
                exclude_article_ids: ""
                id: 43
                impressions_count: 0
                name: Display Ad 43
                organization_id: 327
                placement_area: sidebar_left
                processed_html: <p>Hello <em>hey</em> Hey hey 9</p>
                published: false
                success_rate: 0
                tag_list: ""
                type_of: in_house
                updated_at: 2023-04-07T14:17:01.035+03:00
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Unknown DisplayAd ID
      summary: display ad
      tags:
        - display ads
    put:
      description: This endpoint allows the client to update the attributes of a single display ad, via its id.
      parameters:
        - description: The ID of the display ad.
          example: 123
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: "#/components/schemas/DisplayAd"
              type: object
      responses:
        "200":
          content:
            application/json:
              example:
                approved: false
                body_markdown: Hello _hey_ Hey hey 10
                cached_tag_list: ""
                clicks_count: 0
                created_at: 2023-04-07T14:17:01.192+03:00
                creator_id: null
                display_to: all
                exclude_article_ids: ""
                id: 44
                impressions_count: 0
                name: Display Ad 44
                organization_id: 328
                placement_area: sidebar_left
                processed_html: <p>Hello <em>hey</em> Hey hey 10</p>
                published: false
                success_rate: 0
                tag_list: ""
                type_of: in_house
                updated_at: 2023-04-07T14:17:01.194+03:00
              schema:
                items:
                  $ref: "#/components/schemas/DisplayAd"
                type: object
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: not found
      summary: display ads
      tags:
        - display ads
  "/api/display_ads/{id}/unpublish":
    put:
      description: This endpoint allows the client to remove a display ad from rotation by un-publishing it.
      parameters:
        - description: The ID of the display ad to unpublish.
          example: 123
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      responses:
        "204":
          description: no content
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: not found
      summary: unpublish
      tags:
        - display ads
  /api/followers/users:
    get:
      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"
        - 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.
          example: created_at
          in: query
          name: sort
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                - created_at: 2023-04-07T11:17:01Z
                  id: 48
                  name: Alicia "Thurman" \:/ Reinger
                  path: /username435
                  profile_image: /uploads/user/profile_image/1874/07e583fb-d055-4559-add1-9e27479d293c.jpeg
                  type_of: user_follower
                  user_id: 1874
                  username: username435
                - created_at: 2023-04-07T11:17:01Z
                  id: 47
                  name: Haley "Jackeline" \:/ Huel
                  path: /username433
                  profile_image: /uploads/user/profile_image/1872/87cf4eca-22fb-4503-8ab1-da342d6af46e.jpeg
                  type_of: user_follower
                  user_id: 1872
                  username: username433
              schema:
                items:
                  description: A follower
                  properties:
                    id:
                      format: int32
                      type: integer
                    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
                    type_of:
                      description: user_follower by default
                      type: string
                    user_id:
                      description: The follower's user id
                      format: int32
                      type: integer
                  type: object
                type: array
          description: A List of followers
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
      summary: Followers
      tags:
        - followers
  /api/follows/tags:
    get:
      description: This endpoint allows the client to retrieve a list of the tags they follow.
      operationId: getFollowedTags
      responses:
        "200":
          content:
            application/json:
              example:
                - id: 1532
                  name: tag3
                  points: 1
                - id: 1533
                  name: tag4
                  points: 1
              schema:
                items:
                  $ref: "#/components/schemas/FollowedTag"
                type: array
          description: A List of followed tags
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
      summary: Followed Tags
      tags:
        - followed_tags
        - tags
  "/api/organizations/{username}":
    get:
      description: This endpoint allows the client to retrieve a single organization by their username
      operationId: getOrganization
      parameters:
        - in: path
          name: username
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                github_username: org4848
                id: 333
                joined_at: 2023-04-07T11:17:01Z
                location: null
                name: Lockman, Feeney and Maggio
                profile_image: /uploads/organization/profile_image/333/92285ef2-5081-4520-8ef5-942502e40ffa.png
                story: null
                summary: Retro pork belly wes anderson. Poutine meggings sriracha marfa. Distillery put a bird on it stumptown beard mixtape.
                tag_line: null
                tech_stack: null
                twitter_username: org7429
                type_of: organization
                url: http://kozey-turcotte.biz/deborah_corwin
                username: org77
              schema:
                items:
                  $ref: "#/components/schemas/Organization"
                type: object
          description: An Organization
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Not Found
      security: []
      summary: An organization
      tags:
        - organizations
  "/api/organizations/{username}/articles":
    get:
      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:
        - in: path
          name: username
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/perPageParam30to1000"
      responses:
        "200":
          content:
            application/json:
              example:
                - canonical_url: http://localhost:3000/org81/cabbages-and-kings195-2pag
                  collection_id: null
                  comments_count: 0
                  cover_image: http://localhost:3000/assets/4-dcfcc4d8dd259bc0751c2de24b1cf244b181c789934368ca1cb471f0944b695d.png
                  created_at: 2023-04-07T11:17:02Z
                  crossposted_at: null
                  description: Kitsch crucifix pop-up iphone gentrify taxidermy craft beer. Photo booth you probably haven't heard...
                  edited_at: null
                  id: 811
                  last_comment_at: 2023-04-07T11:17:02Z
                  organization:
                    name: Schmidt-Dickinson
                    profile_image: /uploads/organization/profile_image/337/8c9a5f12-5897-45c4-99d4-7e1e8513b7e0.png
                    profile_image_90: /uploads/organization/profile_image/337/8c9a5f12-5897-45c4-99d4-7e1e8513b7e0.png
                    slug: org81
                    username: org81
                  path: /org81/cabbages-and-kings195-2pag
                  positive_reactions_count: 0
                  public_reactions_count: 0
                  published_at: 2023-04-07T11:17:02Z
                  published_timestamp: 2023-04-07T11:17:02Z
                  readable_publish_date: Apr 7
                  reading_time_minutes: 1
                  slug: cabbages-and-kings195-2pag
                  social_image: http://localhost:3000/assets/4-dcfcc4d8dd259bc0751c2de24b1cf244b181c789934368ca1cb471f0944b695d.png
                  tag_list:
                    - javascript
                    - html
                    - discuss
                  tags: javascript, html, discuss
                  title: Cabbages and Kings195
                  type_of: article
                  url: http://localhost:3000/org81/cabbages-and-kings195-2pag
                  user:
                    github_username: github453
                    name: Keenan "Erick" \:/ Watsica
                    profile_image: /uploads/user/profile_image/1892/f65f08fc-8dac-4a7f-b715-f54671f3b25b.jpeg
                    profile_image_90: /uploads/user/profile_image/1892/f65f08fc-8dac-4a7f-b715-f54671f3b25b.jpeg
                    twitter_username: twitter453
                    user_id: 1892
                    username: username453
                    website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: An Organization's Articles
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Not Found
      security: []
      summary: Organization's Articles
      tags:
        - organizations
        - articles
  "/api/organizations/{username}/users":
    get:
      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:
        - in: path
          name: username
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/perPageParam30to1000"
      responses:
        "200":
          content:
            application/json:
              example:
                - github_username: github445
                  id: 1884
                  joined_at: Apr  7, 2023
                  location: null
                  name: Gena "Buster" \:/ Towne
                  profile_image: /uploads/user/profile_image/1884/7010628d-50e3-4cd1-a6c3-22dd885e7747.jpeg
                  summary: null
                  twitter_username: twitter445
                  type_of: user
                  username: username445
                  website_url: null
                - github_username: github446
                  id: 1885
                  joined_at: Apr  7, 2023
                  location: null
                  name: Ernest "Marie" \:/ Zboncak
                  profile_image: /uploads/user/profile_image/1885/3620dd35-ac62-424a-9a55-d1edcf557703.jpeg
                  summary: null
                  twitter_username: twitter446
                  type_of: user
                  username: username446
                  website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/User"
                type: array
          description: An Organization's users
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Not Found
      security: []
      summary: Organization's users
      tags:
        - organizations
        - users
  /api/pages:
    get:
      description: This endpoint allows the client to retrieve details for all Page objects.
      responses:
        "200":
          content:
            application/json:
              example:
                - body_html: null
                  body_json: null
                  body_markdown: Quod ullam et velit.
                  description: Nesciunt nulla qui quo.
                  id: 51
                  is_top_level_path: false
                  landing_page: false
                  processed_html: |+
                    <p>Quod ullam et velit.</p>

                  slug: shock-cruelty
                  social_image:
                    url: null
                  template: contained
                  title: Some Buried Caesar
              schema:
                items:
                  $ref: "#/components/schemas/Page"
                type: array
          description: successful
      security: []
      summary: show details for all pages
      tags:
        - pages
    post:
      description: This endpoint allows the client to create a new page.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              properties:
                body_json:
                  description: For JSON pages, the JSON body
                  type: string
                body_markdown:
                  description: The text (in markdown) of the ad (required)
                  type: string
                description:
                  description: For internal use, helps similar pages from one another
                  type: string
                is_top_level_path:
                  description: If true, the page is available at '/{slug}' instead of '/page/{slug}', use with caution
                  type: boolean
                slug:
                  description: Used to link to this page in URLs, must be unique and URL-safe
                  type: string
                template:
                  default: contained
                  description: Controls what kind of layout the page is rendered in
                  enum:
                    - contained
                    - full_within_layout
                    - nav_bar_included
                    - json
                  type: string
                title:
                  description: Title of the page
                  type: string
              type: object
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: null
                body_json: null
                body_markdown: |-
                  # Hi, this is a New Page
                  Yep, it's an a new page
                description: a new page
                id: 53
                is_top_level_path: false
                landing_page: false
                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>

                slug: example1
                social_image:
                  url: null
                template: contained
                title: Example Page
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
        "422":
          content:
            application/json:
              example:
                body_html: null
                body_json: null
                body_markdown: |-
                  # Hi, this is a New Page
                  Yep, it's an a new page
                description: a new page
                id: null
                is_top_level_path: false
                landing_page: false
                processed_html: null
                slug: example1
                social_image:
                  url: null
                template: moon
                title: Example Page
          description: unprocessable
      summary: pages
      tags:
        - pages
  "/api/pages/{id}":
    delete:
      description: This endpoint allows the client to delete a single Page object, specified by ID.
      parameters:
        - description: The ID of the page.
          example: 1
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: null
                body_json: null
                body_markdown: Et omnis odio dolorum.
                description: Quibusdam eos est quae.
                id: 60
                is_top_level_path: false
                landing_page: false
                processed_html: |+
                  <p>Et omnis odio dolorum.</p>

                slug: drill_cruelty
                social_image:
                  url: null
                template: contained
                title: Frequent Hearses
              schema:
                $ref: "#/components/schemas/Page"
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
        "422":
          content:
            application/json:
              example:
                __expired: false
                __sending_message: null
                doubled_module:
                  const_name: Page
                  object: Page
                name: null
          description: unprocessable
      summary: remove a page
      tags:
        - pages
    get:
      description: This endpoint allows the client to retrieve details for a single Page object, specified by ID.
      parameters:
        - description: The ID of the page.
          example: 1
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: null
                body_json: null
                body_markdown: Similique delectus nemo repudiandae.
                description: Eum laborum consectetur dolores.
                id: 56
                is_top_level_path: false
                landing_page: false
                processed_html: |+
                  <p>Similique delectus nemo repudiandae.</p>

                slug: plain-compete
                social_image:
                  url: null
                template: contained
                title: This Lime Tree Bower
              schema:
                $ref: "#/components/schemas/Page"
          description: successful
      security: []
      summary: show details for a page
      tags:
        - pages
    put:
      description: This endpoint allows the client to retrieve details for a single Page object, specified by ID.
      parameters:
        - description: The ID of the page.
          example: 1
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Page"
      responses:
        "200":
          content:
            application/json:
              example:
                body_html: null
                body_json: null
                body_markdown: Voluptatem quia est libero.
                description: Doloremque facere incidunt error.
                id: 57
                is_top_level_path: false
                landing_page: false
                processed_html: |+
                  <p>Voluptatem quia est libero.</p>

                slug: condition-exhibition
                social_image:
                  url: null
                template: contained
                title: New Title
              schema:
                $ref: "#/components/schemas/Page"
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
        "422":
          content:
            application/json:
              example:
                body_html: null
                body_json: null
                body_markdown: Dolorem aperiam odio voluptas.
                description: Consequuntur optio harum magni.
                id: 59
                is_top_level_path: false
                landing_page: false
                processed_html: |+
                  <p>Aut excepturi repellat qui.</p>

                slug: satisfaction-ample
                social_image:
                  url: null
                template: moon
                title: What's Become of Waring
          description: unprocessable
      summary: update details for a page
      tags:
        - pages
  /api/podcast_episodes:
    get:
      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"
        - description: Using this parameter will retrieve episodes belonging to a specific podcast.
          example: codenewbie
          in: query
          name: username
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                - class_name: PodcastEpisode
                  id: 48
                  image_url: /uploads/podcast/image/38/79232785-1862-41ab-bceb-31132ce68e5b.jpeg
                  path: /codenewbie/slug-4
                  podcast:
                    image_url: /uploads/podcast/image/38/79232785-1862-41ab-bceb-31132ce68e5b.jpeg
                    slug: codenewbie
                    title: Bourbon County Stout
                  title: "7"
                  type_of: podcast_episodes
              schema:
                items:
                  $ref: "#/components/schemas/PodcastEpisodeIndex"
                type: array
          description: A List of Podcast episodes filtered by username
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Unknown Podcast username
      security: []
      summary: Podcast Episodes
      tags:
        - podcast_episodes
  "/api/profile_images/{username}":
    get:
      description: |-
        This endpoint allows the client to retrieve a user or organization profile image information by its
                corresponding username.
      operationId: getProfileImage
      parameters:
        - description: The parameter is the username of the user or the username of the organization.
          example: janedoe
          in: path
          name: username
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                image_of: user
                profile_image: /uploads/user/profile_image/1907/7a4c1f9f-f3ce-4008-990f-740c2bab0b40.jpeg
                profile_image_90: /uploads/user/profile_image/1907/7a4c1f9f-f3ce-4008-990f-740c2bab0b40.jpeg
                type_of: profile_image
              schema:
                items:
                  $ref: "#/components/schemas/ProfileImage"
                type: object
          description: An object containing profile image details
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Resource Not Found
      summary: A Users or organizations profile image
      tags:
        - profile images
  /api/reactions:
    post:
      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:
        - in: query
          name: category
          required: true
          schema:
            enum:
              - like
              - unicorn
              - exploding_head
              - raised_hands
              - fire
            type: string
        - in: query
          name: reactable_id
          required: true
          schema:
            format: int32
            type: integer
        - in: query
          name: reactable_type
          required: true
          schema:
            enum:
              - Comment
              - Article
              - User
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                category: like
                id: 31
                reactable_id: 815
                reactable_type: Article
                result: none
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
      summary: create reaction
      tags:
        - reactions
  /api/reactions/toggle:
    post:
      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:
        - in: query
          name: category
          required: true
          schema:
            enum:
              - like
              - unicorn
              - exploding_head
              - raised_hands
              - fire
            type: string
        - in: query
          name: reactable_id
          required: true
          schema:
            format: int32
            type: integer
        - in: query
          name: reactable_type
          required: true
          schema:
            enum:
              - Comment
              - Article
              - User
            type: string
      responses:
        "200":
          content:
            application/json:
              example:
                category: like
                id: 29
                reactable_id: 813
                reactable_type: Article
                result: create
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: unauthorized
      summary: toggle reaction
      tags:
        - reactions
  /api/readinglist:
    get:
      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":
          content:
            application/json:
              example: []
              schema:
                items:
                  $ref: "#/components/schemas/ArticleIndex"
                type: array
          description: A list of articles in the users readinglist
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
      summary: Readinglist
      tags:
        - readinglist
  /api/tags:
    get:
      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":
          content:
            application/json:
              example:
                - bg_color_hex: null
                  id: 1566
                  name: tag7
                  text_color_hex: null
                - bg_color_hex: null
                  id: 1565
                  name: tag6
                  text_color_hex: null
                - bg_color_hex: null
                  id: 1564
                  name: tag5
                  text_color_hex: null
              schema:
                items:
                  $ref: "#/components/schemas/Tag"
                type: array
          description: A List of all tags
      security: []
      summary: Tags
      tags:
        - tags
  /api/users/me:
    get:
      description: This endpoint allows the client to retrieve information about the authenticated user
      operationId: getUserMe
      responses:
        "200":
          content:
            application/json:
              example:
                github_username: github480
                id: 1919
                joined_at: Apr  7, 2023
                location: null
                name: Joi "Chanda" \:/ Ruecker
                profile_image: /uploads/user/profile_image/1919/630d6fe8-eea1-4815-9f97-41e94bdeb31e.jpeg
                summary: null
                twitter_username: twitter480
                type_of: user
                username: username480
                website_url: null
              schema:
                items:
                  $ref: "#/components/schemas/User"
                type: object
          description: successful
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
      summary: The authenticated user
      tags:
        - users
  "/api/users/{id}":
    get:
      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:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/User"
                type: object
          description: successful
      summary: A User
      tags:
        - users
  "/api/users/{id}/suspend":
    put:
      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:
        - description: The ID of the user to suspend.
          example: 1
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      responses:
        "204":
          description: User successfully unpublished
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Unknown User ID
      summary: Suspend a User
      tags:
        - users
  "/api/users/{id}/unpublish":
    put:
      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:
        - description: The ID of the user to unpublish.
          example: 1
          in: path
          name: id
          required: true
          schema:
            format: int32
            minimum: 1
            type: integer
      responses:
        "204":
          description: User's articles and comments successfully unpublished
        "401":
          content:
            application/json:
              example:
                error: unauthorized
                status: 401
          description: Unauthorized
        "404":
          content:
            application/json:
              example:
                error: not found
                status: 404
          description: Unknown User ID (still accepted for async processing)
      summary: Unpublish a User's Articles and Comments
      tags:
        - users
  /api/videos:
    get:
      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":
          content:
            application/json:
              example:
                - cloudinary_video_url: https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/thumbs-video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f-00001.png
                  id: 817
                  path: /username499/a-darkling-plain201-3c44
                  title: A Darkling Plain201
                  type_of: video_article
                  user:
                    name: Joshua "Lorrie" \:/ Yundt
                  user_id: 1939
                  video_duration_in_minutes: 00:00
                  video_source_url: https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f.m3u8
                - cloudinary_video_url: https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/thumbs-video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f-00001.png
                  id: 818
                  path: /username500/a-swiftly-tilting-planet202-3igo
                  title: A Swiftly Tilting Planet202
                  type_of: video_article
                  user:
                    name: Hayley "Matt" \:/ Schuster
                  user_id: 1940
                  video_duration_in_minutes: 00:00
                  video_source_url: https://dw71fyauz7yz9.cloudfront.net/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f/video-upload__1e42eb0bab4abb3c63baeb5e8bdfe69f.m3u8
              schema:
                items:
                  $ref: "#/components/schemas/VideoArticle"
                type: array
          description: A List of all articles with videos
      security: []
      summary: Articles with a video
      tags:
        - videos
        - articles
components:
  parameters:
    listingCategoryParam:
      description: |-
        Using this parameter will return listings belonging to the
                      requested category.
      example: cfp
      in: query
      name: category
      schema:
        type: string
    pageParam:
      description: Pagination page
      in: query
      name: page
      required: false
      schema:
        default: 1
        format: int32
        minimum: 1
        type: integer
    perPageParam10to1000:
      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.
      in: query
      name: per_page
      required: false
      schema:
        default: 10
        format: int32
        maximum: 1000
        minimum: 1
        type: integer
    perPageParam24to1000:
      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.
      in: query
      name: per_page
      required: false
      schema:
        default: 24
        format: int32
        maximum: 1000
        minimum: 1
        type: integer
    perPageParam30to100:
      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.
      in: query
      name: per_page
      required: false
      schema:
        default: 30
        format: int32
        maximum: 100
        minimum: 1
        type: integer
    perPageParam30to1000:
      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.
      in: query
      name: per_page
      required: false
      schema:
        default: 30
        format: int32
        maximum: 1000
        minimum: 1
        type: integer
    perPageParam80to1000:
      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.
      in: query
      name: per_page
      required: false
      schema:
        default: 80
        format: int32
        maximum: 1000
        minimum: 1
        type: integer
  schemas:
    Article:
      description: Representation of an Article to be created/updated
      properties:
        article:
          properties:
            body_markdown:
              type: string
            canonical_url:
              nullable: true
              type: string
            description:
              type: string
            main_image:
              nullable: true
              type: string
            organization_id:
              nullable: true
              type: integer
            published:
              default: false
              type: boolean
            series:
              nullable: true
              type: string
            tags:
              type: string
            title:
              type: string
          type: object
      type: object
    ArticleFlareTag:
      description: Flare tag of the article
      properties:
        bg_color_hex:
          description: Background color (hexadecimal)
          nullable: true
          type: string
        name:
          type: string
        text_color_hex:
          description: Text color (hexadecimal)
          nullable: true
          type: string
      type: object
    ArticleIndex:
      description: Representation of an article or post returned in a list
      properties:
        canonical_url:
          format: url
          type: string
        cover_image:
          format: url
          nullable: true
          type: string
        created_at:
          format: date-time
          type: string
        crossposted_at:
          format: date-time
          nullable: true
          type: string
        description:
          type: string
        edited_at:
          format: date-time
          nullable: true
          type: string
        flare_tag:
          $ref: "#/components/schemas/ArticleFlareTag"
        id:
          format: int32
          type: integer
        last_comment_at:
          format: date-time
          type: string
        organization:
          $ref: "#/components/schemas/SharedOrganization"
        path:
          format: path
          type: string
        positive_reactions_count:
          format: int32
          type: integer
        public_reactions_count:
          format: int32
          type: integer
        published_at:
          format: date-time
          type: string
        published_timestamp:
          description: Crossposting or published date time
          format: date-time
          type: string
        readable_publish_date:
          type: string
        reading_time_minutes:
          description: Reading time, in minutes
          format: int32
          type: integer
        slug:
          type: string
        social_image:
          format: url
          type: string
        tag_list:
          items:
            type: string
          type: array
        tags:
          type: string
        title:
          type: string
        type_of:
          type: string
        url:
          format: url
          type: string
        user:
          $ref: "#/components/schemas/SharedUser"
      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
      type: object
    Comment:
      description: A Comment on an Article or Podcast Episode
      properties:
        created_at:
          format: date-time
          type: string
        id_code:
          type: string
        image_url:
          description: Podcast image url
          format: url
          type: string
        type_of:
          type: string
      type: object
    DisplayAd:
      description: A Display Ad, aka Billboard, aka Widget
      properties:
        approved:
          description: Ad must be both published and approved to be in rotation
          type: boolean
        article_exclude_ids:
          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
          nullable: true
          type: string
        body_markdown:
          description: The text (in markdown) of the ad (required)
          type: string
        creator_id:
          description: Identifies the user who created the ad.
          nullable: true
          type: integer
        display_to:
          default: all
          description: Potentially limits visitors to whom the ad is visible
          enum:
            - all
            - logged_in
            - logged_out
          type: string
        id:
          description: The ID of the Display Ad
          type: integer
        name:
          description: For internal use, helps distinguish ads from one another
          type: string
        organization_id:
          description: Identifies the organization to which the ad belongs
          nullable: true
          type: integer
        placement_area:
          description: Identifies which area of site layout the ad can appear in
          enum:
            - sidebar_left
            - sidebar_left_2
            - sidebar_right
            - feed_first
            - feed_second
            - feed_third
            - post_sidebar
            - post_comments
          type: string
        published:
          description: Ad must be both published and approved to be in rotation
          type: boolean
        tag_list:
          description: Tags on which this ad can be displayed (blank is all/any tags)
          type: string
        type_of:
          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)
          enum:
            - in_house
            - community
            - external
          type: string
      required:
        - name
        - body_markdown
        - placement_area
      type: object
    FollowedTag:
      description: Representation of a followed tag
      properties:
        id:
          description: Tag id
          format: int64
          type: integer
        name:
          type: string
        points:
          format: float
          type: number
      required:
        - id
        - name
        - points
      type: object
    Organization:
      description: Representation of an Organization
      properties:
        github_username:
          type: string
        joined_at:
          type: string
        location:
          type: string
        name:
          type: string
        story:
          nullable: true
          type: string
        summary:
          type: string
        tag_line:
          nullable: true
          type: string
        tech_stack:
          type: string
        twitter_username:
          type: string
        type_of:
          type: string
        url:
          type: string
        username:
          type: string
      type: object
    Page:
      description: Representation of a page object
      properties:
        body_json:
          description: For JSON pages, the JSON body
          nullable: true
          type: string
        body_markdown:
          description: The text (in markdown) of the ad (required)
          nullable: true
          type: string
        description:
          description: For internal use, helps similar pages from one another
          type: string
        is_top_level_path:
          description: If true, the page is available at '/{slug}' instead of '/page/{slug}', use with caution
          type: boolean
        slug:
          description: Used to link to this page in URLs, must be unique and URL-safe
          type: string
        social_image:
          nullable: true
          type: object
        template:
          default: contained
          description: Controls what kind of layout the page is rendered in
          enum:
            - contained
            - full_within_layout
            - nav_bar_included
            - json
          type: string
        title:
          description: Title of the page
          type: string
      required:
        - title
        - slug
        - description
        - template
      type: object
    PodcastEpisodeIndex:
      description: Representation of a podcast episode returned in a list
      properties:
        class_name:
          type: string
        id:
          format: int32
          type: integer
        image_url:
          description: Podcast episode image url or podcast image url
          format: url
          type: string
        path:
          format: path
          type: string
        podcast:
          $ref: "#/components/schemas/SharedPodcast"
        title:
          type: string
        type_of:
          type: string
      required:
        - type_of
        - class_name
        - id
        - path
        - title
        - image_url
        - podcast
      type: object
    ProfileImage:
      description: A profile image object
      properties:
        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
        type_of:
          description: Return profile_image
          type: string
      type: object
    SharedOrganization:
      description: The organization the resource belongs to
      properties:
        name:
          type: string
        profile_image:
          description: Profile image (640x640)
          format: url
          type: string
        profile_image_90:
          description: Profile image (90x90)
          format: url
          type: string
        slug:
          type: string
        username:
          type: string
      type: object
    SharedPodcast:
      description: The podcast that the resource belongs to
      properties:
        image_url:
          description: Podcast image url
          format: url
          type: string
        slug:
          type: string
        title:
          type: string
      type: object
    SharedUser:
      description: The resource creator
      properties:
        github_username:
          nullable: true
          type: string
        name:
          type: string
        profile_image:
          description: Profile image (640x640)
          type: string
        profile_image_90:
          description: Profile image (90x90)
          type: string
        twitter_username:
          nullable: true
          type: string
        username:
          type: string
        website_url:
          format: url
          nullable: true
          type: string
      type: object
    Tag:
      description: Representation of a tag
      properties:
        bg_color_hex:
          nullable: true
          type: string
        id:
          description: Tag id
          format: int64
          type: integer
        name:
          type: string
        text_color_hex:
          nullable: true
          type: string
      type: object
    User:
      description: The representation of a user
      properties:
        github_username:
          type: string
        id:
          format: int64
          type: integer
        joined_at:
          type: string
        location:
          nullable: true
          type: string
        name:
          type: string
        profile_image:
          type: string
        summary:
          nullable: true
          type: string
        twitter_username:
          type: string
        type_of:
          type: string
        username:
          type: string
        website_url:
          nullable: true
          type: string
      type: object
    UserInviteParam:
      description: User invite parameters
      properties:
        email:
          type: string
        name:
          nullable: true
          type: string
      type: object
    VideoArticle:
      description: Representation of an Article with video
      properties:
        cloudinary_video_url:
          type: string
        id:
          format: int64
          type: integer
        path:
          type: string
        title:
          type: string
        type_of:
          type: string
        user:
          description: Author of the article
          properties:
            name:
              type: string
          type: object
        user_id:
          format: int64
          type: integer
        video_duration_in_minutes:
          type: string
        video_source_url:
          type: string
      type: object
  securitySchemes:
    api-key:
      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)
      in: header
      name: api-key
      type: apiKey
