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: null
          created_at: '2019-10-24T13:41:29Z'
          edited_at: '2019-10-24T13:56:35Z'
          crossposted_at: null
          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: null
        crossposted_at: null
        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: null
            github_username: null
            website_url: null
            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: null
            github_username: null
            user_id: 7707
            website_url: null
            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: null
                github_username: null
                user_id: 819
                website_url: null
                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: null
                github_username: null
                website_url: null
                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: null
                github_username: null
                website_url: null
                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: null
          github_username: null
          website_url: null
          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: null
              github_username: null
              website_url: null
              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: null
              github_username: null
              website_url: null
              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: null
              github_username: null
              website_url: null
              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! 


            https://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: null
            github_username: Heather-R
            website_url: null
            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! 


            https://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: null
            github_username: Heather-R
            website_url: null
            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! 


          https://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: null
          github_username: Heather-R
          website_url: null
          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: null
        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: null
          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: null
        story: null
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:
        - {}
        - 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
