openapi: 3.2.0 info: title: Forem API V1 Trends 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: Trends paths: /api/trends: get: summary: Trends security: [] tags: - Trends description: 'Retrieve a list of active trends. ### Trends Overview & Score Calculation: - Trends represent hot topics or semantic themes currently being heavily discussed in the community. - They are computed by clustering semantic concept embeddings of recently published articles. - The `score` reflects the volume and engagement (views, comments, reactions) of articles associated with the trend. - Returned trends are ordered by score and recency. - Publicly accessible without authentication. It supports pagination, each page will contain 10 trends by default.' operationId: getTrends parameters: - $ref: '#/components/parameters/pageParam' - $ref: '#/components/parameters/perPageParam10to1000' responses: '200': description: A List of Trends content: application/json: schema: type: array items: $ref: '#/components/schemas/Trend' /api/trends/{id_or_slug}: get: summary: A Trend security: [] tags: - Trends description: 'Retrieve details of a single trend using either its numeric ID or unique slug. ### Usage Guidance: - Useful for loading details of a trending topic (description, score, and slug details) to render header sections on trending tag or topic pages.' operationId: getTrend parameters: - name: id_or_slug in: path required: true description: The ID or slug of the trend to retrieve. example: ruby-3-4-release schema: type: string responses: '200': description: A Trend content: application/json: schema: type: object items: $ref: '#/components/schemas/Trend' '404': description: Trend Not Found /api/trends/{trend_id_or_slug}/articles: get: summary: Articles in a Trend security: [] tags: - Trends description: 'Retrieve a list of published articles belonging to a trend. ### Article Ordering & Proximity: - Articles are mapped to trends based on their embedding distance to the trend''s centroid. - Returned articles are ordered by proximity/similarity (distance) first (most relevant posts first), and then by overall article engagement score. - Supports pagination, each page will contain 10 articles by default.' operationId: getTrendArticles parameters: - name: trend_id_or_slug in: path required: true description: The ID or slug of the trend to retrieve articles for. example: ruby-3-4-release schema: type: string - $ref: '#/components/parameters/pageParam' - $ref: '#/components/parameters/perPageParam10to1000' responses: '200': description: A List of Articles in the Trend content: application/json: schema: type: array items: $ref: '#/components/schemas/ArticleIndex' '404': description: Trend Not Found components: schemas: SharedOrganization: description: The organization the resource belongs to type: object properties: name: type: string username: type: string slug: type: string profile_image: description: Profile image (640x640) type: string format: url profile_image_90: description: Profile image (90x90) type: string format: url ArticleIndex: description: Representation of an article or post returned in a list type: object properties: type_of: type: string id: type: integer format: int32 title: type: string description: type: string cover_image: type: - string - 'null' format: url readable_publish_date: type: string social_image: type: string format: url tag_list: type: array items: type: string tags: type: string slug: type: string path: type: string format: path url: type: string format: url canonical_url: type: string format: url positive_reactions_count: type: integer format: int32 public_reactions_count: type: integer format: int32 created_at: type: string format: date-time edited_at: type: - string - 'null' format: date-time crossposted_at: type: - string - 'null' format: date-time published_at: type: string format: date-time last_comment_at: type: string format: date-time published_timestamp: description: Crossposting or published date time type: string format: date-time reading_time_minutes: description: Reading time, in minutes type: integer format: int32 ai_disclosure_level: type: string enum: - not_disclosed - no_ai - some_ai - fully_autonomous description: Level of AI tooling usage disclosure ai_disclosure_label: type: string description: Human-readable label of AI disclosure user: $ref: '#/components/schemas/SharedUser' flare_tag: $ref: '#/components/schemas/ArticleFlareTag' organization: $ref: '#/components/schemas/SharedOrganization' required: - type_of - id - title - description - cover_image - readable_publish_date - social_image - tag_list - tags - slug - path - url - canonical_url - comments_count - positive_reactions_count - public_reactions_count - created_at - edited_at - crossposted_at - published_at - last_comment_at - published_timestamp - user - reading_time_minutes SharedUser: description: The resource creator type: object properties: name: type: string username: type: string twitter_username: type: - string - 'null' github_username: type: - string - 'null' website_url: type: - string - 'null' format: url profile_image: description: Profile image (640x640) type: string profile_image_90: description: Profile image (90x90) type: string ArticleFlareTag: description: Flare tag of the article type: object properties: name: type: string bg_color_hex: description: Background color (hexadecimal) type: - string - 'null' text_color_hex: description: Text color (hexadecimal) type: - string - 'null' Trend: description: Representation of a trend type: object properties: type_of: type: string id: type: integer format: int64 name: type: string slug: type: string description: type: - string - 'null' key_questions: type: array items: type: string score: type: number format: float articles_count: type: integer format: int32 cover_image: type: - string - 'null' format: url first_observed_at: type: string format: date-time last_observed_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time required: - type_of - id - name - slug - key_questions - score - articles_count - first_observed_at - last_observed_at - created_at - updated_at parameters: pageParam: in: query name: page required: false description: Pagination page schema: type: integer format: int32 minimum: 1 default: 1 perPageParam10to1000: in: query name: per_page required: false description: Page size (the number of items to return per page). The default maximum value can be overridden by "API_PER_PAGE_MAX" environment variable. schema: type: integer format: int32 minimum: 1 maximum: 1000 default: 10 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.