openapi: "3.0.2"
info:
  title: DEV API (beta)
  description: Access DEV articles, comments and other resources via API
  version: "0.5.9"
  termsOfService: https://dev.to/terms
  contact:
    name: DEV Team
    url: https://dev.to/contact
    email: yo@dev.to
  x-logo: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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:
  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
        - positive_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
        readable_publish_date:
          type: string
        social_image:
          type: string
          format: url
        tag_list:
          type: array
          items:
            type: string
        tags:
          type: string
        slug:
          type: string
        path:
          type: string
          format: path
        url:
          type: string
          format: url
        canonical_url:
          type: string
          format: url
        comments_count:
          type: integer
          format: int32
        positive_reactions_count:
          type: integer
          format: int32
        created_at:
          type: string
          format: date-time
        edited_at:
          type: string
          format: date-time
        crossposted_at:
          type: string
          format: date-time
        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/ArticleUser"
        organization:
          $ref: "#/components/schemas/ArticleOrganization"
        flare_tag:
          $ref: "#/components/schemas/ArticleFlareTag"

    ArticleShow:
      type: object
      required:
        - type_of
        - id
        - title
        - description
        - cover_image
        - readable_publish_date
        - social_image
        - tag_list
        - tags
        - slug
        - path
        - url
        - canonical_url
        - comments_count
        - positive_reactions_count
        - 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
        readable_publish_date:
          type: string
        social_image:
          type: string
          format: url
        tag_list:
          type: string
        tags:
          type: array
          items:
            type: string
        slug:
          type: string
        path:
          type: string
          format: path
        url:
          type: string
          format: url
        canonical_url:
          type: string
          format: url
        comments_count:
          type: integer
          format: int32
        positive_reactions_count:
          type: integer
          format: int32
        created_at:
          type: string
          format: date-time
        edited_at:
          type: string
          format: date-time
        crossposted_at:
          type: string
          format: date-time
        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/ArticleUser"
        organization:
          $ref: "#/components/schemas/ArticleOrganization"
        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 JSON 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 JSON payload.*
              type: string
            published:
              description: |
                True to create a published article, false otherwise. Defaults to false
              type: boolean
            series:
              description: |
                Article series name.

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

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

    ArticleMe:
      type: object
      required:
        - type_of
        - id
        - title
        - description
        - cover_image
        - published
        - published_at
        - tag_list
        - slug
        - path
        - url
        - canonical_url
        - comments_count
        - positive_reactions_count
        - 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
        published:
          type: boolean
        published_at:
          type: string
          format: date-time
        tag_list:
          type: array
          items:
            type: string
        slug:
          type: string
        path:
          type: string
          format: path
        url:
          type: string
          format: url
        canonical_url:
          type: string
          format: url
        comments_count:
          type: integer
          format: int32
        positive_reactions_count:
          type: integer
          format: int32
        page_views_count:
          type: integer
          format: int32
        published_timestamp:
          description: Crossposting or published date time
          type: string
          format: date-time
        user:
          $ref: "#/components/schemas/ArticleUser"
        organization:
          $ref: "#/components/schemas/ArticleOrganization"
        flare_tag:
          $ref: "#/components/schemas/ArticleFlareTag"

    ArticleUser:
      description: The article's creator
      type: object
      properties:
        name:
          type: string
        username:
          type: string
        twitter_username:
          type: string
        github_username:
          type: string
        website_url:
          type: string
          format: url
        profile_image:
          description: Profile image (640x640)
          type: string
        profile_image_90:
          description: Profile image (90x90)
          type: string

    ArticleOrganization:
      description: The organization the article 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

    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

    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

    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/ArticleUser"

    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

  examples:
    ErrorBadRequest:
      value:
        error: bad request
        status: 400
    ErrorNotFound:
      value:
        error: not found
        status: 404
    ErrorUnauthorized:
      value:
        error: unauthorized
        status: 401
    ErrorUnprocessableEntity:
      value:
        error: "param is missing or the value is empty: article"
        status: 422
    ArticlesIndex:
      value:
        - type_of: article
          id: 194541
          title: There's a new DEV theme in town for all you 10x hackers out there (plus one
            actually useful new feature)
          description: ''
          cover_image: https://res.cloudinary.com/practicaldev/image/fetch/s--74Bl23tz--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://res.cloudinary.com/practicaldev/image/fetch/s--xU8cbIK4--/c_imagga_scale%2Cf_auto%2Cfl_progressive%2Ch_420%2Cq_auto%2Cw_1000/https://thepracticaldev.s3.amazonaws.com/i/8a39dzf3oovzc2snl7iv.png
          readable_publish_date: Oct 24
          social_image: https://res.cloudinary.com/practicaldev/image/fetch/s--SeMxdKIa--/c_imagga_scale,f_auto,fl_progressive,h_500,q_auto,w_1000/https://res.cloudinary.com/practicaldev/image/fetch/s--xU8cbIK4--/c_imagga_scale%2Cf_auto%2Cfl_progressive%2Ch_420%2Cq_auto%2Cw_1000/https://thepracticaldev.s3.amazonaws.com/i/8a39dzf3oovzc2snl7iv.png
          tag_list:
          - meta
          - changelog
          - css
          - ux
          tags: meta, changelog, css, ux
          slug: there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
          path: "/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk"
          url: https://dev.to/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
          canonical_url: https://dev.to/devteam/there-s-a-new-dev-theme-in-town-for-all-you-10x-hackers-out-there-plus-one-actually-useful-new-feature-2kgk
          comments_count: 37
          positive_reactions_count: 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
        positive_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
    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: users
    description: Users own resources that require authentication
  - 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.

        Each page will contain `30` articles.

        Responses, according to the combination of params, are cached for 24 hours.
      tags:
        - articles
      parameters:
        - name: page
          in: query
          description: |
            Pagination page.

            This param can be used in conjuction with all other params
            (except when asking for fresh and rising articles by themselves).
          schema:
            type: integer
            format: int32
          example: 1
        - name: tag
          in: query
          description: |
            Adding this parameter will return articles that contain the
            requested tag.

            This param can be used by itself, with `page` or with `top`.
          schema:
            type: string
          example: discuss
        - name: username
          in: query
          description: |
            Adding this parameter will return articles belonging to a User or Organization
            ordered by descending `published_at`.

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

            This param can be used by itself or only with `page` and `state`.
          schema:
            type: string
          example: ben
        - name: state
          in: query
          description: |
            Adding this will allow the client to check which articles are fresh or rising.

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

            This param can only be used by itself or with `username` if set to `all`.
          schema:
            type: string
          example: ben
        - name: top
          in: query
          description: |
            Adding this 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 only be used by itself or with `tag`.
          schema:
            type: integer
            format: int32
          example: 2
      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: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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 articles created each 30 seconds by the same user.

        ### Additional resources

        - [Rails tests for Articles API](https://github.com/thepracticaldev/dev.to/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"
        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: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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}:
    get:
      operationId: getArticleById
      summary: A published article
      description: |
        This endpoint allows the client to retrieve a single
        published article given its `id`.

        Responses are cached for 5 minutes.
      tags:
        - articles
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the article
          schema:
            type: integer
            format: int32
          example: 150589
      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: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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 updated 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 are no limits on the amount of updates.

        ### Additional resources

        - [Rails tests for Articles API](https://github.com/thepracticaldev/dev.to/blob/master/spec/requests/api/v0/articles_spec.rb)
      tags:
        - articles
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the article
          schema:
            type: integer
            format: int32
          example: 150589
      requestBody:
        description: |
          Article params to 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:
                type: object
                $ref: "#/components/schemas/ArticleShow"
              examples:
                article-success:
                  $ref: "#/components/examples/ArticleShow"
        400:
          description: BadRequest
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                error-bad-request:
                  $ref: "#/components/examples/ErrorBadRequest"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorUnprocessableEntity"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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/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:
        - name: page
          in: query
          description: Pagination page.
          schema:
            type: integer
            format: int32
          example: 1
        - name: per_page
          in: query
          description: Page size (defaults to 30 with a maximum of 1000).
          schema:
            type: integer
            format: int32
          example: 30
      responses:
        200:
          description: A list of published articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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:
        - name: page
          in: query
          description: Pagination page.
          schema:
            type: integer
            format: int32
          example: 1
        - name: per_page
          in: query
          description: Page size (defaults to 30 with a maximum of 1000).
          schema:
            type: integer
            format: int32
          example: 30
      responses:
        200:
          description: A list of published articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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:
        - name: page
          in: query
          description: Pagination page.
          schema:
            type: integer
            format: int32
          example: 1
        - name: per_page
          in: query
          description: Page size (defaults to 30 with a maximum of 1000).
          schema:
            type: integer
            format: int32
          example: 30
      responses:
        200:
          description: A list of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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:
        - name: page
          in: query
          description: Pagination page.
          schema:
            type: integer
            format: int32
          example: 1
        - name: per_page
          in: query
          description: Page size (defaults to 30 with a maximum of 1000).
          schema:
            type: integer
            format: int32
          example: 30
      responses:
        200:
          description: A list of articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ArticleMe"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#x-code-samples
        - lang: Shell
          label: curl
          source: |
            curl -H "api-key: API_KEY" https://dev.to/api/articles/me/all

  /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"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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:
                type: object
                $ref: "#/components/schemas/WebhookShow"
              examples:
                webhook-success:
                  $ref: "#/components/examples/WebhookShow"
        400:
          description: BadRequest
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                error-bad-request:
                  $ref: "#/components/examples/ErrorBadRequest"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                error-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                error-unprocessable-entity:
                  $ref: "#/components/examples/ErrorUnprocessableEntity"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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}:
    get:
      operationId: getWebhookById
      summary: A webhook endpoint
      description: |
        This endpoint allows the client to retrieve a single
        webhook given its `id`.
      tags:
        - webhooks
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the webhook
          schema:
            type: integer
            format: int32
          example: 123
      responses:
        200:
          description: A webhook endpoint
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/WebhookShow"
              examples:
                webhook-success:
                  $ref: "#/components/examples/WebhookShow"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                article-unauthorized:
                  $ref: "#/components/examples/ErrorUnauthorized"
        404:
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                $ref: "#/components/schemas/APIError"
              examples:
                article-not-found:
                  $ref: "#/components/examples/ErrorNotFound"
      security:
        - api_key: []
        - oauth2: []
      x-code-samples: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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
      parameters:
        - name: id
          in: path
          required: true
          description: Id of the webhook
          schema:
            type: integer
            format: int32
          example: 123
      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: # https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#x-code-samples
        - lang: Shell
          label: curl
          source: |
            curl -X DELETE \
              -H "api-key: API_KEY" \
              https://dev.to/api/webhooks/1
