openapi: 3.1.0
info:
  title: Dev.to Forem Articles API
  description: The Dev.to Forem API (v1) is a RESTful API that provides programmatic access to the Dev.to developer community platform, which is built on the open-source Forem framework. The API enables developers to create, read, update, and manage articles, comments, users, organizations, tags, followers, listings, podcast episodes, pages, display ads, reactions, reading lists, and webhooks. It uses API key authentication, requires an accept header of application/vnd.forem.api-v1+json, and returns JSON responses. Unauthenticated endpoints are CORS-enabled, making it possible to fetch public content directly from browser-based applications.
  version: 1.0.0
  contact:
    name: Forem Support
    url: https://forem.com
  termsOfService: https://dev.to/terms
servers:
- url: https://dev.to/api
  description: Dev.to Production Server
security:
- apiKey: []
tags:
- name: Articles
  description: Endpoints for creating, reading, updating, and managing articles (blog posts, discussions, help threads) on the platform.
paths:
  /articles:
    post:
      operationId: createArticle
      summary: Publish article
      description: Creates a new article. The authenticated user will be the author of the article. The article can be published immediately or saved as a draft by setting the published field.
      tags:
      - Articles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                article:
                  type: object
                  properties:
                    title:
                      type: string
                      description: The title of the article.
                    body_markdown:
                      type: string
                      description: The body of the article in Markdown format.
                    published:
                      type: boolean
                      description: Whether the article should be published immediately.
                    series:
                      type: string
                      description: The name of a series to associate this article with.
                    main_image:
                      type: string
                      format: uri
                      description: URL for the main cover image of the article.
                    canonical_url:
                      type: string
                      format: uri
                      description: The canonical URL for the article if originally published elsewhere.
                    description:
                      type: string
                      description: A brief description or subtitle for the article.
                    tags:
                      type: array
                      items:
                        type: string
                      maxItems: 4
                      description: Up to four tags for the article.
                    organization_id:
                      type: integer
                      description: The organization ID to publish the article under.
                  required:
                  - title
      responses:
        '201':
          description: Article created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '401':
          description: Unauthorized - invalid or missing API key
        '422':
          description: Unprocessable Entity - validation errors
    get:
      operationId: getArticles
      summary: Published articles
      description: Retrieves a list of published articles, ordered by descending popularity. This endpoint is publicly accessible and can be filtered by tag, username, state, and other parameters.
      tags:
      - Articles
      security: []
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      - name: tag
        in: query
        schema:
          type: string
        description: Filter articles by a single tag name.
      - name: tags
        in: query
        schema:
          type: string
        description: Filter articles by a comma-separated list of tag names (articles must have all specified tags).
      - name: tags_exclude
        in: query
        schema:
          type: string
        description: Exclude articles with these comma-separated tag names.
      - name: username
        in: query
        schema:
          type: string
        description: Filter articles by the author's username.
      - name: state
        in: query
        schema:
          type: string
          enum:
          - fresh
          - rising
          - all
        description: Filter articles by state. Defaults to the most popular articles.
      - name: top
        in: query
        schema:
          type: integer
        description: Return the most popular articles published in the last N days.
      - name: collection_id
        in: query
        schema:
          type: integer
        description: Return articles belonging to the specified collection.
      responses:
        '200':
          description: A list of published articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
  /articles/latest:
    get:
      operationId: getLatestArticles
      summary: Published articles sorted by published date
      description: Retrieves a list of published articles sorted by publication date in descending order.
      tags:
      - Articles
      security: []
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A list of articles sorted by publication date
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
  /articles/{id}:
    get:
      operationId: getArticleById
      summary: Published article by id
      description: Retrieves a single published article by its numeric ID.
      tags:
      - Articles
      security: []
      parameters:
      - $ref: '#/components/parameters/articleIdParam'
      responses:
        '200':
          description: The requested article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '404':
          description: Article not found
    put:
      operationId: updateArticle
      summary: Update an article by id
      description: Updates an existing article. Only the article's author or an admin can update the article.
      tags:
      - Articles
      parameters:
      - $ref: '#/components/parameters/articleIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                article:
                  type: object
                  properties:
                    title:
                      type: string
                      description: The title of the article.
                    body_markdown:
                      type: string
                      description: The body of the article in Markdown format.
                    published:
                      type: boolean
                      description: Whether the article should be published.
                    series:
                      type: string
                      description: The name of a series to associate this article with.
                    main_image:
                      type: string
                      format: uri
                      description: URL for the main cover image of the article.
                    canonical_url:
                      type: string
                      format: uri
                      description: The canonical URL for the article.
                    description:
                      type: string
                      description: A brief description or subtitle for the article.
                    tags:
                      type: array
                      items:
                        type: string
                      maxItems: 4
                      description: Up to four tags for the article.
                    organization_id:
                      type: integer
                      description: The organization ID to publish the article under.
      responses:
        '200':
          description: Article updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '401':
          description: Unauthorized
        '404':
          description: Article not found
        '422':
          description: Unprocessable Entity
  /articles/{username}/{slug}:
    get:
      operationId: getArticleByPath
      summary: Published article by path
      description: Retrieves a single published article by the author's username and the article's slug.
      tags:
      - Articles
      security: []
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
        description: The username of the article's author.
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: The slug of the article.
      responses:
        '200':
          description: The requested article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '404':
          description: Article not found
  /articles/me:
    get:
      operationId: getUserArticles
      summary: User's articles
      description: Retrieves all articles authored by the authenticated user.
      tags:
      - Articles
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A list of the authenticated user's articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
  /articles/me/published:
    get:
      operationId: getUserPublishedArticles
      summary: User's published articles
      description: Retrieves only published articles authored by the authenticated user.
      tags:
      - Articles
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A list of the authenticated user's published articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
  /articles/me/unpublished:
    get:
      operationId: getUserUnpublishedArticles
      summary: User's unpublished articles
      description: Retrieves only unpublished (draft) articles authored by the authenticated user.
      tags:
      - Articles
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A list of the authenticated user's unpublished articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
  /articles/me/all:
    get:
      operationId: getUserAllArticles
      summary: User's all articles
      description: Retrieves all articles (both published and unpublished) authored by the authenticated user.
      tags:
      - Articles
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A list of all the authenticated user's articles
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '401':
          description: Unauthorized
  /articles/{id}/unpublish:
    put:
      operationId: unpublishArticle
      summary: Unpublish an article
      description: Unpublishes an article by its ID. Requires admin-level API key.
      tags:
      - Articles
      parameters:
      - $ref: '#/components/parameters/articleIdParam'
      responses:
        '204':
          description: Article unpublished successfully
        '401':
          description: Unauthorized
        '404':
          description: Article not found
  /organizations/{username}/articles:
    get:
      operationId: getOrgArticles
      summary: Organization's Articles
      description: Retrieves a list of articles published under the specified organization.
      tags:
      - Articles
      security: []
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
        description: The username (slug) of the organization.
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam30to1000'
      responses:
        '200':
          description: A list of articles from the organization
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleIndex'
        '404':
          description: Organization not found
components:
  parameters:
    articleIdParam:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: The numeric ID of the article.
    pageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Pagination page number.
    perPageParam30to1000:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 30
      description: Number of items per page (max 1000, default 30).
  schemas:
    Organization:
      type: object
      description: An organization on the DEV platform that can publish articles and have members.
      properties:
        name:
          type: string
          description: The display name of the organization.
        username:
          type: string
          description: The unique username (slug) of the organization.
        slug:
          type: string
          description: The URL slug of the organization.
        profile_image:
          type: string
          format: uri
          description: The URL of the organization's profile image.
        profile_image_90:
          type: string
          format: uri
          description: The URL of the 90px profile image.
    ArticleIndex:
      type: object
      description: A summary article object returned in list endpoints, with fewer fields than the full article representation.
      properties:
        type_of:
          type: string
          description: The type of resource, always "article".
        id:
          type: integer
          description: The unique identifier of the article.
        title:
          type: string
          description: The title of the article.
        description:
          type: string
          description: A short description or subtitle for the article.
        readable_publish_date:
          type: string
          description: The publish date in a human-readable format.
        slug:
          type: string
          description: The URL slug of the article.
        path:
          type: string
          description: The relative path to the article on DEV.
        url:
          type: string
          format: uri
          description: The full URL of the article.
        comments_count:
          type: integer
          description: The number of comments on the article.
        public_reactions_count:
          type: integer
          description: The total number of public reactions.
        collection_id:
          type: integer
          nullable: true
          description: The ID of the collection (series) the article belongs to.
        published_timestamp:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the article was published.
        positive_reactions_count:
          type: integer
          description: The count of positive reactions.
        cover_image:
          type: string
          format: uri
          nullable: true
          description: The URL of the article's cover image.
        social_image:
          type: string
          format: uri
          description: The URL of the social sharing image.
        canonical_url:
          type: string
          format: uri
          description: The canonical URL of the article.
        created_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the article was created.
        reading_time_minutes:
          type: integer
          description: The estimated reading time in minutes.
        tag_list:
          type: array
          items:
            type: string
          description: A list of tags associated with the article.
        tags:
          type: string
          description: A comma-separated string of tags.
        user:
          $ref: '#/components/schemas/User'
        organization:
          $ref: '#/components/schemas/Organization'
    User:
      type: object
      description: A user account on the DEV platform.
      properties:
        name:
          type: string
          description: The display name of the user.
        username:
          type: string
          description: The unique username of the user.
        twitter_username:
          type: string
          nullable: true
          description: The user's Twitter username.
        github_username:
          type: string
          nullable: true
          description: The user's GitHub username.
        user_id:
          type: integer
          description: The unique numeric ID of the user.
        website_url:
          type: string
          format: uri
          nullable: true
          description: The user's website URL.
        location:
          type: string
          nullable: true
          description: The user's location.
        summary:
          type: string
          nullable: true
          description: A brief bio or summary of the user.
        profile_image:
          type: string
          format: uri
          description: The URL of the user's profile image.
        profile_image_90:
          type: string
          format: uri
          description: The URL of the 90px profile image.
        joined_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the user joined.
    Article:
      type: object
      description: A full article object with all detail fields, returned when retrieving a single article.
      properties:
        type_of:
          type: string
          description: The type of resource, always "article".
        id:
          type: integer
          description: The unique identifier of the article.
        title:
          type: string
          description: The title of the article.
        description:
          type: string
          description: A short description or subtitle for the article.
        readable_publish_date:
          type: string
          description: The publish date in a human-readable format.
        slug:
          type: string
          description: The URL slug of the article.
        path:
          type: string
          description: The relative path to the article on DEV.
        url:
          type: string
          format: uri
          description: The full URL of the article.
        comments_count:
          type: integer
          description: The number of comments on the article.
        public_reactions_count:
          type: integer
          description: The total number of public reactions on the article.
        collection_id:
          type: integer
          nullable: true
          description: The ID of the collection (series) the article belongs to.
        published_timestamp:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the article was published.
        positive_reactions_count:
          type: integer
          description: The count of positive reactions on the article.
        cover_image:
          type: string
          format: uri
          nullable: true
          description: The URL of the article's cover image.
        social_image:
          type: string
          format: uri
          description: The URL of the social sharing image.
        canonical_url:
          type: string
          format: uri
          description: The canonical URL if the article was originally published elsewhere.
        created_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the article was created.
        edited_at:
          type: string
          format: date-time
          nullable: true
          description: The ISO 8601 timestamp when the article was last edited.
        crossposted_at:
          type: string
          format: date-time
          nullable: true
          description: The ISO 8601 timestamp when the article was crossposted.
        published_at:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the article was published.
        last_comment_at:
          type: string
          format: date-time
          nullable: true
          description: The ISO 8601 timestamp of the last comment.
        reading_time_minutes:
          type: integer
          description: The estimated reading time in minutes.
        tag_list:
          type: array
          items:
            type: string
          description: A list of tags associated with the article.
        tags:
          type: string
          description: A comma-separated string of tags.
        body_html:
          type: string
          description: The article body rendered as HTML.
        body_markdown:
          type: string
          description: The article body in the original Markdown format.
        user:
          $ref: '#/components/schemas/User'
        organization:
          $ref: '#/components/schemas/Organization'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: api-key
      description: API key obtained from the DEV.to settings page. Pass in the api-key header for authenticated requests.
externalDocs:
  description: Forem API V1 Documentation
  url: https://developers.forem.com/api/v1