feat(custom-objects): add list-all instances endpoint docs

Updates GET /custom_object_instances/{type}:
- Replaces the undocumented external_id-only operation with a general
  listCustomObjectInstances operation covering all three modes:
  no-filter (list all), references_contact_id, references_conversation_id
- Fixes external_id being incorrectly marked required=true
- Adds pagination params (page, per_page)
- Adds custom_object_instances_paginated_list response schema

Companion: intercom/intercom#498284

Author: marcmlc

descriptions/0/api.intercom.io.yaml

@@ -10527,30 +10527,54 @@ paths:
                     order_number: ORDER-12345
                     total_amount: 99.99
     get:
-      summary: Get Custom Object Instance by External ID
+      summary: List Custom Object Instances
       parameters:
+      - name: references_contact_id
+        in: query
+        required: false
+        description: Return instances associated with the given contact ID.
+        schema:
+          type: string
+      - name: references_conversation_id
+        in: query
+        required: false
+        description: Return instances associated with the given conversation ID.
+        schema:
+          type: string
       - name: external_id
         in: query
-        style: form
-        required: true
+        required: false
+        description: Return the single instance with this external ID. When provided,
+          the response is a single object rather than a list.
         schema:
           type: string
-          description: The unique identifier for the instance in the external system
-            it originated from.
-          title: Find by external_id
-          properties:
-            external_id:
-              type: string
-          required:
-          - external_id
+      - name: page
+        in: query
+        required: false
+        description: Page number of results to fetch.
+        schema:
+          type: integer
+      - name: per_page
+        in: query
+        required: false
+        description: Number of results per page. Maximum 150.
+        schema:
+          type: integer
+          maximum: 150
       - name: Intercom-Version
         in: header
         schema:
           "$ref": "#/components/schemas/intercom_version"
       tags:
       - Custom Object Instances
-      operationId: getCustomObjectInstancesByExternalId
-      description: Fetch a Custom Object Instance by external_id.
+      operationId: listCustomObjectInstances
+      description: |-
+        List instances of a custom object type. Three modes are supported:
+        - **No filter** — returns all instances for the type (requires `Intercom-Version: Preview`).
+        - **`references_contact_id`** — returns instances associated with the given contact.
+        - **`references_conversation_id`** — returns instances associated with the given conversation.
+
+        When **`external_id`** is provided, returns a single matching instance (not a list).
       responses:
         '200':
           description: successful
@@ -10559,22 +10583,40 @@ paths:
               examples:
                 successful:
                   value:
-                    id: '24'
-                    type: Order
-                    custom_attributes:
-                      order_number: ORDER-12345
-                      total_amount: 99.99
-                    external_id: '123'
-                    external_created_at:
-                    external_updated_at:
-                    created_at: 1734537748
-                    updated_at: 1734537748
-              schema:
-                "$ref": "#/components/schemas/custom_object_instance"
+                    type: list
+                    pages:
+                      type: pages
+                      page: 1
+                      per_page: 20
+                      total_pages: 1
+                    total_count: 2
+                    data:
+                    - id: '2'
+                      type: Order
+                      custom_attributes:
+                        order_number: ORDER-98765
+                        total_amount: 149.99
+                      external_id: order_002
+                      external_created_at:
+                      external_updated_at:
+                      created_at: 1734537800
+                      updated_at: 1734537800
+                    - id: '1'
+                      type: Order
+                      custom_attributes:
+                        order_number: ORDER-12345
+                        total_amount: 99.99
+                      external_id: order_001
+                      external_created_at: 1734537100
+                      external_updated_at: 1734537100
+                      created_at: 1734537100
+                      updated_at: 1734537100
+              schema:
+                "$ref": "#/components/schemas/custom_object_instances_paginated_list"
         '401':
           $ref: "#/components/responses/Unauthorized"
         '404':
-          $ref: "#/components/responses/ObjectNotFound"
+          $ref: "#/components/responses/TypeNotFound"
     delete:
       summary: Delete a Custom Object Instance by External ID
       parameters:
@@ -23413,6 +23455,31 @@ components:
             reference attribute on the parent object.
           items:
             "$ref": "#/components/schemas/custom_object_instance"
+    custom_object_instances_paginated_list:
+      title: Custom Object Instances
+      type: object
+      x-tags:
+      - Custom Object Instances
+      description: A paginated list of custom object instances.
+      nullable: false
+      properties:
+        type:
+          type: string
+          description: The type of the object - `list`.
+          enum:
+          - list
+          example: list
+        pages:
+          "$ref": "#/components/schemas/pages_link"
+        total_count:
+          type: integer
+          description: A count of the total number of custom object instances.
+          example: 2
+        data:
+          type: array
+          description: An array of Custom Object Instance objects.
+          items:
+            "$ref": "#/components/schemas/custom_object_instance"
     customer_request:
       type: object
       nullable: true