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

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.

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

  version: "0.7.0"
  termsOfService: https://dev.to/terms
  contact:
    name: DEV Team
    url: https://dev.to/contact
    email: yo@dev.to
  x-logo:
    url: https://practicaldev-herokuapp-com.freetls.fastly.net/assets/devlogo-pwa-128-1a9016906487b8ba17f2d3d3c28f9d1cb3ae9b45d685cc2711e20f6b3c6730df.png
    backgroundColor: "#000"
    altText: "DEV 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
    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

  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.

        ### Getting an API key

        To obtain one, please follow these steps:

          - visit https://dev.to/settings/account
          - 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/146201/64421366-af3f8b00-d0a1-11e9-8ff6-7cc0ca6e854e.png)
          - You'll see the newly generated key in the same view
            ![generated DEV API Key](https://user-images.githubusercontent.com/146201/64421367-af3f8b00-d0a1-11e9-9831-73d3bdfdff66.png)
      name: api-key
      in: header
    oauth2:
      type: oauth2
      description: |
        OAuth2 authentication.

        OAuth2 authentication is still in private alpha.
      flows:
        authorizationCode:
          authorizationUrl: https://dev.to/oauth/authorize
          tokenUrl: https://dev.to/oauth/token
          refreshUrl: https://dev.to/oauth/token
          scopes: {}
        clientCredentials:
          tokenUrl: https://dev.to/oauth/token
          refreshUrl: https://dev.to/oauth/token
          scopes: {}

  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
        - public_reactions_count
        - created_at
        - edited_at
        - crossposted_at
        - published_at
        - last_comment_at
        - published_timestamp
        - user
      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
        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"
        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
        - public_reactions_count
        - created_at
        - edited_at
        - crossposted_at
        - published_at
        - last_comment_at
        - published_timestamp
        - body_html
        - body_markdown
        - user
      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
        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"
        organization:
          $ref: "#/components/schemas/SharedOrganization"
        flare_tag:
          $ref: "#/components/schemas/ArticleFlareTag"

    ArticleCreate:
      type: object
      properties:
        article:
          type: object
          required:
            - title
          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
        - public_reactions_count
        - page_views_count
        - published_timestamp
        - body_markdown
        - user
      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
        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"
        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
        - 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
        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"

    Follower:
      type: object
      required:
        - type_of
        - id
        - name
        - path
        - username
        - profile_image
      properties:
        type_of:
          type: string
        id:
          description: Follow 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]

    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:
        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

    WebhookCreate:
      description: Webhook creation payload
      type: object
      properties:
        webhook_endpoint:
          type: object
          required:
            - source
            - target_url
            - events
          properties:
            source:
              description: The name of the requester, eg. "DEV"
              type: string
            target_url:
              type: string
              format: url
            events:
              description: An array of events identifiers
              type: array
              items:
                type: string

    WebhookIndex:
      description: Webhook
      type: object
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int64
        source:
          description: The name of the requester, eg. "DEV"
          type: string
        target_url:
          type: string
          format: url
        events:
          description: An array of events identifiers
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time

    WebhookShow:
      description: Webhook
      type: object
      properties:
        type_of:
          type: string
        id:
          type: integer
          format: int64
        source:
          description: The name of the requester, eg. "DEV"
          type: string
        target_url:
          type: string
          format: url
        events:
          description: An array of events identifiers
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        user:
          $ref: "#/components/schemas/SharedUser"

  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
          public_reactions_count: 142
          collection_id:
          created_at: '2019-10-24T13:41:29Z'
          edited_at: '2019-10-24T13:56:35Z'
          crossposted_at:
          published_at: '2019-10-24T13:52:17Z'
          last_comment_at: '2019-10-25T08:12:43Z'
          published_timestamp: '2019-10-24T13:52:17Z'
          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
        public_reactions_count: 322
        collection_id: 1693
        created_at: "2019-07-31T11:15:06Z"
        edited_at:
        crossposted_at:
        published_at: "2019-08-01T15:47:54Z"
        last_comment_at: "2019-08-06T16:48:10Z"
        published_timestamp: "2019-08-01T15:47:54Z"
        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
          canonical_url: https://example.com/blog/hello
    ArticleCreateFrontMatter:
      value:
        article:
          body_markdown: |
            ---
            title: Hello, World!
            published: true
            tags: discuss, help
            date: 20190701T10:00Z
            series: Hello series
            canonical_url: https://example.com/blog/hello
            ---

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

            <p>...</p>

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

              <p>...</p>

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

              <p>...</p>

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

              <p>...</p>

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

          <p>...</p>

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

            <p>...</p>

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

            <p>...</p>

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

            <p>...</p>

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

    Followers:
      value:
        - type_of: user_follower
          id: 12
          name: Mrs. Neda Morissette
          path: "/nedamrsmorissette"
          username: nedamrsmorissette
          profile_image: https://res.cloudinary.com/...
        - type_of: user_follower
          id: 11
          name: Yoko Hintz
          path: "/yokohintz"
          username: yokohintz
          profile_image: https://res.cloudinary.com/...

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

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

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

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

    Tags:
      value:
        - id: 6
          name: javascript
          bg_color_hex: "#F7DF1E"
          text_color_hex: "#000000"
        - id: 8
          name: webdev
          bg_color_hex: "#562765"
          text_color_hex: "#ffffff"

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

    WebhookCreate:
      value:
        webhook_endpoint:
          target_url: https://example.com/webhooks/webhook1
          source: DEV
          events:
            - article_created
    WebhookShow:
      value:
        type_of: webhook_endpoint
        id: 1
        source: DEV
        target_url: https://example.com/webhooks/webhook1
        events:
          - article_created
        created_at: "2019-09-02T09:47:39.230Z"
        user:
          name: bob
          username: bob
          twitter_username:
          github_username: bob
          website_url:
          profile_image: "..."
          profile_image_90: "..."

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: followers
    description: Users can follow other users on the website
  - name: listings
    description: Listings are classified ads
  - name: podcast-episodes
    description: Podcast episodes
  - name: tags
    description: Tags for articles
  - name: users
    description: Users own resources that require authentication
  - name: videos
    description: Video articles
  - name: webhooks
    description: Webhooks are HTTP endpoints registered to receive events

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: 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-code-samples:
        - 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/master/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: []
        - oauth2: []
      x-code-samples:
        - 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/{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-code-samples:
        - 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/master/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: []
        - oauth2: []
      x-code-samples:
        - 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-code-samples:
        - 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: []
        - oauth2: []
      x-code-samples:
        - 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: []
        - oauth2: []
      x-code-samples:
        - 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: []
        - oauth2: []
      x-code-samples:
        - 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: []
        - oauth2: []
      x-code-samples:
        - 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-code-samples:
        - 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-code-samples:
        - 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'
      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-code-samples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/followers/users

  /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'
        - name: category
          in: query
          description: |
            Using this parameter will return listings belonging to the
            requested category.
          schema:
            type: string
          example: cfp
      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-code-samples:
        - 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 creadits 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/master/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-code-samples:
        - 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-code-samples:
        - lang: Shell
          label: curl (call for papers listings)
          source: |
            curl https://dev.to/api/listings/category/cfp

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

        An unpublished listing is only accessible if authentication is supplied
        and it belongs to the authenticated user.
      tags:
        - listings
      responses:
        "200":
          description: A listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Listing"
              examples:
                article-success:
                  $ref: "#/components/examples/Listing"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      security:
        - {} # this indicates that authentication is optional
        - api_key: []
      x-code-samples:
        - 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-code-samples:
        - 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}

  /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-code-samples:
        - 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-code-samples:
        - 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-code-samples:
        - 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: []
        - oauth2: []
      x-code-samples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/users/me

  /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-code-samples:
        - lang: Shell
          label: curl (all video articles)
          source: |
            curl https://dev.to/api/videos

  /webhooks:
    get:
      operationId: getWebhooks
      summary: Webhooks
      description: |
        This endpoint allows the client to retrieve a list of webhooks they have
        previously registered.

        "Webhooks" are used to register HTTP endpoints that will be called once a relevant event is
        triggered inside the web application, events like `article_created`, `article_updated`.

        It will return all webhooks, without pagination.
      tags:
        - webhooks
      responses:
        "200":
          description: A list of webhooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WebhookIndex"
              examples:
                webhooks-success:
                  summary: Successful response
                  value:
                    - type_of: webhook_endpoint
                      id: 1
                      source: DEV
                      target_url: https://example.com/webhooks/webhook1
                      events:
                        - article_created
                      created_at: "2019-09-02T09:47:39.230Z"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples:
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/webhooks
    post:
      operationId: createWebhook
      summary: Create a new webhook
      description: |
        This endpoint allows the client to create a new webhook.

        "Webhooks" are used to register HTTP endpoints that will be called once a relevant event is
        triggered inside the web application, events like `article_created`, `article_updated`.
      tags:
        - webhooks
      requestBody:
        description: Webhook to create
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookCreate"
            examples:
              webhook-create:
                $ref: "#/components/examples/WebhookCreate"

      responses:
        "201":
          description: A newly created webhook
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookShow"
              examples:
                webhook-success:
                  $ref: "#/components/examples/WebhookShow"
        "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"
        "422":
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorUnprocessableEntity"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples:
        - lang: Shell
          label: curl
          source: |
            curl -X POST -H "Content-Type: application/json" \
              -H "api-key: API_KEY" \
              -d '{"webhook_endpoint":{"target_url":"https://example.org/webhooks/webhook1","source":"DEV","events":["article_created"]}}' \
              https://dev.to/api/webhooks

  /webhooks/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Id of the webhook
        schema:
          type: integer
          format: int64
          minimum: 1
        example: 123
    get:
      operationId: getWebhookById
      summary: A webhook endpoint
      description: |
        This endpoint allows the client to retrieve a single
        webhook given its `id`.
      tags:
        - webhooks
      responses:
        "200":
          description: A webhook endpoint
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookShow"
              examples:
                webhook-success:
                  $ref: "#/components/examples/WebhookShow"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples:
        - lang: Shell
          label: curl
          source: |
            curl https://dev.to/api/webhooks/123
    delete:
      operationId: deleteWebhook
      summary: A webhook endpoint
      description: |
        This endpoint allows the client to delete a single
        webhook given its `id`.
      tags:
        - webhooks
      responses:
        "204":
          description: A successful deletion
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        "404":
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples:
        - lang: Shell
          label: curl
          source: |
            curl -X DELETE \
              -H "api-key: API_KEY" \
              https://dev.to/api/webhooks/1