openapi: 3.1.0
info:
  title: Dev.to Forem Articles DisplayAds 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: DisplayAds
  description: Endpoints for managing display advertisements on the platform. Requires admin-level API key.
paths:
  /display_ads:
    get:
      operationId: getDisplayAds
      summary: Display ads
      description: Retrieves all display ads. Requires admin-level API key.
      tags:
      - DisplayAds
      responses:
        '200':
          description: A list of display ads
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DisplayAd'
        '401':
          description: Unauthorized
    post:
      operationId: createDisplayAd
      summary: Create display ad
      description: Creates a new display ad. Requires admin-level API key.
      tags:
      - DisplayAds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisplayAd'
      responses:
        '201':
          description: Display ad created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayAd'
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable Entity
  /display_ads/{id}:
    get:
      operationId: getDisplayAdById
      summary: Display ad
      description: Retrieves a single display ad by ID. Requires admin-level API key.
      tags:
      - DisplayAds
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the display ad.
      responses:
        '200':
          description: The requested display ad
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayAd'
        '401':
          description: Unauthorized
        '404':
          description: Display ad not found
    put:
      operationId: updateDisplayAd
      summary: Update display ad
      description: Updates an existing display ad. Requires admin-level API key.
      tags:
      - DisplayAds
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the display ad.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisplayAd'
      responses:
        '200':
          description: Display ad updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayAd'
        '401':
          description: Unauthorized
        '404':
          description: Display ad not found
        '422':
          description: Unprocessable Entity
  /display_ads/{id}/unpublish:
    put:
      operationId: unpublishDisplayAd
      summary: Unpublish display ad
      description: Unpublishes a display ad by ID. Requires admin-level API key.
      tags:
      - DisplayAds
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the display ad.
      responses:
        '204':
          description: Display ad unpublished
        '401':
          description: Unauthorized
        '404':
          description: Display ad not found
components:
  schemas:
    DisplayAd:
      type: object
      description: A display advertisement on the platform.
      properties:
        id:
          type: integer
          description: The unique identifier of the display ad.
        name:
          type: string
          description: The name of the display ad.
        body_markdown:
          type: string
          description: The ad content in Markdown format.
        approved:
          type: boolean
          description: Whether the ad has been approved for display.
        published:
          type: boolean
          description: Whether the ad is currently published.
        organization_id:
          type: integer
          nullable: true
          description: The organization ID the ad belongs to.
        placement_area:
          type: string
          description: Where on the page the ad should be displayed.
        tag_list:
          type: string
          description: Comma-separated tags for targeting the ad.
        display_to:
          type: string
          enum:
          - all
          - logged_in
          - logged_out
          description: Who should see the ad.
        type_of:
          type: string
          description: The type of display ad (e.g. in_house, community, external).
  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