From 26c91f01c6f64db3fbd8a19e87e803bff0efbf65 Mon Sep 17 00:00:00 2001
From: Arthur <worldnomad@gmail.com>
Date: Tue, 21 Oct 2025 10:27:10 -0700
Subject: [PATCH] 19724 update docs

---
 docs/integrations/graphql-api.md | 106 ++++++++++++++++++++++++++++++-
 1 file changed, 104 insertions(+), 2 deletions(-)

diff --git a/docs/integrations/graphql-api.md b/docs/integrations/graphql-api.md
index 78d86f11c..b7f64639e 100644
--- a/docs/integrations/graphql-api.md
+++ b/docs/integrations/graphql-api.md
@@ -16,6 +16,28 @@ http://netbox/graphql/ \
 
 The response will include the requested data formatted as JSON:
 
+```json
+{
+  "data": {
+    "circuits": [
+      {
+        "cid": "1002840283",
+        "provider": {
+          "name": "CenturyLink"
+        }
+      },
+      {
+        "cid": "1002840457",
+        "provider": {
+          "name": "CenturyLink"
+        }
+      }
+    ]
+  }
+}
+```
+If using the GraphQL API v2 the format will be:
+
 ```json
 {
   "data": {
@@ -50,17 +72,30 @@ NetBox provides both a singular and plural query field for each object type:
 For example, query `device(id:123)` to fetch a specific device (identified by its unique ID), and query `device_list` (with an optional set of filters) to fetch all devices.
 
 !!! note "Changed in NetBox v4.5"
-    List queries now return paginated results. The actual objects are contained within the `results` field of the response, along with `total_count` and `page_info` fields for pagination metadata. Prior to v4.5, list queries returned objects directly as an array.
+    If using the GraphQL API v2, List queries now return paginated results. The actual objects are contained within the `results` field of the response, along with `total_count` and `page_info` fields for pagination metadata. Prior to v4.5, list queries returned objects directly as an array.
 
 For more detail on constructing GraphQL queries, see the [GraphQL queries documentation](https://graphql.org/learn/queries/).  For filtering and lookup syntax, please refer to the [Strawberry Django documentation](https://strawberry.rocks/docs/django/guide/filters).
 
 ## Filtering
 
 !!! note "Changed in NetBox v4.3"
-    The filtering syntax fo the GraphQL API has changed substantially in NetBox v4.3.
+    The filtering syntax for the GraphQL API has changed substantially in NetBox v4.3.
 
 Filters can be specified as key-value pairs within parentheses immediately following the query name. For example, the following will return only active sites:
 
+```
+query {
+  site_list(
+    filters: {
+      status: STATUS_ACTIVE
+    }
+  ) {
+    name
+  }
+}
+```
+If using the GraphQL API v2 the format will be:
+
 ```
 query {
   site_list(
@@ -77,6 +112,26 @@ query {
 
 Filters can be combined with logical operators, such as `OR` and `NOT`. For example, the following will return every site that is planned _or_ assigned to a tenant named Foo:
 
+```
+query {
+  site_list(
+    filters: {
+      status: STATUS_PLANNED,
+      OR: {
+        tenant: {
+          name: {
+            exact: "Foo"
+          }
+        }
+      }
+    }
+  ) {
+    name
+  }
+}
+```
+If using the GraphQL API v2 the format will be:
+
 ```
 query {
   site_list(
@@ -100,6 +155,19 @@ query {
 
 Filtering can also be applied to related objects. For example, the following query will return only enabled interfaces for each device:
 
+```
+query {
+  device_list {
+    id
+    name
+    interfaces(filters: {enabled: true}) {
+      name
+    }
+  }
+}
+```
+If using the GraphQL API v2 the format will be:
+
 ```
 query {
   device_list {
@@ -118,6 +186,29 @@ query {
 
 Certain queries can return multiple types of objects, for example cable terminations can return circuit terminations, console ports and many others.  These can be queried using [inline fragments](https://graphql.org/learn/schema/#union-types) as shown below:
 
+```
+{
+    cable_list {
+      id
+      a_terminations {
+        ... on CircuitTerminationType {
+          id
+          class_type
+        }
+        ... on ConsolePortType {
+          id
+          class_type
+        }
+        ... on ConsoleServerPortType {
+          id
+          class_type
+        }
+      }
+    }
+}
+```
+If using the GraphQL API v2 the format will be:
+
 ```
 {
   cable_list {
@@ -146,6 +237,17 @@ The field "class_type" is an easy way to distinguish what type of object it is w
 
 ## Pagination
 
+Queries can be paginated by specifying pagination in the query and supplying an offset and optionaly a limit in the query.  If no limit is given, a default of 100 is used.  Queries are not paginated unless requested in the query. An example paginated query is shown below:
+
+```
+query {
+  device_list(pagination: { offset: 0, limit: 20 }) {
+    id
+  }
+}
+```
+### Pagination in GraphQL API V2
+
 All list queries return paginated results using the `OffsetPaginated` type, which includes:
 
 - `results`: The list of objects matching the query