openapi: 3.2.0
info:
  title: Forem API V1 Recommended Articles Lists 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: recommended_articles_lists
paths:
  /api/recommended_articles_lists:
    get:
      summary: Retrieve all recommended articles lists
      tags:
      - recommended_articles_lists
      description: 'Retrieve a list of all recommended articles lists configured in the system.


        ### Overview:

        - Recommended Articles Lists are curated selections of articles pinned or recommended in layout regions (e.g. `main_feed` or `sidebar`).

        - Supports search by list name and standard query pagination.

        - Requires Administrator privileges.'
      parameters:
      - name: page
        in: query
        required: false
        description: Pagination page index.
        schema:
          type: integer
      - name: search
        in: query
        required: false
        description: Search term to match against recommended list names.
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecommendedArticlesList'
      operationId: getApiRecommendedArticlesLists
      x-operation-id-source: derived
    post:
      summary: Create or update a recommended articles list
      tags:
      - recommended_articles_lists
      description: 'Create a new recommended articles list or update an existing one. Requires Administrator privileges.


        ### Body Parameter Guidelines:

        - **name**: Curated list title or label (e.g. "Editor''s Choice").

        - **placement_area**: Target UI layout region (e.g. `main_feed`, `sidebar_top`, `onboarding`).

        - **expires_at**: ISO 8601 timestamp after which the list recommendation automatically expires.

        - **user_id**: Owner/curator numeric user ID.

        - **article_ids**: Staged array of numeric article IDs to include in the recommendation sequence.'
      parameters: []
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendedArticlesList'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                placement_area:
                  type: string
                expires_at:
                  type: string
                  format: date-time
                user_id:
                  type: integer
                article_ids:
                  type: array
                  items:
                    type: integer
              required:
              - user_id
              - placement_area
        description: Curated recommended list details.
      operationId: postApiRecommendedArticlesLists
      x-operation-id-source: derived
  /api/recommended_articles_lists/{id}:
    get:
      summary: Retrieve details of a recommended articles list
      tags:
      - recommended_articles_lists
      description: Retrieve full details and nested article lists for a specific recommended articles list by ID. Requires Admin credentials.
      parameters:
      - name: id
        in: path
        required: true
        description: Unique list numeric ID.
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendedArticlesList'
      operationId: getApiRecommendedArticlesListsById
      x-operation-id-source: derived
    patch:
      summary: Update a recommended articles list
      tags:
      - recommended_articles_lists
      description: Update an existing recommended articles list by ID. Requires Admin credentials.
      parameters:
      - name: id
        in: path
        required: true
        description: Unique list numeric ID.
        schema:
          type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendedArticlesList'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                placement_area:
                  type: string
                expires_at:
                  type: string
                  format: date-time
                user_id:
                  type: integer
                article_ids:
                  type: array
                  items:
                    type: integer
        description: Updated list parameters.
      operationId: patchApiRecommendedArticlesListsById
      x-operation-id-source: derived
components:
  schemas:
    RecommendedArticlesList:
      description: Representation of a recommended articles list
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        placement_area:
          type: string
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        user_id:
          type: integer
          format: int64
        article_ids:
          type: array
          items:
            type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - name
      - placement_area
      - user_id
      - article_ids
      - created_at
      - updated_at
  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.