chamaeleonidae · pulkitagrawal · Jul 26, 2025 · Jul 26, 2025 · Jul 26, 2025 · Jul 29, 2025
diff --git a/README.md b/README.md
@@ -1,11 +1,40 @@
 # Chameleon API Docs
 
-A descriptions of the routing and endpoints available on the Chameleon API
+Documentation for the Chameleon API routing and endpoints.
 
-The documentation can be viewed locally by running any webserver in the `docs` directory.
-
-For example, the following command will start a WEBrick server available on http://localhost:8000:
+The documentation can be viewed locally by running any webserver in the `docs` directory:
 
 ```
 ruby -run -e httpd docs -p 8000
-```
+```
+
+## Status & Guidelines
+
+### Outstanding Work
+- Complete remaining 4 webhook examples: `tour.snoozed`, `survey.snoozed`, `helpbar.item.error`, `alert.triggered`
+
+### Example Data Standards
+When updating documentation, follow these standards:
+
+#### **Dates**: Use 2029 dates consistently in ISO 8601 format (`2029-MM-DDTHH:mm:ss.sssZ`)
+
+#### **Privacy**: Never use real user data - use fictional but realistic examples:
+- Email format: `user@example.com`, `firstname.lastname@company.tld`
+- Use example.com, example.io domains for fictional companies
+
+#### **IDs**: Use consistent 24-character hex patterns: `5f3c4232c712de665632****`
+
+### Suggested Improvements
+**High Priority:**
+- Add navigation and "Back to Overview" links
+- Add visual callouts for warnings/tips
+- Complete cURL examples for all endpoints
+
+**Medium Priority:**  
+- Add troubleshooting sections
+- Enhance schema tables with "Required" column
+- Create quick start guide
+
+**Future Considerations:**
+- Interactive API explorer
+- Multi-language SDK examples
diff --git a/docs/apis/companies.md b/docs/apis/companies.md
@@ -39,9 +39,9 @@ Retrieve a single Company.
 #### HTTP Request
 
 ```
-GET https://api.trychameleon.com/v3/analyze/companies/:id
+GET https://api.chameleon.io/v3/analyze/companies/:id
 # OR
-GET https://api.trychameleon.com/v3/analyze/company?uid=:uid
+GET https://api.chameleon.io/v3/analyze/company?uid=:uid
 ```
 
 | param | -        | description                                                  |
@@ -54,12 +54,8 @@ GET https://api.trychameleon.com/v3/analyze/company?uid=:uid
 {
   "company": {
     "id": "5f3c4232c712de665632a2a1",
-    "created_at": "2029-04-07T12:38:00Z",
-    "uid": "1868",
-    "domain": "example.com",
-    "plan": "custom-92",
-    "clv": 231902.42,
-    ...
+    "created_at": "2029-01-10T08:00:00.000Z",
+    "uid": "company_abc123"
   }
 }
 ```
@@ -89,7 +85,7 @@ GET|POST https://api.chameleon.io/v3/analyze/companies
 # As a URL parameter
 expand[profile]=min&expand[company]=skip
 
-# In the Reqeust body
+# In the Request body
 {"expand":{"profile":"min","company":"skip"}}
 ```
 
@@ -176,7 +172,7 @@ curl -H "X-Account-Secret: ACCOUNT_SECRET" \
      -H "Content-Type: application/json" \
      -X POST \
      -d '{"filters":[{"kind":"property","prop":"uid","op":"eq","value":"123"}]}' \
-     https://api.trychameleon.com/v3/analyze/companies
+     https://api.chameleon.io/v3/analyze/companies
 ```
 
 ## Delete a Company :id=companies-delete
@@ -195,9 +191,9 @@ The associated profiles can also be removed by passing `cascade=profiles` with t
 Either `id` or `uid` is required.
 
 ```
-DELETE https://api.trychameleon.com/v3/edit/companies/:id
+DELETE https://api.chameleon.io/v3/edit/companies/:id
 # OR
-DELETE https://api.trychameleon.com/v3/edit/company?uid=:uid
+DELETE https://api.chameleon.io/v3/edit/company?uid=:uid
 ```
 
 #### HTTP Response
@@ -217,9 +213,9 @@ The Deletion is an internal Chameleon record that can be referenced as proof of
 Deleting a company and all profiles associated with it can be done by passing `cascade=profiles`:
 
 ```
-DELETE https://api.trychameleon.com/v3/edit/companies/:id?cascade=profiles
+DELETE https://api.chameleon.io/v3/edit/companies/:id?cascade=profiles
 # OR
-DELETE https://api.trychameleon.com/v3/edit/company?uid=:uid&cascade=profiles
+DELETE https://api.chameleon.io/v3/edit/company?uid=:uid&cascade=profiles
 ```
 
 #### HTTP Response

diff --git a/docs/apis/profiles-search.md b/docs/apis/profiles-search.md
@@ -301,15 +301,15 @@ Notes:
     {
       "id": "5f3c4232c712de665632a6d5",
       "uid": 18821,
-      "email": "leon@chmln.co",
+      "email": "user1@example.com",
       "role": "admin",
       "invited_users_count": 4,
        ...
     },
     {
       "id": "5f3c4232c712de665632a6d6",
       "uid": 18829,
-      "email": "prehensile@chmln.co",
+      "email": "user2@example.com",
       "role": "admin",
       "invited_users_count": 6,
        ...

diff --git a/docs/apis/profiles.md b/docs/apis/profiles.md
@@ -76,7 +76,7 @@ When using a **GET** request with parameters:
 ```
 ?id=5f3c4232c712de665632a6d5
 ?uid=18821
-?email=leon@chmln.co
+?email=user@example.com
 ```
 
 When using a **POST** request send one of these properties:
@@ -85,7 +85,7 @@ When using a **POST** request send one of these properties:
 {
   "id": "5f3c4232c712de665632a6d5",
   "uid": 18821,
-  "email": "leon@chmln.co"
+  "email": "user@example.com"
 }
 ```
 
@@ -97,13 +97,27 @@ When using a **POST** request send one of these properties:
 {
   "profile": {
     "id": "5f3c4232c712de665632a6d5",
-    "uid": 18821,
-    "email": "leon@chmln.co",
-    "first_name": "Leon",
-    "role": "admin",
-    "last_import_at": "2029-04-07T12:18:00Z",
-    "invited_users_count": 4,
-     ...
+    "created_at": "2029-03-15T10:30:00.000Z",
+    "updated_at": "2029-04-07T12:18:00.000Z",
+    "uid": "user_18821",
+    "company_id": "5f3c4232c712de665632a6e8",
+    "browser_x": 1920,
+    "browser_tz": -8,
+    "browser_l": "en-US",
+    "browser_n": "chrome",
+    "browser_k": "desktop",
+    "percent": 42.87,
+    "last_seen_at": "2029-04-07T11:45:00.000Z",
+    "last_seen_session_count": 23,
+    "delivery_ids": [
+      "5f3c4232c712de665632a6f1",
+      "5f3c4232c712de665632a6f2"
+    ],
+    "company": {
+      "id": "5f3c4232c712de665632a6e8",
+      "created_at": "2029-01-10T08:00:00.000Z",
+      "uid": "company_abc123"
+    }
   }
 }
 ```

diff --git a/docs/apis/segments.md b/docs/apis/segments.md
@@ -30,7 +30,7 @@ With the Chameleon API for Segments, you can:
 > For a full list of your User / Company Properties see the [Properties API](apis/properties.md)
 
 
-## Listing Segments :id=segments-index
+## List Segments :id=segments-index
 
 Retrieve a list of segments according to the specified parameters.
 
@@ -190,3 +190,46 @@ GET https://api.chameleon.io/v3/edit/segments/:id/:kind
   }
 }
 ```
+
+------
+
+## Listing Related Experiences :id=segment-experiences-index
+
+A Segment can be configured to be attached to many Chameleon Experiences, including [Microsurveys](apis/surveys.md), [Tours](apis/tours.md) and [Launchers](apis/launchers.md) and [Rate Limit Groups](apis/limit-groups.md). This endpoint allows you to list any of these items that are currently attached to the Segment given with the ID
+
+#### HTTP Request
+
+```
+GET https://api.chameleon.io/v3/edit/segments/:id/:kind
+```
+
+| param | - | description |
+|---|---|---|
+| `id` | required | A Segment ID to lookup
+| `kind` | required | One of `tour`, `survey` or `launcher`
+
+#### HTTP Response
+
+```json
+{
+  "segment": {
+    "id": "5f3c4232c712de665632a6d7",
+    "name": "Admins",
+    ...
+  },
+  "tours": [
+    {
+      "id": "5f3c4232c712de665632a6d5",
+      "name": "Revamped Dashboard Launch",
+      "style": "auto",
+      "position": 4,
+      "published_at": "2029-04-07T12:18:00Z",
+       ...
+    },
+  ],
+  "cursor": {
+    "limit": 50,
+    "before": "5f3c4232c712de665632a2a1"
+  }
+}
+```
diff --git a/docs/apis/surveys.md b/docs/apis/surveys.md
@@ -62,22 +62,47 @@ GET https://api.chameleon.io/v3/edit/surveys
   "surveys": [
     {
       "id": "5f3c4232c712de665632a6d5",
-      "name": "Task #2 completion CES",
+      "created_at": "2029-03-10T11:20:00.000Z",
+      "updated_at": "2029-04-05T09:30:00.000Z",
+      "name": "Product Satisfaction Survey",
       "position": 1,
-      "published_at": "2029-04-07T12:18:00Z",
-       ...
+      "segment_id": "5f3c4232c712de665632a6d9",
+      "published_at": "2029-03-15T08:00:00.000Z",
+      "tag_ids": ["5f3c4232c712de665632a6f8", "5f3c4232c712de665632a6f9"],
+      "stats": {
+        "started_count": 234,
+        "last_started_at": "2029-04-05T08:45:00.000Z",
+        "completed_count": 187,
+        "last_completed_at": "2029-04-05T08:30:00.000Z",
+        "exited_count": 47,
+        "last_exited_at": "2029-04-05T08:20:00.000Z"
+      },
+      "rate_unlimit_at": null,
+      "last_dropdown_items": ["Very Satisfied", "Satisfied", "Neutral", "Dissatisfied"]
     },
     {
       "id": "5f3c4232c712de665632a2a3",
-      "name": "Admin account setup #1 completion question",
-      "position": 0,
-      "published_at": "2029-04-07T12:38:00Z",
-       ...
-    },
-    ...
+      "created_at": "2029-02-20T14:15:00.000Z",
+      "updated_at": "2029-03-25T16:22:00.000Z",
+      "name": "Feature Request Collection",
+      "position": 2,
+      "segment_id": "5f3c4232c712de665632a6e1",
+      "published_at": "2029-02-25T10:00:00.000Z",
+      "tag_ids": ["5f3c4232c712de665632a6fa"],
+      "stats": {
+        "started_count": 89,
+        "last_started_at": "2029-03-24T15:10:00.000Z",
+        "completed_count": 73,
+        "last_completed_at": "2029-03-24T14:55:00.000Z",
+        "exited_count": 16,
+        "last_exited_at": "2029-03-24T15:20:00.000Z"
+      },
+      "rate_unlimit_at": "2029-04-15T00:00:00.000Z",
+      "last_dropdown_items": ["Better Analytics", "Mobile App", "API Improvements", "More Integrations"]
+    }
   ],
   "cursor": {
-    "limit": 50,
+    "limit": 2,
     "before": "5f3c4232c712de665632a2a3"
   }
 }
@@ -146,11 +171,24 @@ GET https://api.chameleon.io/v3/edit/surveys/:id
 ```json
 {
   "survey": {
-    "id": "5f3c4232c712de665632a2a1",
-    "name": "Admin Self-serve menu",
-    "position": 0,
-    "published_at": "2029-04-07T12:38:00Z",
-    ...
+    "id": "5f3c4232c712de665632a6d5",
+    "created_at": "2029-03-10T11:20:00.000Z",
+    "updated_at": "2029-04-05T09:30:00.000Z",
+    "name": "Product Satisfaction Survey",
+    "position": 1,
+    "segment_id": "5f3c4232c712de665632a6d9",
+    "published_at": "2029-03-15T08:00:00.000Z",
+    "tag_ids": ["5f3c4232c712de665632a6f8", "5f3c4232c712de665632a6f9"],
+    "stats": {
+      "started_count": 234,
+      "last_started_at": "2029-04-05T08:45:00.000Z",
+      "completed_count": 187,
+      "last_completed_at": "2029-04-05T08:30:00.000Z",
+      "exited_count": 47,
+      "last_exited_at": "2029-04-05T08:20:00.000Z"
+    },
+    "rate_unlimit_at": null,
+    "last_dropdown_items": ["Very Satisfied", "Satisfied", "Neutral", "Dissatisfied"]
   }
 }
 ```