openapi: 3.2.0
info:
  title: Dev.to Forem Display Ads 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.
  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: Display Ads
  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:
      - Display Ads
      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:
      - Display Ads
      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:
      - Display Ads
      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:
      - Display Ads
      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:
      - Display Ads
      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