docs: add filtering documentation and enhance Object Customization guide (#236)

- Explain DevRev object and leaf_type.
- Add a section on filtering.
- Remove the beta warning at the top.
  The process to make the APIs public is in progress, and we'll anyways
  not break the beta APIs.
- Fix headers. The Accept header is redundant, and Content-Type is mandatory.
- Remove redundant uses of "Let's say..." while maintaining the educational tone.

Author: shivansh

fern/docs/pages/customization.mdx

@@ -1,18 +1,27 @@
-<Callout intent="warning">
-This functionality is in Beta. It is not recommended for use in production applications.
-</Callout>
-
 DevRev allows you to customize its core objects such as _issue_ and _ticket_ to fit
 your organization's unique workflows and reporting needs. By using the customization
 framework, you can extend these objects with custom fields that reflect your processes.
 
-This guide provides an overview of the customization framework and walks you through the process of tracking bugs in your organization. By the end of this guide, you'll be able to:
-1. Customize DevRev objects such as _issue_ and _ticket_.
+This section provides an overview of the customization framework and walks you through the
+process of tracking bugs in your organization. By the end of this section, you'll be able
+to:
+1. Customize DevRev objects such as _issue_ and _ticket_ by adding custom fields.
+1. Override default field settings of DevRev objects.
 1. Create custom stages and stage transition diagrams for your objects.
 1. Create dependent fields for your objects.
 
 ## Concepts
 
+### DevRev object
+
+DevRev objects are the core entities that represent real-world items such as issues,
+tickets, and incidents. Each object type has a set of fields that describe the object.
+
+<Callout intent="tip">
+When you encounter `leaf_type` in the documentation or API, it refers to the type of DevRev
+object you're working with, such as an _issue_ or _ticket_.
+</Callout>
+
 ### Schema fragment
 
 DevRev objects are customized using _schema fragments_. A fragment is a building block
@@ -40,7 +49,10 @@ Subtypes are defined using a schema fragment of type `custom_type_fragment`.
 
 ## Customizing a DevRev object
 <Callout intent="note">
-Let's say you want to track bugs across various environments in your organization.
+Your team needs to track software bugs. You want to know:
+- Which environments are affected (development, testing, production)
+- Whether it's a regression (a bug in previously working code)
+- The root cause analysis (RCA) of the bug
 </Callout>
 
 First, create a schema fragment defining the fields for the _bug_ subtype.
@@ -49,7 +61,6 @@ Make sure to replace `<TOKEN>` with your API token.
 ```curl
 curl --location 'https://api.devrev.ai/schemas.custom.set' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "type": "custom_type_fragment",
@@ -58,13 +69,6 @@ curl --location 'https://api.devrev.ai/schemas.custom.set' \
     "subtype": "bug",
     "subtype_display_name": "Bug",
     "fields": [
-        {
-            "name": "regression",
-            "field_type": "bool",
-            "ui": {
-                "display_name": "Regression",
-            }
-        },
         {
             "name": "impacted_environments",
             "field_type": "array",
@@ -75,6 +79,13 @@ curl --location 'https://api.devrev.ai/schemas.custom.set' \
                 "display_name": "Impacted Environments",
             }
         },
+        {
+            "name": "regression",
+            "field_type": "bool",
+            "ui": {
+                "display_name": "Regression",
+            }
+        },
         {
             "name": "rca",
             "field_type": "rich_text",
@@ -87,15 +98,13 @@ curl --location 'https://api.devrev.ai/schemas.custom.set' \
 ```
 
 <Callout intent="note">
-Let's say a bug has been identified in the Prod environment. The person who reported the
-anomaly creates a _bug_-flavored _issue_ object to track it and assigns a relevant
-owner.
+A bug has been identified in the production environment. The reporter creates a
+_bug_-flavored _issue_ object to track it and assigns a relevant owner.
 </Callout>
 
 ```curl {11-17}
 curl --location 'https://api.devrev.ai/works.create' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "type": "issue",
@@ -108,8 +117,8 @@ curl --location 'https://api.devrev.ai/works.create' \
         "subtype": "bug"
     },
     "custom_fields": {
+        "ctype__impacted_environments": [ "QA", "Prod" ]
         "ctype__regression": true,
-        "ctype__impacted_environments": [ "Prod" ]
     }
 }'
 ```
@@ -129,7 +138,6 @@ a subtype-specific field.
 ```curl
 curl --location 'https://api.devrev.ai/schemas.custom.set' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "type": "tenant_fragment",
@@ -152,7 +160,6 @@ Populate the release notes in the issue object created above:
 ```curl {8-13}
 curl --location 'https://api.devrev.ai/works.update' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "id": "don:core:dvrv-us-1:devo/test:issue/1",
@@ -195,7 +202,9 @@ The following observations can be made from the above example:
   - Subtype fields are of the form `ctype__<field_name>`.
   - Tenant fields are of the form `tnt__<field_name>`.
 * References to each fragment are stored with the object.
-* When updating an object, the `custom_schema_spec` can specify only the fragments being modified. Here, only the tenant fragment is specified as only the release notes field is being updated.
+* When updating an object, the `custom_schema_spec` can specify only the fragments being
+  modified. Here, only the tenant fragment is specified as only the release notes field
+  is being updated.
 
 ## Supported custom field types
 
@@ -214,8 +223,37 @@ The following custom field types are supported -
 | date      | `"2020-10-20"` (YYYY-MM-DD)              |
 | id        | `"don:core:dvrv-us-1:devo/test:issue/1"` |
 
-The list variants of all the supported custom field types are also supported. For
-example, `[]int`, `[]tokens`, etc.
+The list variants of all the supported custom field types are also supported.
+In the example above, the `impacted_environments` field is a list of enum values.
+
+## Filtering DevRev objects
+
+<Callout intent="note">
+To demonstrate filtering capabilities, consider finding all bugs in the production
+environment that had a customer impact.
+</Callout>
+
+This translates to filtering _issue_ objects with subtype _bug_, _customer_impact_ set
+to `true` and _impacted_environments_ containing `"Prod"`.
+
+```curl
+curl --location 'https://api.devrev.ai/works.list' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: <TOKEN>' \
+--data '{
+    "type": [ "issue" ],
+    "issue": {
+        "subtype": [ "bug" ]
+    },
+    "custom_fields": {
+        "ctype__customer_impact": [ true ],
+        "ctype__impacted_environments": [ "Prod" ]
+    }
+}'
+```
+
+Note that both _customer_impact_ and _impacted_environments_ are filterable fields,
+marked with `is_filterable: true` above.
 
 ## Schema fragment versioning
 
@@ -228,7 +266,7 @@ The same API endpoint `schemas.custom.set` is used to create and update fragment
 API internally figures out how to version and chain the fragments.
 
 <Callout intent="note">
-Let's say you want to add a new boolean field _customer_impact_ to the _bug_ subtype
+You want to add a new boolean field _customer_impact_ to the _bug_ subtype
 and delete the _regression_ field.
 </Callout>
 
@@ -237,7 +275,6 @@ and delete the _regression_ field.
 ```curl {28-36}
 curl --location 'https://api.devrev.ai/schemas.custom.set' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "type": "custom_type_fragment",
@@ -265,6 +302,7 @@ curl --location 'https://api.devrev.ai/schemas.custom.set' \
         {
             "name": "customer_impact",
             "field_type": "bool",
+            "is_filterable": true,
             "ui": {
                 "display_name": "Customer Impact",
             }
@@ -276,7 +314,9 @@ curl --location 'https://api.devrev.ai/schemas.custom.set' \
 
 Note that:
 * The API payload reflects the entire state of the new fragment version.
-* The `deleted_fields` array specifies the field names that are being deleted. If not provided, the API call fails due to the lack of an explicit field deletion confirmation. This prevents accidental field deletions.
+* The `deleted_fields` array specifies the field names that are being deleted. If not
+  provided, the API call fails due to the lack of an explicit field deletion
+  confirmation. This prevents accidental field deletions.
 
 The above API call internally performs the following steps:
 1. Creates a new fragment with the specified payload.
@@ -318,7 +358,7 @@ _regression_ field is dropped in the response.
 
 ```curl {16-18, 21}
 curl --location 'https://api.devrev.ai/works.get' \
---header 'Accept: application/json' \
+--header 'Content-Type: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "id": "don:core:dvrv-us-1:devo/test:issue/2"
@@ -373,7 +413,7 @@ organization:
 
 ```curl
 curl --location 'https://api.devrev.ai/schemas.custom.list' \
---header 'Accept: application/json' \
+--header 'Content-Type: application/json' \
 --header 'Authorization: <TOKEN>'
 ```
 
@@ -391,7 +431,8 @@ hints:
 * `is_sortable`: Whether the field is sortable. Requires `is_filterable` to be true.
 * `is_groupable`: Whether the field is groupable. Requires `is_filterable` to be true.
 * `order`: The order in which the field appears in the side panel.
-* `group_name`: The group title under which field(s) appear in the side panel. In the example below, the fields are grouped under groups titled **Group 1** and **Group 2**.
+* `group_name`: The group title under which field(s) appear in the side panel. In the
+  example below, the fields are grouped under groups titled **Group 1** and **Group 2**.
 
   ![customization-group_name-ui-hint](../img/customization-group_name-ui-hint.png)
 
@@ -405,7 +446,7 @@ The fields available in native DevRev objects are called stock fields. For examp
 `priority` is a stock field of _issue_.
 
 <Callout intent="note">
-Let's say you want to do the following modifications to the priority field in your organization:
+You want to do the following modifications to the priority field in your organization:
 
 1. Update the UI display name from _Priority_ to _Urgency Level_.
 1. Update the allowed values from _P0_, _P1_, _P2_, and _P3_ to _Low_, _Medium_, _High_, and _Blocker_.
@@ -417,7 +458,6 @@ fragment with the following payload:
 ```curl
 curl --location 'https://api.devrev.ai/internal/schemas.custom.set' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
   "type": "tenant_fragment",
@@ -492,15 +532,14 @@ _backlog_, and _prioritized_ stages. By default, DevRev creates _open_, _in_prog
 and _closed_ states in your organization.
 
 <Callout intent="note">
-Let's say you want to add a new stage _Needs RCA_ to the _bug_ subtype.
+You want to add a new stage _Needs RCA_ to the _bug_ subtype.
 </Callout>
 
 ### Adding a custom stage
 
 ```curl
 curl --location 'https://api.devrev.ai/stages.custom.create' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "name": "Needs RCA",
@@ -542,7 +581,6 @@ backl --> dev --> rca --> compl
 ```curl {11}
 curl --location 'https://api.devrev.ai/stage-diagrams.create' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "leaf_type": "issue",
@@ -591,7 +629,6 @@ The stage diagram created above can be referenced in the _bug_ subtype as follow
 ```curl {9}
 curl --location 'https://api.devrev.ai/schemas.custom.set' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "type": "custom_type_fragment",
@@ -609,15 +646,14 @@ All objects of the _bug_ subtype now adhere to the stage diagram created above.
 ## Dependent fields
 
 <Callout intent="note">
-Let's say that the developers in your organization tend to forget to add an RCA when
-resolving the bugs. You can make the _RCA_ field required when a _bug_ object is moved
-to the _completed_ stage by adding a dependent field constraint.
+The developers in your organization tend to forget to add an RCA when resolving the
+bugs. You can make the _RCA_ field required when a _bug_ object is moved to the
+_completed_ stage by adding a dependent field constraint.
 </Callout>
 
 ```curl {12-22}
 curl --location 'https://api.devrev.ai/schemas.custom.set' \
 --header 'Content-Type: application/json' \
---header 'Accept: application/json' \
 --header 'Authorization: <TOKEN>' \
 --data '{
     "type": "custom_type_fragment",