api_v0.yml

# This document follows the OpenAPI spec <https://spec.openapis.org/oas/v3.0.3>
# It contains two Redoc vendor extensions, x-codeSamples and x-logo
# x-logo: https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#x-logo
# x-codeSamples: https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#x-codesamples

openapi: "3.0.3"
info:
  title: DEV API (beta)
  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 that don't require authentication are CORS enabled.

    All requests must send a user-agent header.

    Dates and date times, unless otherwise specified, must be in
    the [RFC 3339](https://tools.ietf.org/html/rfc3339) format.

  version: "0.9.7"
  termsOfService: https://dev.to/terms
  contact:
    name: DEV Team
    url: https://dev.to/contact
    email: yo@dev.to
  x-logo:
    url: https://res.cloudinary.com/practicaldev/image/fetch/s--EYllUmBG--/c_limit,f_auto,fl_progressive,q_80,w_190/https://res.cloudinary.com/practicaldev/image/fetch/s--m5i3pkpk--/c_limit%252cf_auto%252cfl_progressive%252cq_auto%252cw_880/https://dev-to-uploads.s3.amazonaws.com/i/sf6uve8ehm4ogwka0mez.png
    backgroundColor: ""
    altText: "Forem logo"

servers:
  - url: https://dev.to/api
    description: Production server

components:
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      description: Pagination page.
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
    perPageParam10to1000:
      in: query
      name: per_page
      required: false
      description: Page size (the number of items to return per page).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 10
    perPageParam24to1000:
      in: query
      name: per_page
      required: false
      description: Page size (the number of items to return per page).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 24
    perPageParam30to1000:
      in: query
      name: per_page
      required: false
      description: Page size (the number of items to return per page).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 30
    perPageParam30to100:
      in: query
      name: per_page
      required: false
      description: Page size (the number of items to return per page).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 30
    perPageParam80to1000:
      in: query
      name: per_page
      required: false
      description: Page size (the number of items to return per page).
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 80
    listingCategoryParam:
      name: category
      in: query
      description: |
        Using this parameter will return listings belonging to the
        requested category.
      schema:
        type: string
      example: cfp

  securitySchemes:
    api_key:
      type: apiKey
      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)
      name: api-key
      in: header

  schemas:
    APIError:
      type: object
      required:
        - error
        - status
      properties:
        error:
          type: string
        status:
          type: integer
          format: int32
    ArticleIndex:
      type: object
      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
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        title:
          type: string
        description:
          type: string
        cover_image:
          type: string
          format: url
          nullable: true
        readable_publish_date:
          type: string
        social_image:
          type: string
          format: url
        tag_list:
          type: array
          items:
            type: string
        tags:
          type: string
        slug:
          type: string
        path:
          type: string
          format: path
        url:
          type: string
          format: url
        canonical_url:
          type: string
          format: url
        comments_count:
          type: integer
          format: int32
        positive_reactions_count:
          type: integer
          format: int32
        public_reactions_count:
          type: integer
          format: int32
        created_at:
          type: string
          format: date-time
        edited_at:
          type: string
          format: date-time
          nullable: true
        crossposted_at:
          type: string
          format: date-time
          nullable: true
        published_at:
          type: string
          format: date-time
        last_comment_at:
          type: string
          format: date-time
        published_timestamp:
          description: Crossposting or published date time
          type: string
          format: date-time
        user:
          $ref: "#/components/schemas/SharedUser"
        reading_time_minutes:
          description: Reading time, in minutes
          type: integer
          format: int32
        organization:
          $ref: "#/components/schemas/SharedOrganization"
        flare_tag:
          $ref: "#/components/schemas/ArticleFlareTag"

    ArticleShow:
      type: object
      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
        - body_html
        - body_markdown
        - user
        - reading_time_minutes
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        title:
          type: string
        description:
          type: string
        cover_image:
          type: string
          format: url
          nullable: true
        readable_publish_date:
          type: string
        social_image:
          type: string
          format: url
        tag_list:
          type: string
        tags:
          type: array
          items:
            type: string
        slug:
          type: string
        path:
          type: string
          format: path
        url:
          type: string
          format: url
        canonical_url:
          type: string
          format: url
        comments_count:
          type: integer
          format: int32
        positive_reactions_count:
          type: integer
          format: int32
        public_reactions_count:
          type: integer
          format: int32
        created_at:
          type: string
          format: date-time
        edited_at:
          type: string
          format: date-time
          nullable: true
        crossposted_at:
          type: string
          format: date-time
          nullable: true
        published_at:
          type: string
          format: date-time
        last_comment_at:
          type: string
          format: date-time
        published_timestamp:
          description: Crossposting or published date time
          type: string
          format: date-time
        body_html:
          type: string
        body_markdown:
          type: string
        user:
          $ref: "#/components/schemas/SharedUser"
        reading_time_minutes:
          description: Reading time, in minutes
          type: integer
          format: int32
        organization:
          $ref: "#/components/schemas/SharedOrganization"
        flare_tag:
          $ref: "#/components/schemas/ArticleFlareTag"

    ArticleCreate:
      type: object
      properties:
        article:
          type: object
          properties:
            title:
              type: string
            body_markdown:
              description: |
                The body of the article.

                It can contain an optional front matter. For example

                ```markdown
                ---
                title: Hello, World!
                published: true
                tags: discuss, help
                date: 20190701T10:00Z
                series: Hello series
                canonical_url: https://example.com/blog/hello
                cover_image: article_published_cover_image
                ---
                ```

                `date`, `series` and `canonical_url` are optional.
                `date` is the publication date-time
                `series` is the name of the series the article belongs to
                `canonical_url` is the canonical URL of the article
                `cover_image` is the main image of the article

                *If the markdown contains a front matter, it will take precedence
                on the equivalent params given in the payload.*
              type: string
            published:
              description: |
                True to create a published article, false otherwise. Defaults to false
              type: boolean
            series:
              description: |
                Article series name.

                All articles belonging to the same series need to have the same name
                in this parameter.
              type: string
            main_image:
              type: string
              format: url
            canonical_url:
              type: string
              format: url
            description:
              type: string
            tags:
              type: array
              items:
                type: string
            organization_id:
              description: |
                Only users belonging to an organization can assign the article to it
              type: integer
              format: int32

    ArticleUpdate:
      type: object
      properties:
        article:
          type: object
          properties:
            title:
              type: string
            body_markdown:
              description: |
                The body of the article.

                It can contain an optional front matter. For example

                ```markdown
                ---
                title: Hello, World!
                published: true
                tags: discuss, help
                date: 20190701T10:00Z
                series: Hello series
                canonical_url: https://example.com/blog/hello
                cover_image: article_published_cover_image
                ---
                ```

                `date`, `series` and `canonical_url` are optional.
                `date` is the publication date-time
                `series` is the name of the series the article belongs to
                `canonical_url` is the canonical URL of the article
                `cover_image` is the main image of the article

                *If the markdown contains a front matter, it will take precedence
                on the equivalent params given in the payload.*
              type: string
            published:
              description: |
                True to create a published article, false otherwise. Defaults to false
              type: boolean
            series:
              description: |
                Article series name.

                All articles belonging to the same series need to have the same name
                in this parameter.

                To remove an article from a series, the `null` value can be used.
              type: string
            main_image:
              type: string
              format: url
            canonical_url:
              type: string
              format: url
            description:
              type: string
            tags:
              type: array
              items:
                type: string
            organization_id:
              description: |
                Only users belonging to an organization can assign the article to it
              type: integer
              format: int32

    ArticleMe:
      type: object
      required:
        - type_of
        - id
        - title
        - description
        - cover_image
        - published
        - published_at
        - tag_list
        - slug
        - path
        - url
        - canonical_url
        - comments_count
        - positive_reactions_count
        - public_reactions_count
        - page_views_count
        - published_timestamp
        - body_markdown
        - user
        - reading_time_minutes
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        title:
          type: string
        description:
          type: string
        cover_image:
          type: string
          format: url
          nullable: true
        published:
          type: boolean
        published_at:
          type: string
          format: date-time
        tag_list:
          type: array
          items:
            type: string
        slug:
          type: string
        path:
          type: string
          format: path
        url:
          type: string
          format: url
        canonical_url:
          type: string
          format: url
        comments_count:
          type: integer
          format: int32
        positive_reactions_count:
          type: integer
          format: int32
        public_reactions_count:
          type: integer
          format: int32
        page_views_count:
          type: integer
          format: int32
        published_timestamp:
          description: Crossposting or published date time
          type: string
          format: date-time
        body_markdown:
          description: The body of the article in Markdown format
          type: string
        user:
          $ref: "#/components/schemas/SharedUser"
        reading_time_minutes:
          description: Reading time, in minutes
          type: integer
          format: int32
        organization:
          $ref: "#/components/schemas/SharedOrganization"
        flare_tag:
          $ref: "#/components/schemas/ArticleFlareTag"

    ArticleFlareTag:
      description: Flare tag of the article
      type: object
      properties:
        name:
          type: string
        bg_color_hex:
          description: Background color (hexadecimal)
          type: string
        text_color_hex:
          description: Text color (hexadecimal)
          type: string

    ArticleVideo:
      type: object
      required:
        - type_of
        - id
        - path
        - cloudinary_video_url
        - title
        - user_id
        - video_duration_in_minutes
        - video_source_url
        - user
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        path:
          type: string
        cloudinary_video_url:
          description: The preview image of the video
          type: string
          format: url
        title:
          type: string
        user_id:
          type: integer
          format: int32
        video_duration_in_minutes:
          description: |
            The duration of the video.

            If the video duration is below 1 hour, the format will be `mm:ss`,
            if it's 1 hour or above the format will be `h:mm:ss`.
          type: string
        video_source_url:
          format: url
          type: string
        user:
          type: object
          properties:
            name:
              description: The user's name
              type: string

    Comment:
      type: object
      required:
        - type_of
        - id_code
        - created_at
        - body_html
        - user
        - children
      properties:
        type_of:
          type: string
        id_code:
          type: string
        created_at:
          type: string
          format: date-time
        body_html:
          description: HTML formatted comment
          type: string
        user:
          $ref: "#/components/schemas/SharedUser"
        children:
          type: array
          items:
            $ref: "#/components/schemas/Comment"
    FollowedTag:
      type: object
      required:
        - id
        - name
        - points
      properties:
        id:
          description: Tag id
          type: integer
          format: int64
        name:
          type: string
        points:
          type: number
          format: float

    Follower:
      type: object
      required:
        - type_of
        - created_at
        - id
        - user_id
        - name
        - path
        - username
        - profile_image
      properties:
        type_of:
          type: string
        created_at:
          description: Date the user became a follower
          type: string
          format: date-time
        id:
          description: Follow id
          type: integer
          format: int32
        user_id:
          type: integer
          format: int32
        name:
          type: string
        path:
          type: string
        username:
          type: string
        profile_image:
          description: Profile image (60x60)
          type: string
          format: url

    Listing:
      type: object
      required:
        - type_of
        - id
        - title
        - slug
        - body_markdown
        - tag_list
        - tags
        - category
        - processed_html
        - published
        - user
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int64
        title:
          type: string
        slug:
          type: string
        body_markdown:
          type: string
        tag_list:
          type: string
        tags:
          type: array
          items:
            type: string
        category:
          $ref: "#/components/schemas/ListingCategory"
        processed_html:
          type: string
        published:
          type: boolean
        user:
          $ref: "#/components/schemas/SharedUser"
        organization:
          $ref: "#/components/schemas/SharedOrganization"

    ListingCategory:
      type: string
      enum: [cfp, forhire, collabs, education, jobs, mentors, products, mentees, forsale, events, misc]

    ListingCreate:
      type: object
      properties:
        listing:
          type: object
          required:
            - title
            - body_markdown
            - category
          properties:
            title:
              type: string
            body_markdown:
              description: The body of the listing in Markdown format.
              type: string
            category:
              $ref: "#/components/schemas/ListingCategory"
            tags:
              description: |
                Tags related to the listing.

                A maximum of 8 tags are allowed and it takes precedence over `tag_list`.
              type: array
              items:
                type: string
            tag_list:
              description: |
                Comma separated list of tags.

                A maximum of 8 tags are allowed.
              type: string
            expires_at:
              description: Date and time of expiration.
              type: string
              format: date-time
            contact_via_connect:
              description: |
                True if users are allowed to contact the listing's owner
                via DEV connect, false otherwise.

                Defaults to false.
              type: boolean
            location:
              description: Geographical area or city for the listing.
              type: string
            organization_id:
              description: |
                The id of the organization the user is creating the listing for.

                Only users belonging to an organization can assign the listing to it.
              type: integer
              format: int64
            action:
              description: Set it to "draft" to create an unpublished listing
              type: string
              enum: [draft]

    ListingUpdate:
      type: object
      properties:
        listing:
          type: object
          properties:
            title:
              type: string
            body_markdown:
              description: The body of the listing in Markdown format.
              type: string
            category:
              $ref: "#/components/schemas/ListingCategory"
            tags:
              description: |
                Tags related to the listing.

                A maximum of 8 tags are allowed and it takes precedence over `tag_list`.
              type: array
              items:
                type: string
            tag_list:
              description: |
                Comma separated list of tags.

                A maximum of 8 tags are allowed.
              type: string
            expires_at:
              description: Date and time of expiration.
              type: string
              format: date-time
            contact_via_connect:
              description: |
                True if users are allowed to contact the listing's owner
                via DEV connect, false otherwise.

                Defaults to false.
              type: boolean
            location:
              description: Geographical area or city for the listing.
              type: string
            action:
              description: |
                This param can be provided by itself to invoke some actions:

                - `bump` bumps the listing and charge either the
                  organization or the user
                - `publish` publishes a draft listing
                - `unpublish` unpublishes a published listing

                It will take priority on any other param in the payload.
              type: string
              enum: [bump, publish, unpublish]

    ReadingList:
      type: object
      required:
        - type_of
        - id
        - status
        - created_at
        - article
      properties:
        type_of:
          type: string
        id:
          description: Follow id
          type: integer
          format: int32
        status:
          type: string
          enum:
            - valid
            - invalid
            - confirmed
            - archived
        created_at:
          type: string
          format: date-time
        article:
          $ref: "#/components/schemas/ArticleIndex"

    PodcastEpisode:
      type: object
      required:
        - type_of
        - id
        - path
        - image_url
        - title
        - podcast
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        path:
          type: string
        image_url:
          type: string
          format: url
        title:
          type: string
        podcast:
          type: object
          properties:
            title:
              type: string
            slug:
              type: string
            image_url:
              type: string
              format: url

    SharedUser:
      description: The resource creator
      type: object
      properties:
        user_id:
          type: integer
          format: int32
        name:
          type: string
        username:
          type: string
        twitter_username:
          type: string
          nullable: true
        github_username:
          type: string
          nullable: true
        website_url:
          type: string
          format: url
          nullable: true
        profile_image:
          description: Profile image (640x640)
          type: string
        profile_image_90:
          description: Profile image (90x90)
          type: string

    SharedOrganization:
      description: The organization the resource belongs to
      type: object
      properties:
        name:
          type: string
        username:
          type: string
        slug:
          type: string
        profile_image:
          description: Profile image (640x640)
          type: string
          format: url
        profile_image_90:
          description: Profile image (90x90)
          type: string
          format: url

    Tag:
      type: object
      required:
        - id
        - name
        - bg_color_hex
        - text_color_hex
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        bg_color_hex:
          description: Background color (hexadecimal)
          type: string
        text_color_hex:
          description: Text color (hexadecimal)
          type: string

    User:
      type: object
      required:
        - type_of
        - id
        - username
        - name
        - summary
        - twitter_username
        - github_username
        - website_url
        - location
        - joined_at
        - profile_image
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int32
        username:
          type: string
        name:
          type: string
        summary:
          type: string
          nullable: true
        twitter_username:
          type: string
          nullable: true
        github_username:
          type: string
          nullable: true
        website_url:
          type: string
          format: url
          nullable: true
        location:
          type: string
          nullable: true
        joined_at:
          description: Date of joining (formatted with strftime `"%b %e, %Y"`)
          type: string
        profile_image:
          description: Profile image (320x320)
          type: string
          format: url

    ProfileImage:
      description: Profile image
      type: object
      properties:
        type_of:
          type: string
          enum: [profile_image]
        image_of:
          description: "Discriminates what is the type of the profile image owner (user or organization)"
          type: string
          enum: [user, organization]
        profile_image:
          type: string
          description: Profile image (640x640)
        profile_image_90:
          type: string
          description: Profile image (90x90)

    Organization:
      description: Organization
      type: object
      properties:
        type_of:
          type: string
        username:
          type: string
        name:
          type: string
        summary:
          type: string
          nullable: true
        twitter_username:
          type: string
          nullable: true
        github_username:
          type: string
          nullable: true
        url:
          type: string
          format: url
        location:
          type: string
          nullable: true
        tech_stack:
          type: string
          nullable: true
        tag_line:
          type: string
          nullable: true
        story:
          type: string
          nullable: true
        joined_at:
          description: Date of joining
          type: string
          format: date-time
        profile_image:
          type: string
          description: Profile image (640x640)
          format: url

    AdminUserCreate:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          format: name

  examples:
    ErrorBadRequest:
      value:
        error: bad request
        status: 400
    ErrorNotFound:
      value:
        error: not found
        status: 404
    ErrorUnauthorized:
      value:
        error: unauthorized
        status: 401
    ErrorPaymentRequired:
      value:
        error: not enough available credits
        status: 402
    ErrorForbidden:
      value:
        error: forbidden
        status: 403
    ErrorUnprocessableEntity:
      value:
        error: "param is missing or the value is empty: article"
        status: 422
    ErrorTooManyRequests:
      value:
        error: "Rate limit reached, try again in 30 seconds"
        status: 429

    ArticlesIndex:
      value:
        - type_of: article
          id: 194541
          title: There's a new DEV theme in town for all you 10x hackers out there (plus one
            actually useful new feature)
          description: ''
          cover_image: https://res.cloudinary.com/practicaldev/image/fetch/s--74Bl23tz--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://res.cloudinary.com/practicaldev/image/fetch/s--xU8cbIK4--/c_imagga_scale%2Cf_auto%2Cfl_progressive%2Ch_420%2Cq_auto%2Cw_1000/https://thepracticaldev.s3.amazonaws.com/i/8a39dzf3oovzc2snl7iv.png
          readable_publish_date: Oct 24
          social_image: https://res.cloudinary.com/practicaldev/image/fetch/s--SeMxdKIa--/c_imagga_scale,f_auto,fl_progressive,h_500,q_auto,w_1000/https://res.cloudinary.com/practicaldev/image/fetch/s--xU8cbIK4--/c_imagga_scale%2Cf_auto%2Cfl_progressive%2Ch_420%2Cq_auto%2Cw_1000/https://thepracticaldev.s3.amazonaws.com/i/8a39dzf3oovzc2snl7iv.png
          tag_list:
            - meta
            - changelog
            - css
            - ux
          tags: meta, changelog, css, ux
          slug: there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
          path: "/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk"
          url: https://dev.to/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
          canonical_url: https://dev.to/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
          comments_count: 37
          positive_reactions_count: 12
          public_reactions_count: 142
          collection_id:
          created_at: '2019-10-24T13:41:29Z'
          edited_at: '2019-10-24T13:56:35Z'
          crossposted_at:
          published_at: '2019-10-24T13:52:17Z'
          last_comment_at: '2019-10-25T08:12:43Z'
          published_timestamp: '2019-10-24T13:52:17Z'
          reading_time_minutes: 15
          user:
            name: Ben Halpern
            username: ben
            twitter_username: bendhalpern
            github_username: benhalpern
            website_url: http://benhalpern.com
            profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--Y1sq1tFG--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/1/f451a206-11c8-4e3d-8936-143d0a7e65bb.png
            profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--DcW51A6v--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/1/f451a206-11c8-4e3d-8936-143d0a7e65bb.png
          organization:
            name: The DEV Team
            username: devteam
            slug: devteam
            profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--0kDBq1Ne--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/1/0213bbaa-d5a1-4d25-9e7a-10c30b455af0.png
            profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--8tTU-XkZ--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/1/0213bbaa-d5a1-4d25-9e7a-10c30b455af0.png
    ArticleShow:
      value:
        type_of: article
        id: 150589
        title: "Byte Sized Episode 2: The Creation of Graph Theory "
        description: The full story of Leonhard Euler and the creation of this fundamental
          computer science principle, delivered in a few minutes.
        cover_image: https://res.cloudinary.com/practicaldev/image/fetch/s--qgutBUrH--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://thepracticaldev.s3.amazonaws.com/i/88e62fzblbluz1dm7xjf.png
        readable_publish_date: Aug  1
        social_image: https://res.cloudinary.com/practicaldev/image/fetch/s--6wSHHfwd--/c_imagga_scale,f_auto,fl_progressive,h_500,q_auto,w_1000/https://thepracticaldev.s3.amazonaws.com/i/88e62fzblbluz1dm7xjf.png
        tag_list: computerscience, graphtheory, bytesized, history
        tags:
          - computerscience
          - graphtheory
          - bytesized
          - history
        slug: byte-sized-episode-2-the-creation-of-graph-theory-34g1
        path: "/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1"
        url: https://dev.to/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1
        canonical_url: https://dev.to/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1
        comments_count: 21
        positive_reactions_count: 122
        public_reactions_count: 322
        collection_id: 1693
        created_at: "2019-07-31T11:15:06Z"
        edited_at:
        crossposted_at:
        published_at: "2019-08-01T15:47:54Z"
        last_comment_at: "2019-08-06T16:48:10Z"
        published_timestamp: "2019-08-01T15:47:54Z"
        reading_time_minutes: 15
        body_html: |+
          <p>Today's episode of Byte Sized is about Leonhard Euler and the creation of <a href="https://en.wikipedia.org/wiki/Graph_theory">Graph Theory</a>.</p>

          <p>For more about how Graph Theory works, check out this video from BaseCS!</p>...
        body_markdown: "---\r\ntitle: Byte Sized Episode 2: The Creation of Graph Theory \r\npublished:
          true\r\ndescription: The full story of Leonhard Euler and the creation of this fundamental
          computer science principle, delivered in a few minutes.\r\ntags: computerscience,
          graphtheory, bytesized, history\r\ncover_image: https://thepracticaldev.s3.amazonaws.com/i/88e62fzblbluz1dm7xjf.png\r\nseries:
          Byte Sized Season 1\r\n---\r\n\r\nToday's episode of Byte Sized is about Leonhard
          Euler and the creation of [Graph Theory](https://en.wikipedia.org/wiki/Graph_theory).\r\n\r\nFor
          more about how Graph Theory works, check out this video from BaseCS!..."
        user:
          name: Vaidehi Joshi
          username: vaidehijoshi
          twitter_username: vaidehijoshi
          github_username: vaidehijoshi
          website_url: http://www.vaidehi.com
          profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--eDGAYAoK--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2882/K2evUksb.jpg
          profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--htZnqMn3--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2882/K2evUksb.jpg
        organization:
          name: Byte Sized
          username: bytesized
          slug: bytesized
          profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--sq0DrZfn--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/865/652f7998-32a8-4fd9-85ca-dd697d2a9ee9.png
          profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--1Pt_ICL---/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/organization/profile_image/865/652f7998-32a8-4fd9-85ca-dd697d2a9ee9.png
    ArticleCreateTitleBody:
      value:
        article:
          title: Hello, World!
          published: true
          body_markdown: Hello DEV, this is my first post
          tags: ["discuss", "help"]
          series: Hello series
    ArticleCreateFrontMatter:
      value:
        article:
          body_markdown: |
            ---
            title: Hello, World!
            published: true
            tags: discuss, help
            date: 20190701T10:00Z
            series: Hello series
            ---

            Hello DEV, this is my first post
    ArticleCreateOrganization:
      value:
        article:
          title: Hello, World!
          published: true
          body_markdown: Hello DEV, this is my first post
          tags: ["discuss", "help"]
          series: Hello series
          organization_id: 1234
    ArticleVideo:
      value:
        - type_of: video_article
          id: 273532
          path: "/devteam/basecs-depth-first-search-implementing-4kkl"
          cloudinary_video_url: https://res.cloudinary.com/....png
          title: 'BaseCS: Depth First Search Implementing'
          user_id: 2882
          video_duration_in_minutes: '11:47'
          video_source_url: 'https://dw71fyauz7yz9.cloudfront.net/123/123.m3u8'
          user:
            name: Vaidehi Joshi

    Comments:
      value:
        - type_of: comment
          id_code: m3m0
          created_at: 2020-07-01T17:59:43Z
          body_html: |
            <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
            <html><body>
            <p>...</p>

            </body></html>
          user:
            user_id: 4056
            name: Heriberto Morissette
            username: heriberto_morissette
            twitter_username:
            github_username:
            website_url:
            profile_image: https://res.cloudinary.com/...jpeg
            profile_image_90: https://res.cloudinary.com/...jpeg
          children: []
        - type_of: comment
          id_code: m357
          created_at: 2020-07-02T17:19:40Z
          body_html: |
            <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
            <html><body>
            <p>...</p>

            <p>...</p>

            </body></html>
          user:
            name: Dario Waelchi
            username: dario waelchi
            twitter_username:
            github_username:
            user_id: 7707
            website_url:
            profile_image: https://res.cloudinary.com/...png
            profile_image_90: https://res.cloudinary.com/...png
          children:
            - type_of: comment
              id_code: m35m
              created_at: 2020-08-01T11:59:40Z
              body_html: |
                <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
                <html><body>

                <p>...</p>

                </body></html>
              user:
                name: rhymes
                username: rhymes
                twitter_username:
                github_username:
                user_id: 819
                website_url:
                profile_image: https://res.cloudinary.com/...jpeg
                profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--SC90PuMi--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg
              children: []
    CommentsDeleted:
      value:
        - type_of: comment
          id_code: m357
          body_html: <p>[deleted]</p>
          user: {}
          children:
            - type_of: comment
              id_code: m35m
              body_html: |
                <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
                <html><body>

                <p>...</p>

                </body></html>
              user:
                name: rhymes
                username: rhymes
                twitter_username:
                github_username:
                website_url:
                profile_image: https://res.cloudinary.com/...jpeg
                profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--SC90PuMi--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg
              children: []
    CommentsHidden:
      value:
        - type_of: comment
          id_code: m357
          body_html: <p>[hidden by post author]</p>
          user: {}
          children:
            - type_of: comment
              id_code: m35m
              body_html: |
                <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
                <html><body>

                <p>...</p>

                </body></html>
              user:
                name: rhymes
                username: rhymes
                twitter_username:
                github_username:
                website_url:
                profile_image: https://res.cloudinary.com/...jpeg
                profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--SC90PuMi--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg
              children: []
    Comment:
      value:
        type_of: comment
        id_code: m357
        created_at: 2020-08-02T17:19:40Z
        body_html: |
          <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
          <html><body>
          <p>...</p>

          <p>...</p>

          </body></html>
        user:
          name: Dario Waelchi
          username: dario waelchi
          twitter_username:
          github_username:
          website_url:
          profile_image: https://res.cloudinary.com/...png
          profile_image_90: https://res.cloudinary.com/...png
        children:
          - type_of: comment
            id_code: m35m
            created_at: 2020-07-02T17:19:40Z
            body_html: |
              <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
              <html><body>

              <p>...</p>

              </body></html>
            user:
              name: rhymes
              username: rhymes
              twitter_username:
              github_username:
              website_url:
              profile_image: https://res.cloudinary.com/...jpeg
              profile_image_90: https://res.cloudinary.com/....jpeg
            children: []
    CommentDeleted:
      value:
        type_of: comment
        id_code: m357
        body_html: <p>[deleted]</p>
        user: {}
        children:
          - type_of: comment
            id_code: m35m
            body_html: |
              <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
              <html><body>

              <p>...</p>

              </body></html>
            user:
              name: rhymes
              username: rhymes
              twitter_username:
              github_username:
              website_url:
              profile_image: https://res.cloudinary.com/...jpeg
              profile_image_90: https://res.cloudinary.com/...jpeg
            children: []
    CommentHidden:
      value:
        type_of: comment
        id_code: m357
        body_html: <p>[hidden by post author]</p>
        user: {}
        children:
          - type_of: comment
            id_code: m35m
            body_html: |
              <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
              <html><body>

              <p>...</p>

              </body></html>
            user:
              name: rhymes
              username: rhymes
              twitter_username:
              github_username:
              website_url:
              profile_image: https://res.cloudinary.com/...jpeg
              profile_image_90: https://res.cloudinary.com/...jpeg
            children: []

    Followers:
      value:
        - type_of: user_follower
          id: 12
          created_at: "2021-04-02T04:21:46Z"
          user_id: 3081
          name: Mrs. Neda Morissette
          path: "/nedamrsmorissette"
          username: nedamrsmorissette
          profile_image: https://res.cloudinary.com/...
        - type_of: user_follower
          id: 11
          created_at: "2021-04-02T04:21:46Z"
          user_id: 7466
          name: Yoko Hintz
          path: "/yokohintz"
          username: yokohintz
          profile_image: https://res.cloudinary.com/...

    Listings:
      value:
        - type_of: listing
          id: 1157
          created_at: "2021-04-07 08:29:42 UTC"
          title: TestBash Detroit
          slug: testbash-detroit-50gb
          body_markdown: "Do you want to learn about automation? Maybe you're interested in
            AI-driven testing? Security testing? We have a selection of talks, workshops and
            training courses to help you in a wide variety of areas in software testing. Join
            us for our very first trip to Detroit MI! \n\nhttps://bit.ly/TBDetroit"
          tag_list: events
          tags:
            - events
          category: cfp
          processed_html: |
            <p>Do you want to learn about automation? Maybe you're interested in AI-driven testing? Security testing? We have a selection of talks, workshops and training courses to help you in a wide variety of areas in software testing. Join us for our very first trip to Detroit MI! </p>

            <p><a href="https://bit.ly/TBDetroit">https://bit.ly/TBDetroit</a></p>
          published: true
          user:
            name: Heather
            username: heatherr
            twitter_username:
            github_username: Heather-R
            website_url:
            profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--ggU5WPaT--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
            profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--CjladMBD--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
    ListingsByOrganization:
      value:
        - type_of: listing
          id: 1157
          title: TestBash Detroit
          slug: testbash-detroit-50gb
          body_markdown: "Do you want to learn about automation? Maybe you're interested in
            AI-driven testing? Security testing? We have a selection of talks, workshops and
            training courses to help you in a wide variety of areas in software testing. Join
            us for our very first trip to Detroit MI! \n\nhttps://bit.ly/TBDetroit"
          tag_list: events
          tags:
            - events
          category: cfp
          processed_html: |
            <p>Do you want to learn about automation? Maybe you're interested in AI-driven testing? Security testing? We have a selection of talks, workshops and training courses to help you in a wide variety of areas in software testing. Join us for our very first trip to Detroit MI! </p>

            <p><a href="https://bit.ly/TBDetroit">https://bit.ly/TBDetroit</a></p>
          published: true
          user:
            name: Heather
            username: heatherr
            twitter_username:
            github_username: Heather-R
            website_url:
            profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--ggU5WPaT--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
            profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--CjladMBD--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
          organization:
            name: E Corp
            username: ecorp
            slug: ecorp
            profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--ggU5WPaT--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
            profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--CjladMBD--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
    Listing:
      value:
        type_of: listing
        id: 1157
        title: TestBash Detroit
        slug: testbash-detroit-50gb
        body_markdown: "Do you want to learn about automation? Maybe you're interested in
          AI-driven testing? Security testing? We have a selection of talks, workshops and
          training courses to help you in a wide variety of areas in software testing. Join
          us for our very first trip to Detroit MI! \n\nhttps://bit.ly/TBDetroit"
        tag_list: events
        tags:
          - events
        category: cfp
        processed_html: |
          <p>Do you want to learn about automation? Maybe you're interested in AI-driven testing? Security testing? We have a selection of talks, workshops and training courses to help you in a wide variety of areas in software testing. Join us for our very first trip to Detroit MI! </p>

          <p><a href="https://bit.ly/TBDetroit">https://bit.ly/TBDetroit</a></p>
        published: true
        user:
          name: Heather
          username: heatherr
          twitter_username:
          github_username: Heather-R
          website_url:
          profile_image: https://res.cloudinary.com/practicaldev/image/fetch/s--ggU5WPaT--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
          profile_image_90: https://res.cloudinary.com/practicaldev/image/fetch/s--CjladMBD--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://dev-to-uploads.s3.amazonaws.com/uploads/user/profile_image/136256/11cced64-afd2-4421-91e1-c5f7b216d49b.jpeg
    ListingCreate:
      value:
        listing:
          title: ACME Conference
          body_markdown: Awesome conference
          category: cfp
          tags:
            - events
    ListingCreateOrganization:
      value:
        listing:
          title: ACME Conference
          body_markdown: Awesome conference
          category: cfp
          tags:
            - events
          organization_id: 1
    ListingUpdate:
      value:
        listing:
          title: ACME New Conference
          body_markdown: Awesome new conference
    ListingUpdateActionBump:
      value:
        listing:
          action: bump
    ListingUpdateActionPublish:
      value:
        listing:
          action: publish
    ListingUpdateActionUnpublish:
      value:
        listing:
          action: unpublish

    PodcastEpisodes:
      value:
        - type_of: podcast_episodes
          id: 13894
          path: "/codenewbie/s11-e7-why-site-reliability-is-so-important-molly-struve"
          image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png
          title: S11:E7 - Why site reliability is so important (Molly Struve)
          podcast:
            title: CodeNewbie
            slug: codenewbie
            image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png
        - type_of: podcast_episodes
          id: 13829
          path: "/codenewbie/s11-e6-what-are-the-pros-and-cons-of-working-in-civic-tech-aidan-feldman"
          image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png
          title: S11:E6 - What are the pros and cons of working in civic tech (Aidan Feldman)
          podcast:
            title: CodeNewbie
            slug: codenewbie
            image_url: https://dev-to-uploads.s3.amazonaws.com/uploads/podcast/image/2/9f50a462-9152-429a-b15e-d024baaa8e01.png

    Tags:
      value:
        - id: 6
          name: javascript
          bg_color_hex: "#F7DF1E"
          text_color_hex: "#000000"
        - id: 8
          name: webdev
          bg_color_hex: "#562765"
          text_color_hex: "#ffffff"
    TagsFollowed:
      value:
        - id: 13
          name: discuss
          points: 3
        - id: 12
          name: webdev
          points: 1

    User:
      value:
        type_of: user
        id: 1234
        username: bob
        name: bob
        summary: Hello, world
        twitter_username: bob
        github_username: bob
        website_url:
        location: New York
        joined_at: Jan 1, 2017
        profile_image: https://res.cloudinary.com/...jpeg

    Users:
      value:
        - type_of: user
          id: 1234
          username: bob
          name: bob
          summary: Hello, world
          twitter_username: bob
          github_username: bob
          website_url:
          location: New York
          joined_at: Jan 1, 2017
          profile_image: https://res.cloudinary.com/...jpeg

    ProfileImage:
      value:
        type_of: profile_image
        image_of: user
        profile_image: https://res.cloudinary.com/...jpeg
        profile_image_90: https://res.cloudinary.com/...jpeg

    Organization:
      value:
        type_of: organization
        username: ecorp
        name: E Corp
        summary: Together we can change the world, with E Corp
        twitter_username: ecorp
        github_username: ecorp
        url: https://ecorp.internet
        location: New York
        joined_at: '2019-10-24T13:41:29Z'
        tech_stack: Ruby
        tag_line:
        story:

tags:
  - name: articles
    description: Articles are all the posts users create on DEV
  - name: comments
    description: Users can leave comments to articles and podcasts episodes
  - name: follows
    description: Resources are user can follow
  - name: followers
    description: Users can follow other users on the website
  - name: listings
    description: Listings are classified ads
  - name: organizations
    description: Users can create and join organizations
  - name: podcast-episodes
    description: Podcast episodes
  - name: readinglist
    description: User's reading list
  - name: tags
    description: Tags for articles
  - name: users
    description: Users own resources that require authentication
  - name: videos
    description: Video articles
  - name: profile images
    description: User or organization profile images

paths:
  /articles:
    get:
      operationId: getArticles
      summary: Published articles
      description: |
        This endpoint allows the client to retrieve a list of articles.

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

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

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

            Articles will be ordered by descending popularity.

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

            Articles will be ordered by descending popularity.
          schema:
            type: string
          example: "javascript, css"
        - name: tags_exclude
          in: query
          description: |
            Using this parameter will retrieve articles that do _not_ contain _any_ of comma-separated tags.

            Articles will be ordered by descending popularity.
          schema:
            type: string
          example: "node, java"
        - name: username
          in: query
          description: |
            Using this parameter will retrieve articles belonging
            to a User or Organization ordered by descending publication date.

            If `state=all` the number of items returned will be `1000` instead of the default `30`.

            This parameter can be used in conjuction with `state`.
          schema:
            type: string
          example: ben
        - name: state
          in: query
          description: |
            Using this parameter will allow the client to check which articles are fresh or rising.

            If `state=fresh` the server will return fresh articles.
            If `state=rising` the server will return rising articles.

            This param can be used in conjuction with `username`, only if set to `all`.
          schema:
            type: string
            enum: [fresh, rising, all]
          example: fresh
        - name: top
          in: query
          description: |
            Using this parameter will allow the client to return the most popular articles
            in the last `N` days.

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

            This param can be used in conjuction with `tag`.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 2
        - name: collection_id
          in: query
          description: |
            Adding this will allow the client to return the list of articles
            belonging to the requested collection, ordered by ascending
            publication date.
          schema:
            type: integer
            format: int32
          example: 99
      responses:
        "200":
          description: A list of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleIndex"
              examples:
                articles-success:
                  $ref: "#/components/examples/ArticlesIndex"
      x-codeSamples:
        - lang: Shell
          label: curl (all articles)
          source: |
            curl https://dev.to/api/articles
        - lang: Shell
          label: curl (user's articles)
          source: |
            curl https://dev.to/api/articles?username=ben
    post:
      operationId: createArticle
      summary: Create a new article
      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.

        ### Rate limiting

        There is a limit of 10 requests per 30 seconds.

        ### Additional resources

        - [Rails tests for Articles API](https://github.com/forem/forem/blob/main/spec/requests/api/v0/articles_spec.rb)
      tags:
        - articles
      requestBody:
        description: Article to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArticleCreate"
            examples:
              article-create-title-body:
                $ref: "#/components/examples/ArticleCreateTitleBody"
              article-create-front-matter:
                $ref: "#/components/examples/ArticleCreateFrontMatter"
              article-create-organization:
                $ref: "#/components/examples/ArticleCreateOrganization"

      responses:
        "201":
          description: A newly created article
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleShow"
              examples:
                article-success:
                  $ref: "#/components/examples/ArticleShow"
          headers:
            Location:
              description: The URL of the new article
              schema:
                type: string
                format: url
        "400":
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-bad-request:
                  $ref: "#/components/examples/ErrorBadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-forbidden:
                  $ref: "#/components/examples/ErrorForbidden"
        "422":
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorUnprocessableEntity"
        "429":
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorTooManyRequests"
          headers:
            Retry-After:
              description: The number of seconds to wait until the next request
              schema:
                type: integer
                format: int32
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -X POST -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"article":{"title":"Title","body_markdown":"Body","published":false,"tags":["discuss", "javascript"]}}' \
              https://dev.to/api/articles
        - lang: Shell
          label: curl (with front matter)
          source: |
            curl -X POST -H "Content-Type: application/json" \
            -H "api-key: API_KEY" \
            -d '{"article":{"body_markdown":"---\ntitle:A sample article about...\npublished:false\n---\n..."}}' \
            https://dev.to/api/articles

  /articles/latest:
    get:
      operationId: getLatestArticles
      summary: Published articles sorted by publish date
      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.
      tags:
        - articles
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of articles sorted by descending publish date
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleIndex"
              examples:
                articles-success:
                  $ref: "#/components/examples/ArticlesIndex"

  /articles/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Id of the article
        schema:
          type: integer
          format: int32
          minimum: 1
        example: 150589
    get:
      operationId: getArticleById
      summary: A published article by ID
      description: |
        This endpoint allows the client to retrieve a single
        published article given its `id`.
      tags:
        - articles
      responses:
        "200":
          description: An article
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleShow"
              examples:
                article-success:
                  $ref: "#/components/examples/ArticleShow"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/articles/150589
    put:
      operationId: updateArticle
      summary: Update an article
      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.

        ### Rate limiting

        There is a limit of 30 requests per 30 seconds.

        ### Additional resources

        - [Rails tests for Articles API](https://github.com/forem/forem/blob/main/spec/requests/api/v0/articles_spec.rb)
      tags:
        - articles
      requestBody:
        description: |
          Article params for the update.

          *Note: if the article contains a front matter in its body, its front
          matter properties will still take precedence over any JSON equivalent
          params, which means that the full body_markdown with the modified
          front matter params needs to be provided for an update to be successful*
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArticleUpdate"
            examples:
              article-update-title-body:
                $ref: "#/components/examples/ArticleCreateTitleBody"
              article-update-front-matter:
                $ref: "#/components/examples/ArticleCreateFrontMatter"
              article-update-organization:
                $ref: "#/components/examples/ArticleCreateOrganization"
      responses:
        "200":
          description: The updated article
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleShow"
              examples:
                article-success:
                  $ref: "#/components/examples/ArticleShow"
        "400":
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-bad-request:
                  $ref: "#/components/examples/ErrorBadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-forbidden:
                  $ref: "#/components/examples/ErrorForbidden"
        "422":
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorUnprocessableEntity"
        "429":
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorTooManyRequests"
          headers:
            Retry-After:
              description: The number of seconds to wait until the next request
              schema:
                type: integer
                format: int32
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -X PUT -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"article":{"title":"Title"}}' \
              https://dev.to/api/articles/{id}

  /articles/{username}/{slug}:
    parameters:
      - name: username
        in: path
        required: true
        description: User or organization username.
        schema:
          type: string
        example: devteam
      - name: slug
        in: path
        required: true
        description: Slug of the article.
        schema:
          type: string
        example: for-empowering-community-2k6h
    get:
      operationId: getArticleByPath
      summary: A published article by path
      description: |
        This endpoint allows the client to retrieve a single
        published article given its `path`.
      tags:
        - articles
      responses:
        "200":
          description: An article
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleShow"
              examples:
                article-success:
                  $ref: "#/components/examples/ArticleShow"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/articles/bytesized/byte-sized-episode-2-the-creation-of-graph-theory-34g1

  /articles/me:
    get:
      operationId: getUserArticles
      summary: User's articles
      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.
      tags:
        - articles
        - users
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of published articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/articles/me

  /articles/me/published:
    get:
      operationId: getUserPublishedArticles
      summary: User's published articles
      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.
      tags:
        - articles
        - users
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of published articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/articles/me/published

  /articles/me/unpublished:
    get:
      operationId: getUserUnpublishedArticles
      summary: User's unpublished articles
      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.
      tags:
        - articles
        - users
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/articles/me/unpublished

  /articles/me/all:
    get:
      operationId: getUserAllArticles
      summary: User's all articles
      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.
      tags:
        - articles
        - users
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/articles/me/all

  /comments:
    get:
      operationId: getCommentsByArticleId
      summary: Comments
      description: |
        This endpoint allows the client to retrieve all comments belonging to an
        article or podcast episode as threaded conversations.

        It will return the all top level comments with their nested comments as
        threads. See the format specification for further details.
      tags:
        - comments
      parameters:
        - name: a_id
          in: query
          description: Article identifier.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 270180
        - name: p_id
          in: query
          description: Podcast Episode identifier.
          schema:
            type: integer
            format: int32
            minimum: 1
          example: 124
      responses:
        "200":
          description: A list of threads of comments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Comment"
              examples:
                comments-success:
                  $ref: "#/components/examples/Comments"
                comments-success-deleted:
                  $ref: "#/components/examples/CommentsDeleted"
                comments-success-hidden:
                  $ref: "#/components/examples/CommentsHidden"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl (all comments of an article)
          source: |
            curl https://dev.to/api/comments?a_id=270180
        - lang: Shell
          label: curl (all comments of a podcast episode)
          source: |
            curl https://dev.to/api/comments?p_id=124

  /comments/{id}:
    get:
      operationId: getCommentById
      summary: Comment
      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.
      tags:
        - comments
      parameters:
        - name: id
          in: path
          required: true
          description: Comment identifier.
          schema:
            type: string
          example: m35m
      responses:
        "200":
          description: A comment and its descendants
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
              examples:
                comment-success:
                  $ref: "#/components/examples/Comment"
                comments-success-deleted:
                  $ref: "#/components/examples/CommentDeleted"
                comments-success-hidden:
                  $ref: "#/components/examples/CommentHidden"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl (a comment and its descendants)
          source: |
            curl https://dev.to/api/comments/m51e

  /followers/users:
    get:
      operationId: getFollowers
      summary: Followers
      description: |
        This endpoint allows the client to retrieve a list of the followers
        they have.

        "Followers" are users that are following other users on the website.

        It supports pagination, each page will contain `80` followers by default.
      tags:
        - followers
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam80to1000'
        - in: query
          name: sort
          schema:
            type: string
            default: 'created_at'
            pattern: '^-?\w+(,-?\w+)*$'
          required: false
          description: |
            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`.
      responses:
        "200":
          description: A list of followers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Follower"
              examples:
                followers-success:
                  $ref: "#/components/examples/Followers"

        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/followers/users

  /follows/tags:
    get:
      operationId: getFollowedTags
      summary: Followed tags
      description: |
        This endpoint allows the client to retrieve a list of the tags
        they follow.
      tags:
        - follows
        - tags
      responses:
        "200":
          description: A list of followed tags
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FollowedTag"
              examples:
                followers-success:
                  $ref: "#/components/examples/TagsFollowed"

        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/follows/tags

  /listings:
    get:
      operationId: getListings
      summary: Published listings
      description: |
        This endpoint allows the client to retrieve a list of listings.

        "Listings" are classified ads that users create on DEV.
        They can be related to conference announcements, job offers, mentorships,
        upcoming events and more.

        By default it will return published listings ordered by descending
        freshness.

        It supports pagination, each page will contain `30` articles by default.
      tags:
        - listings
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
        - $ref: '#/components/parameters/listingCategoryParam'
      responses:
        "200":
          description: A list of listings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Listing"
              examples:
                listings-success:
                  $ref: "#/components/examples/Listings"
      x-codeSamples:
        - lang: Shell
          label: curl (all listings)
          source: |
            curl https://dev.to/api/listings
    post:
      operationId: createListing
      summary: Create a new listing
      description: |
        This endpoint allows the client to create a new listing.

        "Listings" are classified ads that users create on DEV.
        They can be related to conference announcements, job offers, mentorships,
        upcoming events and more.

        The user creating the listing or the organization on which behalf the user
        is creating for need to have enough credits for this operation to be
        successful. The server will prioritize the organization's credits over
        the user's credits.

        ### Additional resources

        - [Rails tests for Listings API](https://github.com/forem/forem/blob/main/spec/requests/api/v0/listings_spec.rb)
      tags:
        - listings
      requestBody:
        description: Listing to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListingCreate"
            examples:
              listing-create:
                $ref: "#/components/examples/ListingCreate"
              listing-create-organization:
                $ref: "#/components/examples/ListingCreateOrganization"

      responses:
        "201":
          description: A newly created Listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Listing"
              examples:
                article-success:
                  $ref: "#/components/examples/Listing"
        "400":
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-bad-request:
                  $ref: "#/components/examples/ErrorBadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        "402":
          description: PaymentRequired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorPaymentRequired"
        "422":
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorUnprocessableEntity"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -X POST -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"listing":{"title":"Title","body_markdown":"Body","category":"cfp"}}' \
              https://dev.to/api/listings
        - lang: Shell
          label: curl (with tags)
          source: |
            curl -X POST -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"listing":{"title":"Title","body_markdown":"Body","category":"cfp","tags":["python"]}}' \
              https://dev.to/api/listings
        - lang: Shell
          label: curl (draft)
          source: |
            curl -X POST -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"listing":{"title":"Title","body_markdown":"Body","category":"cfp","action":"draft"}}' \
              https://dev.to/api/listings

  /listings/category/{category}:
    get:
      operationId: getListingsByCategory
      summary: Published listings by category
      description: |
        This endpoint allows the client to retrieve a list of listings belonging
        to the specified category.

        "Listings" are classified ads that users create on DEV.
        They can be related to conference announcements, job offers, mentorships,
        upcoming events and more.

        By default it will return published listings ordered by descending
        freshness.

        It supports pagination, each page will contain `30` articles by default.
      tags:
        - listings
      parameters:
        - name: category
          in: path
          required: true
          description: The category of the listing
          schema:
            $ref: "#/components/schemas/ListingCategory"
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of listings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Listing"
              examples:
                listings-success:
                  $ref: "#/components/examples/Listings"
      x-codeSamples:
        - lang: Shell
          label: curl (call for papers listings)
          source: |
            curl https://dev.to/api/listings/category/cfp

  /listings/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Id of the listing
        schema:
          type: integer
          format: int64
          minimum: 1
        example: 1
    get:
      operationId: getListingById
      summary: A listing
      description: |
        This endpoint allows the client to retrieve
        a single listing given its `id`.

        An unpublished listing is only accessible if authentication is supplied
        and it belongs to the authenticated user.
      tags:
        - listings
      responses:
        "200":
          description: A listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Listing"
              examples:
                article-success:
                  $ref: "#/components/examples/Listing"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      security:
        - {} # this indicates that authentication is optional
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/listings/1184
        - lang: Shell
          label: curl (with authentication)
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/listings/1185
    put:
      operationId: updateListing
      summary: Update a listing
      description: |
        This endpoint allows the client to update an existing listing.
      tags:
        - listings
      requestBody:
        description: |
          Listing params for the update.

          **Note**: except for bumping, publishing and unpublishing there are the
          following restrictions on the ability to update listings:

          - the payload has to contain at least one param among `title`, `body_markdown` or `tags`/`tag_list`
          - the listing can't be updated if it has not been bumped in the last 24 hours
          - the listing can't be updated if it has been published but not recently bumped
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListingUpdate"
            examples:
              listing-update-action-bump:
                $ref: "#/components/examples/ListingUpdateActionBump"
              listing-update-action-publish:
                $ref: "#/components/examples/ListingUpdateActionPublish"
              listing-update-action-unpublish:
                $ref: "#/components/examples/ListingUpdateActionUnpublish"
              listing-update:
                $ref: "#/components/examples/ListingUpdate"
      responses:
        "200":
          description: The updated article
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleShow"
              examples:
                article-success:
                  $ref: "#/components/examples/ArticleShow"
        "400":
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-bad-request:
                  $ref: "#/components/examples/ErrorBadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        "402":
          description: PaymentRequired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorPaymentRequired"
        "422":
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorUnprocessableEntity"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl (bump)
          source: |
            curl -X PUT -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"listing":{"action":"bump"}' \
              https://dev.to/api/listings/{id}
        - lang: Shell
          label: curl (update)
          source: |
            curl -X PUT -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"listing":{"title":"Title"}' \
              https://dev.to/api/listings/{id}

  /readinglist:
    get:
      operationId: getReadinglist
      summary: User's reading list
      description: |
        This endpoint allows the client to retrieve a list of readinglist reactions along with the related article for the authenticated user.

        Reading list will be in reverse chronological order base
        on the creation of the reaction.

        It will return paginated reading list items along with the articles
        they refer to. By default a page will contain `30` items
      tags:
        - readinglist
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to100'
      responses:
        "200":
          description: The reading list with a overview of the article
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ReadingList"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/readinglist

  /organizations/{username}:
    get:
      operationId: getOrganization
      summary: An organization
      description: |
        This endpoint allows the client to retrieve a single organization by their username
      tags:
        - organizations
      parameters:
        - name: username
          in: path
          required: true
          description: |
            Username of the organization
          schema:
            type: string
          example: "ecorp"
      responses:
        "200":
          description: An organization
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
              examples:
                user-success:
                  $ref: "#/components/examples/Organization"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                user-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/organizations/ecorp

  /organizations/{username}/users:
    get:
      operationId: getOrgUsers
      summary: Organization's users
      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.
      tags:
        - organizations
      parameters:
        - name: username
          in: path
          required: true
          description: |
            Username of the organization
          schema:
            type: string
          example: "ecorp"
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of users belonging to the organization
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
              examples:
                user-success:
                  $ref: "#/components/examples/Users"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                user-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/organizations/ecorp/users

  /organizations/{username}/listings:
    get:
      operationId: getOrgListings
      summary: Organization's listings
      description: |
        This endpoint allows the client to retrieve a list of listings belonging to the organization

        It supports pagination, each page will contain `30` listing by default.
      tags:
        - organizations
      parameters:
        - name: username
          in: path
          required: true
          description: |
            Username of the organization
          schema:
            type: string
          example: "ecorp"
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
        - $ref: '#/components/parameters/listingCategoryParam'
      responses:
        "200":
          description: A list of listings belonging to the organization
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/Listing"
                    - required:
                      - organization
              examples:
                user-success:
                  $ref: "#/components/examples/ListingsByOrganization"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                user-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/organizations/ecorp/listings

  /organizations/{username}/articles:
    get:
      operationId: getOrgArticles
      summary: Organization's Articles
      description: |
        This endpoint allows the client to retrieve a list of Articles belonging to the organization

        It supports pagination, each page will contain `30` articles by default.
      tags:
        - organizations
      parameters:
        - name: username
          in: path
          required: true
          description: |
            Username of the organization
          schema:
            type: string
          example: "ecorp"
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        "200":
          description: A list of articles belonging to the organization
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleIndex"
              examples:
                article-success:
                  $ref: "#/components/examples/ArticlesIndex"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                user-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/organizations/ecorp/articles

  /podcast_episodes:
    get:
      operationId: getPodcastEpisodes
      summary: Published podcast episodes
      description: |
        This endpoint allows the client to retrieve a list of podcast episodes.

        "Podcast episodes" are episodes belonging to podcasts.

        It will only return active 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.
      tags:
        - podcast-episodes
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam30to1000'
        - name: username
          in: query
          description: |
            Using this parameter will retrieve episodes belonging
            to a specific podcast.
          schema:
            type: string
          example: codenewbie
      responses:
        "200":
          description: A list of podcast episodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PodcastEpisode"
              examples:
                articles-success:
                  $ref: "#/components/examples/PodcastEpisodes"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl (all podcast episodes)
          source: |
            curl https://dev.to/api/podcast_episodes
        - lang: Shell
          label: curl (all episodes belonging to a podcast)
          source: |
            curl https://dev.to/api/podcast_episodes?username=codenewbie

  /tags:
    get:
      operationId: getTags
      summary: Tags
      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.
      tags:
        - tags
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam10to1000'
      responses:
        "200":
          description: A list of tags
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Tag"
              examples:
                articles-success:
                  $ref: "#/components/examples/Tags"
      x-codeSamples:
        - lang: Shell
          label: curl (all tags)
          source: |
            curl https://dev.to/api/tags

  /users/{id}:
    get:
      operationId: getUser
      summary: A user
      description: |
        This endpoint allows the client to retrieve a single user, either by
        id or by the user's username
      tags:
        - users
      parameters:
        - name: id
          in: path
          required: true
          description: |
            Id of the user.

            It can be either of the following two values:

              - an integer representing the id of the user
              - the string `by_username` (needs to be used in conjuction with the param `url`)
          schema:
            type: string
          example: "1"
        - name: url
          in: query
          description: Username of the user
          schema:
            type: string
          example: ben
      responses:
        "200":
          description: A user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              examples:
                user-success:
                  $ref: "#/components/examples/User"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                user-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl (by id)
          source: |
            curl https://dev.to/api/users/1
        - lang: Shell
          label: curl (by username)
          source: |
            curl https://dev.to/api/users/by_username?url=ben

  /users/me:
    get:
      operationId: getUserMe
      summary: The authenticated user
      description: |
        This endpoint allows the client to retrieve information
        about the authenticated user
      tags:
        - users
      responses:
        "200":
          description: A user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
              examples:
                user-success:
                  $ref: "#/components/examples/User"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/users/me

  /profile_images/{username}:
    get:
      operationId: getProfileImage
      summary: User or organization profile picture
      description: |
        This endpoint allows the client to retrieve a user or organization
        profile image information by its corresponding username
      tags:
        - profile images
      parameters:
        - name: username
          in: path
          required: true
          description: Username of the user or organization
          schema:
            type: string
          example: "diogoosorio"
      responses:
        "200":
          description: The profile image
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProfileImage"
              examples:
                profile-image-success:
                  $ref: "#/components/examples/ProfileImage"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                profile-image-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/profile_images/diogoosorio

  /videos:
    get:
      operationId: getArticlesWithVideo
      summary: Articles with a video
      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.
      tags:
        - articles
        - videos
      parameters:
        - $ref: '#/components/parameters/pageParam'
        - $ref: '#/components/parameters/perPageParam24to1000'
      responses:
        "200":
          description: A list of video articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleVideo"
              examples:
                articles-success:
                  $ref: "#/components/examples/ArticleVideo"
      x-codeSamples:
        - lang: Shell
          label: curl (all video articles)
          source: |
            curl https://dev.to/api/videos

  /admin/users:
    post:
      operationId: postAdminUsersCreate
      summary: Invites a user to the Forem Instance 
      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.
      tags:
        - users
      requestBody:
        description: Details of the user to be invited
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdminUserCreate"
      responses:
        "200":
          description: The invitation was created (no response body)
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      x-codeSamples:
        - lang: Shell
          label: curl (invite user)
          source: |
            curl -X POST -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"email": "test@example.com", "name": "Firstname Lastname"}' \
              https://dev.to/api/admin/users