docs: add custom objects beta API documentation

fern/docs/pages/custom-objects.mdx

@@ -0,0 +1,272 @@
+## Table of contents
+
+* [Introduction](#custom-objects)
+* [Quick start](#quick-start)
+   - [Create a schema and a custom object](#create-a-schema-and-a-custom-object)
+   - [Get a custom object](#get-a-custom-object)
+   - [List custom objects](#list-custom-objects)
+   - [Update a custom object](#update-a-custom-object)
+   - [Delete a custom object](#delete-a-custom-object)
+* [Key concepts](#key-concepts)
+* [Custom object lifecycle](#custom-object-lifecycle)
+* [Extended use cases](#extended-use-cases)
+    - [Reference custom objects in other objects](#reference-custom-objects-in-other-objects)
+    - [Add subtypes to custom objects](#add-subtypes-to-custom-objects)
+
+- - -
+
+## Introduction
+Custom objects allow you to extend DevRev's data model beyond the standard use-cases
+served by the native apps like Build and Support.  Custom objects allow you to create
+and manage object types tailored to your specific business needs.
+
+## Quick start
+Let's say you want to manage marketing campaigns on DevRev. We'll go through the process of creating a "Campaign" custom object with relevant fields.
+
+All DevRev objects require a schema. So, we'll first create a schema for the "Campaign" custom object. Make sure to replace the `<YOUR_API_TOKEN>` with your actual API token.
+
+### Create a schema and a custom object
+
+```
+curl --location 'https://api.devrev.ai/schemas.custom.set' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "type": "tenant_fragment",
+    "description": "Attributes for Campaign",
+    "leaf_type": "campaign",
+    "fields": [
+        {
+            "name": "name",
+            "field_type": "tokens",
+            "description": "Name of the campaign"
+        },
+        {
+            "name": "start_date",
+            "field_type": "date",
+            "description": "Start date of the campaign"
+        },
+        {
+            "name": "end_date",
+            "field_type": "date",
+            "description": "End date of the campaign"
+        },
+        {
+            "name": "budget",
+            "field_type": "int",
+            "description": "Budget allocated for the campaign"
+        },
+        {
+            "name": "target_audience",
+            "field_type": "enum",
+            "description": "Target audience for the campaign",
+            "allowed_values": [
+                "Professionals",
+                "Students"
+            ]
+        }
+    ],
+    "is_custom_leaf_type": true,
+    "id_prefix": "CAMP"
+}'
+```
+
+Once the schema is created, you can create a custom object of type "Campaign":
+
+```
+curl --location 'https://api.devrev.ai/custom-objects.create' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "leaf_type": "campaign",
+    "unique_key": "CAMP-001",
+    "custom_schema_spec": {
+        "tenant_fragment": true
+    },
+    "custom_fields": {
+        "tnt__name": "Summer Sale 2023",
+        "tnt__start_date": "2023-06-01",
+        "tnt__end_date": "2023-08-31",
+        "tnt__budget": 10000,
+        "tnt__target_audience": "Professionals"
+    }
+}'
+```
+
+The response of the above API call will be the ID of the custom object created.
+```
+{
+  "custom_object": {
+    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1",
+    "created_by": {...},
+    "created_date": "2024-10-01T07:02:58.958Z",
+    "modified_by": {...},
+    "modified_date": "2024-10-01T07:02:58.958Z",
+    "display_id": "C-CAMP-1",
+    "leaf_type": "campaign",
+    "unique_key": "CAMP-001"
+    "stock_schema_fragment": "don:core:dvrv-us-1:stock_sf/1",
+    "custom_schema_fragments": [
+      "don:core:dvrv-us-1:devo/demo:tenant_fragment/1"
+    ],
+    "custom_fields": {
+      "tnt__name": "Summer Sale 2023",
+      "tnt__start_date": "2023-06-01",
+      "tnt__end_date": "2023-08-31",
+      "tnt__budget": 10000,
+      "tnt__target_audience": "Professionals"
+    }
+  }
+}
+```
+
+Note that the `id` field in the above response is the system generated ID for the custom object.
+
+The sections below provide more details on the available API endpoints for interacting with custom objects.
+
+### Get a custom object
+
+To get a custom object, use the `custom-objects.get` endpoint:
+
+```
+curl --location 'https://api.devrev.ai/custom-objects.get' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1"
+}'
+```
+
+### List custom objects
+
+To list custom objects, use the `custom-objects.list` endpoint:
+
+```
+curl --location 'https://api.devrev.ai/custom-objects.list' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "leaf_type": "campaign",
+    "filter": [
+      "eq",
+      "$custom_fields.tnt__target_audience",
+      "Young adults"
+    ]
+}'
+```
+
+### Update a custom object
+
+To update an existing custom object, use the `custom-objects.update` endpoint. The
+following example updates the budget of the previously created campaign custom object:
+
+```
+curl --location 'https://api.devrev.ai/custom-objects.update' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1",
+    "custom_fields": {
+        "tnt__budget": 15000
+    }
+}'
+```
+
+### Delete a custom object
+
+To delete a custom object, use the `custom-objects.delete` endpoint.
+The following example deletes the previously created campaign custom object:
+
+```
+curl --location 'https://api.devrev.ai/custom-objects.delete' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "id": "don:core:dvrv-us-1:devo/demo:custom_object/campaign/1"
+}'
+```
+
+## Key concepts
+
+1. **Leaf Type**: The base type of your custom object (e.g., "campaign"). Note that for custom objects, `is_custom_leaf_type` must be set to `true` to differentiate it from standard DevRev objects.
+2. **Subtype**: A more specific categorization within a leaf type (e.g., "promotion" or "advertising" for a "campaign" leaf type).
+3. **Custom Fields**: User-defined fields that store specific data for your custom object.
+4. **Unique Key**: The `unique_key` is a unique identifier for each custom object. This is useful for maintaining idempotency when retrying custom object creation requests.
+5. **ID Prefix**: The `id_prefix` should be unique and is used to generate the display ID for the custom object. In the above example, the `id_prefix` is "CAMP" and the generated custom object display ID is "C-CAMP-1". The display ID is used to identify the custom object in the UI, similar to the standard DevRev object display IDs like "ISS-001" for issues.
+
+For more details on customization concepts, please refer to the
+[Customization](./object-customization) documentation.
+
+## Custom object lifecycle
+
+1. **Creation**: Define the leaf type, subtype (optional), and custom fields for your custom object.
+2. **Usage**: Create, update, and query custom objects as needed in your workflows.
+3. **Management**: Modify the schema of the custom object as your needs evolve.
+
+## Extended use cases
+
+### Reference custom objects in other objects
+Let's say you want to reference all the campaigns that have been run for a customer
+workspace. You can do so by adding a field of type "id" and "id_type: custom_object.campaign"
+in the account object.
+
+```
+curl --location 'https://api.devrev.ai/schemas.custom.set' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "type": "tenant_fragment",
+    "description": "Tenant attributes for Account",
+    "leaf_type": "account",
+    "fields": [
+        {
+            "name": "campaigns",
+            "field_type": "array",
+            "base_type": "id",
+            "id_type": [ "custom_object.campaign" ],
+        },
+        ... // other fields
+    ],
+}'
+```
+
+### Add subtypes to custom objects
+Adding subtypes to custom objects allows you to categorize and manage your custom
+objects more effectively. The process is the same as adding subtypes to other standard
+DevRev objects like issues and tickets.
+
+Let's say you have run different types of campaigns like social media and email
+marketing. You can create a subtype for each of these variants. If you want to create a
+campaign custom object with subtype "social_media", you can do so as follows:
+
+```
+curl --location 'https://api.devrev.ai/custom-objects.create' \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'Authorization: <YOUR_API_TOKEN>' \
+--data '{
+    "leaf_type": "campaign",
+    "custom_schema_spec": {
+        "subtype": "social_media",
+        "tenant_fragment": true
+    },
+    "custom_fields": {
+        "tnt__name": "Summer Sale 2023",
+        "tnt__start_date": "2023-06-01",
+        "tnt__end_date": "2023-08-31",
+        "tnt__budget": 10000,
+        "tnt__target_audience": "Professionals",
+        "ctype__social_media_platform": "Facebook",
+        "ctype__post_id": "1234567890"
+    },
+    "unique_key": "CAMP-001"
+}'
+```
+

fern/versions/beta.yml

@@ -13,5 +13,7 @@ navigation:
     contents:
       - page: Object Customization
         path: ../docs/pages/customization.mdx
+      - page: Custom Objects
+        path: ../docs/pages/custom-objects.mdx
       - page: Create accounts and contacts in DevRev
         path: ../docs/pages/create-accounts.mdx