openapi: 3.2.0
info:
  title: Forem API V1 Analytics API
  version: 1.0.0
  description: Access Forem articles, users and other resources via API.
servers:
- url: https://dev.to
  description: Production server
security:
- api-key: []
- bearer_auth: []
tags:
- name: Analytics
paths:
  /api/analytics/totals:
    get:
      summary: Retrieve analytics totals
      tags:
      - Analytics
      description: 'Retrieve aggregated lifetime stats (views, reactions, comments) for articles.


        ### Scope Control:

        - Specify `article_id` to query a single post''s metrics.

        - Specify `organization_id` to retrieve metrics across all articles owned by the target organization.'
      parameters:
      - name: article_id
        in: query
        required: false
        description: Optional ID to limit totals to a single article.
        schema:
          type: integer
      - name: organization_id
        in: query
        required: false
        description: Optional ID to limit totals to an organization's articles.
        schema:
          type: integer
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsTotals
      x-operation-id-source: derived
  /api/analytics/historical:
    get:
      summary: Retrieve historical analytics
      tags:
      - Analytics
      description: 'Retrieve historical analytics data graphed over a time range.


        ### Time Range Formats:

        - **start**: Start date (e.g. `2024-01-01`). Required.

        - **end**: End date (e.g. `2024-01-31`). Defaults to current date if omitted.'
      parameters:
      - name: start
        in: query
        required: true
        description: Start date (YYYY-MM-DD format).
        schema:
          type: string
        example: '2024-01-01'
      - name: end
        in: query
        required: false
        description: End date (YYYY-MM-DD format).
        schema:
          type: string
        example: '2024-01-31'
      - name: article_id
        in: query
        required: false
        description: Limit stats to a single article.
        schema:
          type: integer
      - name: organization_id
        in: query
        required: false
        description: Limit stats to an organization's articles.
        schema:
          type: integer
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsHistorical
      x-operation-id-source: derived
  /api/analytics/past_day:
    get:
      summary: Retrieve analytics for the past day
      tags:
      - Analytics
      description: Retrieve real-time hourly analytics statistics for the last 24 hours. Used for live graphs.
      parameters:
      - name: article_id
        in: query
        required: false
        schema:
          type: integer
      - name: organization_id
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsPastDay
      x-operation-id-source: derived
  /api/analytics/referrers:
    get:
      summary: Retrieve referrer analytics
      tags:
      - Analytics
      description: Retrieve traffic referring domains and URL source tracking metrics for articles.
      parameters:
      - name: start
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-01'
      - name: end
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-31'
      - name: article_id
        in: query
        required: false
        schema:
          type: integer
      - name: organization_id
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsReferrers
      x-operation-id-source: derived
  /api/analytics/top_contributors:
    get:
      summary: Retrieve top contributors analytics
      tags:
      - Analytics
      description: Retrieve top organization contributors ordered by article engagement scores.
      parameters:
      - name: start
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-01'
      - name: end
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-31'
      - name: article_id
        in: query
        required: false
        schema:
          type: integer
      - name: organization_id
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsTopContributors
      x-operation-id-source: derived
  /api/analytics/follower_engagement:
    get:
      summary: Retrieve follower engagement analytics
      tags:
      - Analytics
      description: Retrieve stats detailing new follower growth and engagement over time.
      parameters:
      - name: start
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-01'
      - name: end
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-31'
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsFollowerEngagement
      x-operation-id-source: derived
  /api/analytics/dashboard:
    get:
      summary: Retrieve dashboard analytics bundle
      tags:
      - Analytics
      description: Retrieve a complete bundled metrics package (totals, history, top posts) for rendering dashboard landing pages.
      parameters:
      - name: start
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-01'
      - name: end
        in: query
        required: false
        schema:
          type: string
        example: '2024-01-31'
      - name: article_id
        in: query
        required: false
        schema:
          type: integer
      - name: organization_id
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsDashboard
      x-operation-id-source: derived
  /api/analytics/heatmap:
    get:
      summary: Retrieve heatmap activity
      tags:
      - Analytics
      description: Retrieve user activity heatmap metrics (commits, posts, reactions) grouped by weekdays and hours.
      parameters:
      - name: end
        in: query
        required: false
        schema:
          type: string
        example: '2024-12-31'
      responses:
        '200':
          description: successful
      operationId: getApiAnalyticsHeatmap
      x-operation-id-source: derived
components:
  securitySchemes:
    api-key:
      type: apiKey
      name: api-key
      in: header
      description: "API Key authentication.\n\nAuthentication for some endpoints, like write operations on the\nArticles API require a DEV API key.\n\nAll authenticated endpoints are CORS disabled, the API key is intended for non-browser scripts.\n\n### Getting an API key\n\nTo obtain one, please follow these steps:\n\n  - visit https://dev.to/settings/extensions\n  - in the \"DEV API Keys\" section create a new key by adding a\n    description and clicking on \"Generate API Key\"\n\n    ![obtain a DEV API Key](https://user-images.githubusercontent.com/37842/172718105-bd93664e-76e0-477d-99c4-265dda0b06c5.png)\n\n  - You'll see the newly generated key in the same view\n    ![generated DEV API Key](https://user-images.githubusercontent.com/37842/172718151-e7fe26a0-9937-42e8-96c6-333acdab9e49.png)"
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived RS256 RFC 9068 access token issued by the configured delegation service and verified against its configured JWKS. The issuer authorizes the client and requested operation before minting the token; Forem validates the token and resolves its subject and owner to a local user. An invalid token returns 401; an unavailable trust dependency with no usable cached key returns 503.