Mirror Article version-history endpoints into Preview spec + Fern overrides

descriptions/0/api.intercom.io.yaml

@@ -1938,6 +1938,196 @@ paths:
                   locales:
                   - en
                   - fr
+  "/articles/{article_id}/versions":
+    get:
+      summary: List article versions
+      parameters:
+      - name: Intercom-Version
+        in: header
+        schema:
+          "$ref": "#/components/schemas/intercom_version"
+      - name: article_id
+        in: path
+        required: true
+        description: The unique identifier for the article whose versions you are
+          listing.
+        example: 123
+        schema:
+          type: integer
+      - name: page
+        in: query
+        required: false
+        description: The page of results to fetch. Defaults to the first page.
+        example: 1
+        schema:
+          type: integer
+      - name: per_page
+        in: query
+        required: false
+        description: The number of results to return per page.
+        example: 25
+        schema:
+          type: integer
+      - name: locale
+        in: query
+        required: false
+        description: Filter versions to a specific locale. Use the locale identifier
+          (for example `en`, `fr`). If the locale is not configured for the workspace,
+          a `400` is returned.
+        example: en
+        schema:
+          type: string
+      tags:
+      - Articles
+      operationId: listArticleVersions
+      description: |
+        Fetch the version history of an article by making a GET request to
+        `https://api.intercom.io/articles/<article_id>/versions`. Versions are
+        returned newest-first as a paginated list of metadata. Use
+        `GET /articles/{article_id}/versions/{id}` to retrieve a single version
+        with its full content.
+
+        Requires the `read_articles_scope` OAuth scope. Set `Intercom-Version: Preview`.
+      responses:
+        '200':
+          description: Versions found
+          content:
+            application/json:
+              examples:
+                Versions found:
+                  value:
+                    type: list
+                    pages:
+                      type: pages
+                      page: 1
+                      per_page: 25
+                      total_pages: 1
+                    total_count: 2
+                    data:
+                    - type: article_version
+                      id: '301'
+                      article_id: '123'
+                      title: This is the article title
+                      description: ''
+                      author_id: '991267502'
+                      created_by_id: '5017691'
+                      created_via: web
+                      from_version_id: '300'
+                      state: published
+                      created_at: 1734537292
+                    - type: article_version
+                      id: '300'
+                      article_id: '123'
+                      title: This was the earlier title
+                      description: ''
+                      author_id: '991267502'
+                      created_by_id: '5017691'
+                      created_via: api
+                      from_version_id: null
+                      state: draft
+                      created_at: 1734530000
+              schema:
+                "$ref": "#/components/schemas/article_version_list"
+        '400':
+          description: Unknown locale
+          content:
+            application/json:
+              examples:
+                Unknown locale:
+                  value:
+                    type: error.list
+                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
+                    errors:
+                    - code: parameter_invalid
+                      message: Unknown locale
+              schema:
+                "$ref": "#/components/schemas/error"
+        '404':
+          "$ref": "#/components/responses/ObjectNotFound"
+        '401':
+          "$ref": "#/components/responses/Unauthorized"
+  "/articles/{article_id}/versions/{id}":
+    get:
+      summary: Retrieve an article version
+      parameters:
+      - name: Intercom-Version
+        in: header
+        schema:
+          "$ref": "#/components/schemas/intercom_version"
+      - name: article_id
+        in: path
+        required: true
+        description: The unique identifier for the article.
+        example: 123
+        schema:
+          type: integer
+      - name: id
+        in: path
+        required: true
+        description: The unique identifier for the version.
+        example: '301'
+        schema:
+          type: string
+      - name: locale
+        in: query
+        required: false
+        description: Return the version's content for a specific locale. If the locale
+          is not configured for the workspace, a `400` is returned.
+        example: en
+        schema:
+          type: string
+      tags:
+      - Articles
+      operationId: retrieveArticleVersion
+      description: |
+        Fetch a single prior version of an article, including its body content,
+        by making a GET request to
+        `https://api.intercom.io/articles/<article_id>/versions/<id>`. Returns
+        the version's full content; the live article remains untouched.
+
+        Requires the `read_articles_scope` OAuth scope. Set `Intercom-Version: Preview`.
+      responses:
+        '200':
+          description: Version found
+          content:
+            application/json:
+              examples:
+                Version found:
+                  value:
+                    type: article_version
+                    id: '301'
+                    article_id: '123'
+                    title: This is the article title
+                    description: ''
+                    body: <p class="no-margin">Body of this version</p>
+                    body_markdown: "Body of this version\n"
+                    author_id: '991267502'
+                    created_by_id: '5017691'
+                    created_via: web
+                    from_version_id: '300'
+                    state: published
+                    created_at: 1734537292
+                    updated_at: 1734537292
+              schema:
+                "$ref": "#/components/schemas/article_version"
+        '400':
+          description: Unknown locale
+          content:
+            application/json:
+              examples:
+                Unknown locale:
+                  value:
+                    type: error.list
+                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
+                    errors:
+                    - code: parameter_invalid
+                      message: Unknown locale
+              schema:
+                "$ref": "#/components/schemas/error"
+        '404':
+          "$ref": "#/components/responses/ObjectNotFound"
+        '401':
+          "$ref": "#/components/responses/Unauthorized"
   "/articles/search":
     get:
       summary: Search for articles
@@ -24702,6 +24892,174 @@ components:
         zh-TW:
           description: The content of the article in Chinese (Taiwan)
           "$ref": "#/components/schemas/article_content"
+    article_version:
+      title: Article Version
+      type: object
+      x-tags:
+      - Articles
+      description: A historical version of an article, including its content.
+      properties:
+        type:
+          type: string
+          description: String representing the object's type. Always has the value
+            `article_version`.
+          enum:
+          - article_version
+          example: article_version
+        id:
+          type: string
+          description: The unique identifier for the version.
+          example: '301'
+        article_id:
+          type: string
+          description: The unique identifier of the article this version belongs to.
+          example: '123'
+        title:
+          type: string
+          description: The title of the article at this version.
+          example: This is the article title
+        description:
+          type: string
+          nullable: true
+          description: The description of the article at this version.
+          example: ''
+        body:
+          type: string
+          nullable: true
+          description: The HTML body of the article at this version.
+          example: <p class="no-margin">Body of this version</p>
+        body_markdown:
+          type: string
+          nullable: true
+          description: The Markdown body of the article at this version.
+          example: |
+            Body of this version
+        author_id:
+          type: string
+          description: The id of the teammate listed as the article's author at this
+            version.
+          example: '991267502'
+        created_by_id:
+          type: string
+          nullable: true
+          description: The id of the teammate who created this version.
+          example: '5017691'
+        created_via:
+          type: string
+          description: How this version was created (for example `web`, `api`).
+          example: web
+        from_version_id:
+          type: string
+          nullable: true
+          description: The id of the version this version was created from, or `null`
+            if this is the first version.
+          example: '300'
+        state:
+          type: string
+          description: Whether this version is the currently published version of
+            the article (`published`) or an earlier non-live version (`draft`).
+          enum:
+          - published
+          - draft
+          example: published
+        created_at:
+          type: integer
+          format: date-time
+          description: The time the version was created, as a UTC Unix timestamp.
+          example: 1734537292
+        updated_at:
+          type: integer
+          format: date-time
+          description: The time the version was last updated, as a UTC Unix timestamp.
+          example: 1734537292
+    article_version_list:
+      title: Article Versions
+      type: object
+      description: A paginated list of versions of an article.
+      properties:
+        type:
+          type: string
+          description: The type of the object - `list`.
+          enum:
+          - list
+          example: list
+        pages:
+          "$ref": "#/components/schemas/cursor_pages"
+        total_count:
+          type: integer
+          description: A count of the total number of versions.
+          example: 2
+        data:
+          type: array
+          description: An array of Article version summary objects.
+          items:
+            "$ref": "#/components/schemas/article_version_summary"
+    article_version_summary:
+      title: Article Version Summary
+      type: object
+      x-tags:
+      - Articles
+      description: A metadata summary of an article version, as returned by the version-history
+        list endpoint. Omits the version's body content - fetch a single version to
+        retrieve its `body` and `body_markdown`.
+      properties:
+        type:
+          type: string
+          description: String representing the object's type. Always has the value
+            `article_version`.
+          enum:
+          - article_version
+          example: article_version
+        id:
+          type: string
+          description: The unique identifier for the version.
+          example: '301'
+        article_id:
+          type: string
+          description: The unique identifier of the article this version belongs to.
+          example: '123'
+        title:
+          type: string
+          description: The title of the article at this version.
+          example: This is the article title
+        description:
+          type: string
+          nullable: true
+          description: The description of the article at this version.
+          example: ''
+        author_id:
+          type: string
+          description: The id of the teammate listed as the article's author at this
+            version.
+          example: '991267502'
+        created_by_id:
+          type: string
+          nullable: true
+          description: The id of the teammate who created this version.
+          example: '5017691'
+        created_via:
+          type: string
+          description: How this version was created (for example `web`, `api`).
+          example: web
+        from_version_id:
+          type: string
+          nullable: true
+          description: The id of the version this version was created from, or `null`
+            if this is the first version.
+          example: '300'
+        state:
+          type: string
+          description: Whether this version is the currently published version of
+            the article (`published`) or an earlier non-live version (`draft`).
+          enum:
+          - published
+          - draft
+          example: published
+        created_at:
+          type: integer
+          format: date-time
+          description: The time the version was created, as a UTC Unix timestamp.
+          example: 1734537292
     assign_conversation_request:
       title: Assign Conversation Request
       type: object

fern/preview-openapi-overrides.yml

@@ -22,6 +22,21 @@ paths:
               $ref: '#/components/schemas/CreateArticleRequestBody'
   '/articles/{id}':
     put: null
+  '/articles/{article_id}/versions':
+    get:
+      x-fern-pagination:
+        offset: $request.page
+        results: $response.data
+      x-fern-sdk-group-name:
+        - articles
+      x-fern-sdk-method-name: listVersions
+      x-fern-request-name: ListArticleVersionsRequest
+  '/articles/{article_id}/versions/{id}':
+    get:
+      x-fern-sdk-group-name:
+        - articles
+      x-fern-sdk-method-name: findVersion
+      x-fern-request-name: FindArticleVersionRequest
   '/tickets':
     post: null
   '/ticket_types/{id}':