openapi: 3.1.0
info:
  title: Dev.to Forem Articles Pages 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: Pages
  description: Endpoints for managing static pages on the platform. Requires admin-level API key.
paths:
  /pages:
    get:
      operationId: getPages
      summary: Show details for all pages
      description: Retrieves all static pages on the platform. Requires admin-level API key.
      tags:
      - Pages
      responses:
        '200':
          description: A list of pages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Page'
        '401':
          description: Unauthorized
    post:
      operationId: createPage
      summary: Create a new page
      description: Creates a new static page. Requires admin-level API key.
      tags:
      - Pages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Page'
      responses:
        '201':
          description: Page created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable Entity
  /pages/{id}:
    get:
      operationId: getPageById
      summary: Show details for a page
      description: Retrieves a single static page by ID. Requires admin-level API key.
      tags:
      - Pages
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the page.
      responses:
        '200':
          description: The requested page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          description: Unauthorized
        '404':
          description: Page not found
    put:
      operationId: updatePage
      summary: Update details for a page
      description: Updates an existing static page. Requires admin-level API key.
      tags:
      - Pages
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Page'
      responses:
        '200':
          description: Page updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          description: Unauthorized
        '404':
          description: Page not found
        '422':
          description: Unprocessable Entity
    delete:
      operationId: deletePage
      summary: Remove a page
      description: Deletes a static page by ID. Requires admin-level API key.
      tags:
      - Pages
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the page.
      responses:
        '204':
          description: Page deleted
        '401':
          description: Unauthorized
        '404':
          description: Page not found
components:
  schemas:
    Page:
      type: object
      description: A static page on the platform, managed by administrators.
      properties:
        id:
          type: integer
          description: The unique identifier of the page.
        title:
          type: string
          description: The title of the page.
        slug:
          type: string
          description: The URL slug of the page.
        description:
          type: string
          description: A description of the page.
        body_markdown:
          type: string
          description: The page content in Markdown format.
        body_json:
          type: string
          nullable: true
          description: The page content in JSON format, if applicable.
        is_top_level_path:
          type: boolean
          description: Whether the page is accessible at a top-level URL path.
        social_image:
          type: object
          nullable: true
          description: Social image configuration for the page.
        template:
          type: string
          description: The template used to render the page.
  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