diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml
index 12b0e53d79f..22d5cac8473 100644
--- a/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml
+++ b/docs/openapi/apis/cf/latest/components/requestBodies/DomainCreateRequestBody.yaml
@@ -9,31 +9,53 @@ content:
       properties:
         name:
           type: string
-          description: Name of the domain
+          description: Name of the domain; must be unique (case-insensitive)
         internal:
           type: boolean
-          description: Whether the domain is used for internal (container-to-container) traffic
+          default: false
+          description: Whether the domain is used for internal (container-to-container) traffic, or external (user-to-container) traffic
         router_group:
           type: object
           properties:
             guid:
               type: string
               format: uuid
-          description: 'The desired router group guid.  _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+              description: The desired router group guid
+          description: 'The desired router group. _note: creates a `tcp` domain; cannot be used when `internal` is set to `true` or domain is scoped to an org_'
+        enforce_route_policies:
+          type: boolean
+          default: false
+          description: When `true`, GoRouter enforces route policies for routes on this domain using mutual TLS (mTLS). Set at creation only; cannot be changed on update. Cannot be used with internal domains
+        route_policies_scope:
+          type: string
+          enum:
+            - any
+            - org
+            - space
+          description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update'
         relationships:
           type: object
           properties:
             organization:
               $ref: ../schemas/RelationshipToOne.yaml
-              description: A relationship to the organization the domain will be scoped to;  _note cannot be used when `internal` is set to `true` or domain is associated with a router group_
+              description: 'A relationship to the organization the domain will be scoped to; _note: cannot be used when `internal` is set to `true` or domain is associated with a router group_'
             shared_organizations:
               $ref: ../schemas/RelationshipToMany.yaml
-              description: A relationship to organizations the domain will be shared with  _Note cannot be used without an organization relationship_
+              description: 'A relationship to organizations the domain will be shared with. _Note: cannot be used without an organization relationship_'
+          description: Relationships to the organization the domain will be scoped to and the organizations the domain will be shared with
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the domain
     examples:
       default:
         summary: default
         value:
           name: example.com
           internal: false
+      identityAwareDomain:
+        summary: Identity-aware domain
+        value:
+          name: apps.identity
+          internal: false
+          enforce_route_policies: true
+          route_policies_scope: org
diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml
index 006b25879e7..353c65b6949 100644
--- a/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml
+++ b/docs/openapi/apis/cf/latest/components/requestBodies/DomainUpdateRequestBody.yaml
@@ -7,4 +7,14 @@ content:
       properties:
         metadata:
           $ref: '../schemas/Metadata.yaml'
+          description: Labels and annotations applied to the domain
       description: Request schema for updating a domain
+    examples:
+      default:
+        summary: default
+        value:
+          metadata:
+            labels:
+              key: value
+            annotations:
+              note: detailed information
diff --git a/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml b/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml
index 53466cecdf6..f6b5cc66726 100644
--- a/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml
+++ b/docs/openapi/apis/cf/latest/components/requestBodies/IsolationSegmentCreate.yaml
@@ -1,4 +1,5 @@
 description: Isolation segment to create
+required: true
 content:
   application/json:
     schema:
@@ -6,9 +7,10 @@ content:
       properties:
         name:
           type: string
-          description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness
+          description: Name of the isolation segment; must be unique (case-insensitive)
         metadata:
           $ref: ../schemas/Metadata.yaml
+          description: Labels and annotations applied to the isolation segment
       required:
         - name
     examples:
diff --git a/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml b/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml
index 520314e54e4..0af37f0dea8 100644
--- a/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml
+++ b/docs/openapi/apis/cf/latest/components/schemas/Domain.yaml
@@ -9,14 +9,15 @@ allOf:
         type: boolean
         description: Whether the domain is used for internal (container-to-container) traffic
       router_group:
-        type: 
+        type:
           - object
           - 'null'
         properties:
           guid:
             type: string
             format: uuid
-        description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
+            description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
+        description: The router group the domain routes `tcp` traffic through; if set, the domain will only be available for `tcp` traffic
       supported_protocols:
         type: array
         items:
@@ -25,10 +26,29 @@ allOf:
             - http
             - tcp
         description: Available protocols for routes using the domain, currently `http` and `tcp`
+      enforce_route_policies:
+        type: boolean
+        description: When `true`, GoRouter enforces route policies for routes on this domain. This field only appears in the response when set to `true`. Set at creation only; cannot be changed on update
+      route_policies_scope:
+        type: string
+        enum:
+          - any
+          - org
+          - space
+        description: 'Operator-defined boundary for allowed callers: `any`, `org`, or `space`. Required when `enforce_route_policies` is `true`. This field only appears when `enforce_route_policies` is `true`. Set at creation only; cannot be changed on update'
       relationships:
-        $ref: './Relationships.yaml'
+        type: object
+        properties:
+          organization:
+            $ref: './RelationshipToOne.yaml'
+            description: The organization the domain is scoped to; if set, the domain will only be available in that organization; otherwise, the domain will be globally available
+          shared_organizations:
+            $ref: './RelationshipToMany.yaml'
+            description: Organizations the domain is shared with; if set, the domain will be available in these organizations in addition to the organization the domain is scoped to
+        description: Relationships to the organization the domain is scoped to and the organizations the domain is shared with
       metadata:
         $ref: './Metadata.yaml'
+        description: Labels and annotations applied to the domain
       links:
         type: object
         properties:
@@ -37,15 +57,18 @@ allOf:
             description: The URL to get this domain
           organization:
             $ref: './Link.yaml'
-            description: The URL to get the organization for this domain
+            description: The URL to get the organization this domain is scoped to; only present for organization-scoped domains
           route_reservations:
             $ref: './Link.yaml'
-            description: The URL to get the route reservations for this domain
+            description: The URL to check which routes are reserved for this domain
           shared_organizations:
             $ref: './Link.yaml'
-            description: The URL to get the shared organizations for this domain
+            description: The URL to get the organizations this domain is shared with; only present for organization-scoped domains
           router_group:
             $ref: './Link.yaml'
-            description: The URL to get the router group for this domain
-description: |
-  A domain is a fully qualified domain name that is used for application routes. A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.
+            description: The URL to get the router group for this domain; only present for domains associated with a router group
+        description: Links to related resources
+description: |-
+  Domains represent a [fully qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) that is used for application routes.
+
+  A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access.
diff --git a/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml b/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml
index 4cebea5d499..8c477f390aa 100644
--- a/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml
+++ b/docs/openapi/apis/cf/latest/components/schemas/DomainList.yaml
@@ -2,7 +2,10 @@ type: object
 properties:
   pagination:
     $ref: './Pagination.yaml'
+    description: Pagination information for the list of domains
   resources:
     type: array
     items:
       $ref: './Domain.yaml'
+    description: List of domains
+description: A paginated list of domains
diff --git a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml
index 4007eaa6233..cf243ef0a7d 100644
--- a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml
+++ b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegment.yaml
@@ -4,9 +4,10 @@ allOf:
   - properties:
       name:
         type: string
-        description: The name of the isolation segment
+        description: Name of the isolation segment
       metadata:
         $ref: './Metadata.yaml'
+        description: Labels and annotations on the isolation segment
       links:
         type: object
         properties:
@@ -15,5 +16,6 @@ allOf:
             description: The URL to get this isolation segment
           organizations:
             $ref: './Link.yaml'
-            description: The URL to get the organizations for this isolation segment
-description: An isolation segment provides a dedicated pool of compute resources for an organization or space.
+            description: The URL to get the organizations entitled to this isolation segment
+        description: Links to related resources
+description: Isolation Segments provide dedicated pools of resources to which apps can be deployed to isolate workloads.
diff --git a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml
index dfc532a991f..597d9da63d8 100644
--- a/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml
+++ b/docs/openapi/apis/cf/latest/components/schemas/IsolationSegmentList.yaml
@@ -2,7 +2,10 @@ type: object
 properties:
   pagination:
     $ref: './Pagination.yaml'
+    description: Pagination information for the list of isolation segments
   resources:
     type: array
     items:
       $ref: './IsolationSegment.yaml'
+    description: List of isolation segments
+description: A paginated list of isolation segments
diff --git a/docs/openapi/apis/cf/latest/paths/Domains.yaml b/docs/openapi/apis/cf/latest/paths/Domains.yaml
index 06bf38364ac..2115e074963 100644
--- a/docs/openapi/apis/cf/latest/paths/Domains.yaml
+++ b/docs/openapi/apis/cf/latest/paths/Domains.yaml
@@ -1,14 +1,27 @@
 /v3/domains:
   get:
     summary: List domains
-    description: Retrieve all domains the user has access to.
+    description: |-
+      Retrieve all domains the user has access to.
+
+      **Permitted roles:** All Roles
     operationId: listDomains
     tags:
       - Domains
     parameters:
       - $ref: ../components/parameters/Page.yaml
       - $ref: ../components/parameters/PerPage.yaml
-      - $ref: ../components/parameters/OrderBy.yaml
+      - name: order_by
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+            - created_at
+            - -created_at
+            - updated_at
+            - -updated_at
+        description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`
       - $ref: ../components/parameters/CreatedAts.yaml
       - $ref: ../components/parameters/UpdatedAts.yaml
       - $ref: ../components/parameters/LabelSelector.yaml
@@ -18,21 +31,21 @@
           type: array
           items:
             type: string
-        description: Comma-delimited list of GUIDs to filter by
+        description: Comma-delimited list of guids to filter by
       - name: names
         in: query
         schema:
           type: array
           items:
             type: string
-        description: Comma-delimited list of domain names to filter by
+        description: Comma-delimited list of domain names to filter by (case-insensitive)
       - name: organization_guids
         in: query
         schema:
           type: array
           items:
             type: string
-        description: Comma-delimited list of owning organization GUIDs to filter by
+        description: Comma-delimited list of owning organization guids to filter by
     responses:
       '200':
         description: OK
@@ -48,20 +61,20 @@
                     total_results: 3
                     total_pages: 2
                     first:
-                      href: https://api.example.org?page=1&per_page=2
+                      href: https://api.example.org/v3/domains?page=1&per_page=2
                     last:
-                      href: https://api.example.org?page=2&per_page=2
+                      href: https://api.example.org/v3/domains?page=2&per_page=2
                     next:
-                      href: https://api.example.org?page=2&per_page=2
+                      href: https://api.example.org/v3/domains?page=2&per_page=2
                     previous: null
                   resources:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5
                       created_at: '2019-03-08T01:06:19Z'
                       updated_at: '2019-03-08T01:06:19Z'
                       name: test-domain.com
                       internal: false
                       router_group:
-                        guid: 123e4567-e89b-12d3-a456-426614174000
+                        guid: 5806148f-cce6-4d86-7fbd-aa269e3f6f3f
                       supported_protocols:
                         - tcp
                       metadata:
@@ -79,6 +92,29 @@
                           href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations
                         router_group:
                           href: https://api.example.org/routing/v1/router_groups/5806148f-cce6-4d86-7fbd-aa269e3f6f3f
+                    - guid: 9b2f3d89-3f89-4f05-8188-8a2b298c79d5
+                      created_at: '2026-04-21T10:15:30Z'
+                      updated_at: '2026-04-21T10:15:30Z'
+                      name: apps.identity
+                      internal: false
+                      router_group: null
+                      supported_protocols:
+                        - http
+                      enforce_route_policies: true
+                      route_policies_scope: org
+                      metadata:
+                        labels: {}
+                        annotations: {}
+                      relationships:
+                        organization:
+                          data: null
+                        shared_organizations:
+                          data: []
+                      links:
+                        self:
+                          href: https://api.example.org/v3/domains/9b2f3d89-3f89-4f05-8188-8a2b298c79d5
+                        route_reservations:
+                          href: https://api.example.org/v3/domains/9b2f3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations
       '400':
         $ref: ../components/responses/BadRequest.yaml
       '401':
@@ -97,7 +133,10 @@
         $ref: ../components/responses/ServiceUnavailable.yaml
   post:
     summary: Create a domain
-    description: Create a domain.
+    description: |-
+      Create a domain.
+
+      **Permitted roles:** Admin, Org Manager *(when an `organization` relationship is provided)*
     operationId: createDomain
     tags:
       - Domains
@@ -110,6 +149,38 @@
           application/json:
             schema:
               $ref: ../components/schemas/Domain.yaml
+            examples:
+              default:
+                summary: default
+                value:
+                  guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5
+                  created_at: '2019-03-08T01:06:19Z'
+                  updated_at: '2019-03-08T01:06:19Z'
+                  name: test-domain.com
+                  internal: false
+                  router_group: null
+                  supported_protocols:
+                    - http
+                  metadata:
+                    labels: {}
+                    annotations: {}
+                  relationships:
+                    organization:
+                      data:
+                        guid: 3a3f3d89-3f89-4f05-8188-751b298c79d5
+                    shared_organizations:
+                      data:
+                        - guid: 404f3d89-3f89-4a72-8188-751b298d88d5
+                        - guid: 416d3d89-3f89-4b67-a189-123b298d3592
+                  links:
+                    self:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5
+                    organization:
+                      href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5
+                    route_reservations:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations
+                    shared_organizations:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations
         links:
           organization:
             operationId: getOrganization
@@ -133,7 +204,10 @@
 /v3/domains/{guid}:
   get:
     summary: Get a domain
-    description: Retrieve a domain.
+    description: |-
+      Retrieve a domain.
+
+      **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Billing Manager *(can only view domains without an organization relationship)*, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter
     operationId: getDomain
     tags:
       - Domains
@@ -146,6 +220,38 @@
           application/json:
             schema:
               $ref: ../components/schemas/Domain.yaml
+            examples:
+              default:
+                summary: default
+                value:
+                  guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5
+                  created_at: '2019-03-08T01:06:19Z'
+                  updated_at: '2019-03-08T01:06:19Z'
+                  name: test-domain.com
+                  internal: false
+                  router_group: null
+                  supported_protocols:
+                    - http
+                  metadata:
+                    labels: {}
+                    annotations: {}
+                  relationships:
+                    organization:
+                      data:
+                        guid: 3a3f3d89-3f89-4f05-8188-751b298c79d5
+                    shared_organizations:
+                      data:
+                        - guid: 404f3d89-3f89-4a72-8188-751b298d88d5
+                        - guid: 416d3d89-3f89-4b67-a189-123b298d3592
+                  links:
+                    self:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5
+                    organization:
+                      href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5
+                    route_reservations:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations
+                    shared_organizations:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations
         links:
           organization:
             operationId: getOrganization
@@ -160,32 +266,17 @@
         $ref: ../components/responses/NotFound.yaml
   patch:
     summary: Update a domain
-    description: Update a domain.
+    description: |-
+      Update a domain.
+
+      **Permitted roles:** Admin, Org Manager *(if domain is scoped to organization managed by the org manager)*
     operationId: updateDomain
     tags:
       - Domains
     parameters:
       - $ref: ../components/parameters/Guid.yaml
     requestBody:
-      description: Domain object that needs to be updated
-      required: true
-      content:
-        application/json:
-          schema:
-            type: object
-            properties:
-              metadata:
-                $ref: ../components/schemas/Metadata.yaml
-            description: Request schema for updating a domain
-          examples:
-            default:
-              summary: default
-              value:
-                metadata:
-                  labels:
-                    key: value
-                  annotations:
-                    note: detailed information
+      $ref: ../components/requestBodies/DomainUpdateRequestBody.yaml
     responses:
       '200':
         description: Successfully updated domain
@@ -193,6 +284,40 @@
           application/json:
             schema:
               $ref: ../components/schemas/Domain.yaml
+            examples:
+              default:
+                summary: default
+                value:
+                  guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5
+                  created_at: '2019-03-08T01:06:19Z'
+                  updated_at: '2019-03-08T01:06:19Z'
+                  name: test-domain.com
+                  internal: false
+                  router_group: null
+                  supported_protocols:
+                    - http
+                  metadata:
+                    labels:
+                      key: value
+                    annotations:
+                      note: detailed information
+                  relationships:
+                    organization:
+                      data:
+                        guid: 3a3f3d89-3f89-4f05-8188-751b298c79d5
+                    shared_organizations:
+                      data:
+                        - guid: 404f3d89-3f89-4a72-8188-751b298d88d5
+                        - guid: 416d3d89-3f89-4b67-a189-123b298d3592
+                  links:
+                    self:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5
+                    organization:
+                      href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5
+                    route_reservations:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/route_reservations
+                    shared_organizations:
+                      href: https://api.example.org/v3/domains/3a5d3d89-3f89-4f05-8188-8a2b298c79d5/relationships/shared_organizations
       '400':
         $ref: ../components/responses/BadRequest.yaml
       '401':
@@ -211,7 +336,10 @@
         $ref: ../components/responses/ServiceUnavailable.yaml
   delete:
     summary: Delete a domain
-    description: Delete a domain.
+    description: |-
+      Delete a domain.
+
+      **Permitted roles:** Admin, Org Manager *(if domain is scoped to organization managed by the org manager)*
     operationId: deleteDomain
     tags:
       - Domains
@@ -239,32 +367,38 @@
 /v3/domains/{guid}/relationships/shared_organizations:
   post:
     summary: Share a domain
-    description: This endpoint shares an organization-scoped domain to other organizations specified by a list of organization guids. This will allow any of the other organizations to use the organization-scoped domain.
+    description: |-
+      This endpoint shares an organization-scoped domain to other organizations specified by a list of organization guids. This will allow any of the other organizations to use the organization-scoped domain.
+
+      **Permitted roles:** Admin, Org Manager
     operationId: shareDomain
     tags:
       - Domains
     parameters:
       - $ref: ../components/parameters/Guid.yaml
     requestBody:
-      description: List of organizations to share the domain with
+      description: The organization guids with which to share the domain
       required: true
       content:
         application/json:
           schema:
             type: object
+            required:
+              - data
             properties:
               data:
                 type: array
                 items:
                   $ref: ../components/schemas/Relationship.yaml
-            description: Organization relationships; each organization will be entitled to manage this isolation segment
+                description: The organization guids with which to share the domain
+            description: A to-many relationship containing the organization guids with which to share the domain
           examples:
             default:
               summary: default
               value:
                 data:
-                  - guid: 123e4567-e89b-12d3-a456-426614174000
-                  - guid: 123e4567-e89b-12d3-a456-426614174000
+                  - guid: 404f3d89-3f89-4a72-8188-751b298d88d5
+                  - guid: 416d3d89-3f89-4b67-a189-123b298d3592
     responses:
       '200':
         description: Successfully shared domain
@@ -275,19 +409,16 @@
               properties:
                 data:
                   type: array
-                items:
-                  type: object
-                  properties:
-                    guid:
-                      type: string
-                      format: uuid
+                  items:
+                    $ref: ../components/schemas/Relationship.yaml
+                  description: The organizations the domain is shared with
             examples:
               default:
                 summary: default
                 value:
                   data:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 404f3d89-3f89-4a72-8188-751b298d88d5
+                    - guid: 416d3d89-3f89-4b67-a189-123b298d3592
       '401':
         $ref: ../components/responses/Unauthorized.yaml
       '403':
@@ -303,21 +434,56 @@
       Retrieve all domains available in an organization for the current user. This will return unscoped domains (those without an owning organization), domains that are scoped to the given organization (owned by the given organization), and domains that have been shared with the organization.
 
       To retrieve the default domain for an organization, use the [get default domain](#get-default-domain) endpoint.
+
+      **Permitted roles:** All Roles
     operationId: listDomainsForOrganization
     tags:
       - Domains
     parameters:
-      - $ref: ../components/parameters/Guid.yaml
-      - $ref: ../components/parameters/Page.yaml
-      - $ref: ../components/parameters/PerPage.yaml
-      - $ref: ../components/parameters/OrderBy.yaml
+      - name: guid
+        in: path
+        required: true
+        schema:
+          type: string
+          format: uuid
+        description: The guid of the organization
+      - name: guids
+        in: query
+        schema:
+          type: array
+          items:
+            type: string
+        description: Comma-delimited list of guids to filter by
       - name: names
         in: query
         schema:
           type: array
           items:
             type: string
-        description: Comma-delimited list of domain names to filter by
+        description: Comma-delimited list of domain names to filter by (case-insensitive)
+      - name: organization_guids
+        in: query
+        schema:
+          type: array
+          items:
+            type: string
+        description: Comma-delimited list of owning organization guids to filter by
+      - $ref: ../components/parameters/Page.yaml
+      - $ref: ../components/parameters/PerPage.yaml
+      - name: order_by
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+            - created_at
+            - -created_at
+            - updated_at
+            - -updated_at
+        description: Value to sort by. Defaults to ascending; prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`
+      - $ref: ../components/parameters/LabelSelector.yaml
+      - $ref: ../components/parameters/CreatedAts.yaml
+      - $ref: ../components/parameters/UpdatedAts.yaml
     responses:
       '200':
         description: OK
@@ -333,20 +499,20 @@
                     total_results: 3
                     total_pages: 2
                     first:
-                      href: https://api.example.org?page=1&per_page=2
+                      href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5/domains?page=1&per_page=2
                     last:
-                      href: https://api.example.org?page=2&per_page=2
+                      href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5/domains?page=2&per_page=2
                     next:
-                      href: https://api.example.org?page=2&per_page=2
+                      href: https://api.example.org/v3/organizations/3a3f3d89-3f89-4f05-8188-751b298c79d5/domains?page=2&per_page=2
                     previous: null
                   resources:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 3a5d3d89-3f89-4f05-8188-8a2b298c79d5
                       created_at: '2019-03-08T01:06:19Z'
                       updated_at: '2019-03-08T01:06:19Z'
                       name: test-domain.com
                       internal: false
                       router_group:
-                        guid: 123e4567-e89b-12d3-a456-426614174000
+                        guid: 5806148f-cce6-4d86-7fbd-aa269e3f6f3f
                       supported_protocols:
                         - tcp
                       metadata:
@@ -373,7 +539,10 @@
 /v3/domains/{guid}/route_reservations:
   get:
     summary: Check reserved routes for a domain
-    description: Check if a specific route for a domain exists, regardless of the user’s visibility for the route in case the route belongs to a space the user does not belong to.
+    description: |-
+      Check if a specific route for a domain exists, regardless of the user's visibility for the route in case the route belongs to a space the user does not belong to.
+
+      **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Billing Manager *(can only check if routes exist for a domain without an organization relationship)*, Org Manager, Space Auditor, Space Developer, Space Manager, Space Supporter
     operationId: checkReservedRoutesForDomain
     tags:
       - Domains
@@ -381,19 +550,22 @@
       - $ref: ../components/parameters/Guid.yaml
       - name: host
         in: query
+        required: false
         schema:
           type: string
-        description: Hostname to filter by
+        description: Hostname to filter by; defaults to empty string if not provided and only applicable to `http` routes
       - name: path
         in: query
+        required: false
         schema:
           type: string
-        description: Path to filter by
+        description: Path to filter by; defaults to empty string if not provided and only applicable to `http` routes
       - name: port
         in: query
+        required: false
         schema:
           type: integer
-        description: Port to filter by
+        description: Port to filter by; only applicable to `tcp` routes and required for `tcp` routes
     responses:
       '200':
         description: OK
@@ -404,6 +576,7 @@
               properties:
                 matching_route:
                   type: boolean
+                  description: Whether a route matching the given host, path, and port exists for the domain
             examples:
               default:
                 summary: default
@@ -418,7 +591,10 @@
 /v3/domains/{guid}/relationships/shared_organizations/{org_guid}:
   delete:
     summary: Unshare a domain
-    description: This endpoint removes an organization from the list of organizations an organization-scoped domain is shared with. This prevents the organization from using the organization-scoped domain.
+    description: |-
+      This endpoint removes an organization from the list of organizations an organization-scoped domain is shared with. This prevents the organization from using the organization-scoped domain.
+
+      **Permitted roles:** Admin, Org Manager *(can be in either the domain's owning organization or the organization it has been shared to)*
     operationId: unshareDomain
     tags:
       - Domains
@@ -430,7 +606,7 @@
         schema:
           type: string
           format: uuid
-        description: The GUID of the organization to unshare the domain from
+        description: The guid of the organization to unshare the domain from
     responses:
       '204':
         description: Successfully unshared domain
diff --git a/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml b/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml
index 8cc67497399..373b0ef1fa6 100644
--- a/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml
+++ b/docs/openapi/apis/cf/latest/paths/IsolationSegments.yaml
@@ -1,14 +1,29 @@
 /v3/isolation_segments:
   get:
     summary: List isolation segments
-    description: Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For anyone else, this is the isolation segments in the allowed list for any organization to which the user belongs.
+    description: |-
+      Retrieves all isolation segments to which the user has access. For admin, this is all the isolation segments in the system. For anyone else, this is the isolation segments in the allowed list for any organization to which the user belongs.
+
+      **Permitted roles:** All Roles
     operationId: listIsolationSegments
     tags:
       - Isolation Segments
     parameters:
       - $ref: ../components/parameters/Page.yaml
       - $ref: ../components/parameters/PerPage.yaml
-      - $ref: ../components/parameters/OrderBy.yaml
+      - name: order_by
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+            - created_at
+            - -created_at
+            - updated_at
+            - -updated_at
+            - name
+            - -name
+        description: Value to sort by; defaults to ascending. Prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`, and `name`
       - $ref: ../components/parameters/CreatedAts.yaml
       - $ref: ../components/parameters/UpdatedAts.yaml
       - $ref: ../components/parameters/LabelSelector.yaml
@@ -18,21 +33,21 @@
           type: array
           items:
             type: string
-        description: Comma-delimited list of isolation segment guids to filter by.
+        description: Comma-delimited list of isolation segment guids to filter by
       - name: names
         in: query
         schema:
           type: array
           items:
             type: string
-        description: Comma-delimited list of isolation segment names to filter by.
+        description: Comma-delimited list of isolation segment names to filter by (case-insensitive)
       - name: organization_guids
         in: query
         schema:
           type: array
           items:
             type: string
-        description: Comma-delimited list of organization guids to filter by.
+        description: Comma-delimited list of organization guids to filter by
     responses:
       '200':
         description: OK
@@ -55,7 +70,7 @@
                       href: https://api.example.org/v3/isolation_segments?page=2&per_page=5
                     previous: null
                   resources:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c
                       name: an_isolation_segment
                       created_at: '2016-10-19T20:25:04Z'
                       updated_at: '2016-11-08T16:41:26Z'
@@ -67,7 +82,7 @@
                       metadata:
                         annotations: {}
                         labels: {}
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac
                       name: an_isolation_segment1
                       created_at: '2016-10-19T20:29:19Z'
                       updated_at: '2016-11-08T16:41:26Z'
@@ -79,7 +94,7 @@
                       metadata:
                         annotations: {}
                         labels: {}
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: ecdc67c3-a71e-43ff-bddf-048930b8cd03
                       name: an_isolation_segment2
                       created_at: '2016-10-19T20:29:22Z'
                       updated_at: '2016-11-08T16:41:26Z'
@@ -91,7 +106,7 @@
                       metadata:
                         annotations: {}
                         labels: {}
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 424c89e4-4353-46b7-9bf4-f90bd9bacac0
                       name: an_isolation_segment3
                       created_at: '2016-10-19T20:29:27Z'
                       updated_at: '2016-11-08T16:41:26Z'
@@ -103,7 +118,7 @@
                       metadata:
                         annotations: {}
                         labels: {}
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 0a79fcec-a648-4eb8-a6c3-2b5be39047c7
                       name: an_isolation_segment4
                       created_at: '2016-10-19T20:29:33Z'
                       updated_at: '2016-11-08T16:41:26Z'
@@ -133,7 +148,10 @@
         $ref: ../components/responses/ServiceUnavailable.yaml
   post:
     summary: Create an isolation segment
-    description: Create an isolation segment.
+    description: |-
+      Create an isolation segment.
+
+      **Permitted roles:** Admin
     operationId: createIsolationSegment
     tags:
       - Isolation Segments
@@ -150,7 +168,7 @@
               default:
                 summary: default
                 value:
-                  guid: 123e4567-e89b-12d3-a456-426614174000
+                  guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c
                   name: an_isolation_segment
                   created_at: '2016-10-19T20:25:04Z'
                   updated_at: '2016-11-08T16:41:26Z'
@@ -179,7 +197,10 @@
 /v3/isolation_segments/{guid}:
   get:
     summary: Get an isolation segment
-    description: Retrieve an isolation segment to which the user has access. For admin, this is any isolation segment in the system. For anyone else, this is an isolation segment in the allowed list for any organization to which the user belongs.
+    description: |-
+      Retrieve an isolation segment to which the user has access. For admin, this is any isolation segment in the system. For anyone else, this is an isolation segment in the allowed list for any organization to which the user belongs.
+
+      **Permitted roles:** All Roles
     operationId: getIsolationSegment
     tags:
       - Isolation Segments
@@ -196,7 +217,7 @@
               default:
                 summary: default
                 value:
-                  guid: 123e4567-e89b-12d3-a456-426614174000
+                  guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c
                   name: an_isolation_segment
                   created_at: '2016-10-19T20:25:04Z'
                   updated_at: '2016-11-08T16:41:26Z'
@@ -216,7 +237,10 @@
         $ref: ../components/responses/NotFound.yaml
   patch:
     summary: Update an isolation segment
-    description: Update an isolation segment.
+    description: |-
+      Update an isolation segment.
+
+      **Permitted roles:** Admin
     operationId: updateIsolationSegment
     tags:
       - Isolation Segments
@@ -232,9 +256,10 @@
             properties:
               name:
                 type: string
-                description: The name of the isolation segment
+                description: Name of the isolation segment; isolation segment names must be unique across the entire system, and case is ignored when checking for uniqueness
               metadata:
                 $ref: ../components/schemas/Metadata.yaml
+                description: Labels and annotations applied to the isolation segment
           examples:
             default:
               summary: default
@@ -251,8 +276,8 @@
               default:
                 summary: default
                 value:
-                  guid: 123e4567-e89b-12d3-a456-426614174000
-                  name: <%= name %>
+                  guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c
+                  name: my_isolation_segment
                   created_at: '2016-10-19T20:25:04Z'
                   updated_at: '2016-11-08T16:41:26Z'
                   links:
@@ -281,7 +306,10 @@
         $ref: ../components/responses/ServiceUnavailable.yaml
   delete:
     summary: Delete an isolation segment
-    description: An isolation segment cannot be deleted if it is entitled to any organization.
+    description: |-
+      An isolation segment cannot be deleted if it is entitled to any organization.
+
+      **Permitted roles:** Admin
     operationId: deleteIsolationSegment
     tags:
       - Isolation Segments
@@ -302,27 +330,31 @@
         $ref: ../components/responses/500.yaml
 /v3/isolation_segments/{guid}/relationships/organizations:
   post:
-    summary: Entitle organizations for isolation segment
-    description: This endpoint entitles the specified organizations for the isolation segment. In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization.
+    summary: Entitle organizations for an isolation segment
+    description: |-
+      This endpoint entitles the specified organizations for the isolation segment. In the case where the specified isolation segment is the system-wide shared segment, and if an organization is not already entitled for any other isolation segment, then the shared isolation segment automatically gets assigned as the default for that organization.
+
+      **Permitted roles:** Admin
     operationId: entitleOrganizationsForIsolationSegment
     tags:
       - Isolation Segments
     parameters:
       - $ref: ../components/parameters/Guid.yaml
     requestBody:
-      description: List of organizations to entitle
+      description: Organization relationships; each organization will be entitled to manage this isolation segment
       required: true
       content:
         application/json:
           schema:
             $ref: ../components/schemas/RelationshipToMany.yaml
+            description: Organization relationships; each organization will be entitled to manage this isolation segment
           examples:
             default:
               summary: default
               value:
                 data:
-                  - guid: 123e4567-e89b-12d3-a456-426614174000
-                  - guid: 123e4567-e89b-12d3-a456-426614174000
+                  - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac
+                  - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c
     responses:
       '200':
         description: OK
@@ -335,8 +367,8 @@
                 summary: default
                 value:
                   data:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac
+                    - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c
                   links:
                     self:
                       href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations
@@ -352,14 +384,15 @@
         $ref: ../components/responses/UnprocessableEntity.yaml
   get:
     summary: List organizations relationship
-    description: This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs.
+    description: |-
+      This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs.
+
+      **Permitted roles:** All Roles
     operationId: listOrganizationsForIsolationSegment
     tags:
       - Isolation Segments
     parameters:
       - $ref: ../components/parameters/Guid.yaml
-      - $ref: ../components/parameters/Page.yaml
-      - $ref: ../components/parameters/PerPage.yaml
     responses:
       '200':
         description: OK
@@ -372,8 +405,8 @@
                 summary: default
                 value:
                   data:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 68d54d31-9b3a-463b-ba94-e8e4c32edbac
+                    - guid: b19f6525-cbd3-4155-b156-dc0c2a431b4c
                   links:
                     self:
                       href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/organizations
@@ -388,7 +421,10 @@
 /v3/isolation_segments/{guid}/relationships/organizations/{org_guid}:
   delete:
     summary: Revoke entitlement to isolation segment for an organization
-    description: This endpoint revokes the entitlement for the specified organization to the isolation segment. If the isolation segment is assigned to a space within an organization, the entitlement cannot be revoked. If the isolation segment is the organization’s default, the entitlement cannot be revoked.
+    description: |-
+      This endpoint revokes the entitlement for the specified organization to the isolation segment. If the isolation segment is assigned to a space within an organization, the entitlement cannot be revoked. If the isolation segment is the organization's default, the entitlement cannot be revoked.
+
+      **Permitted roles:** Admin
     operationId: revokeIsolationSegmentForOrganization
     tags:
       - Isolation Segments
@@ -400,7 +436,7 @@
         schema:
           type: string
           format: uuid
-        description: The GUID of the organization to revoke entitlement from.
+        description: The guid of the organization to revoke entitlement from
     responses:
       '204':
         description: No Content
@@ -415,14 +451,15 @@
 /v3/isolation_segments/{guid}/relationships/spaces:
   get:
     summary: List spaces relationship
-    description: This endpoint lists the spaces to which the isolation segment is assigned. For an Admin, this will list all associated spaces in the system. For an org manager, this will list only those associated spaces belonging to orgs for which the user is a manager. For any other user, this will list only those associated spaces to which the user has access.
+    description: |-
+      This endpoint lists the spaces to which the isolation segment is assigned. For an Admin, this will list all associated spaces in the system. For an org manager, this will list only those associated spaces belonging to orgs for which the user is a manager. For any other user, this will list only those associated spaces to which the user has access.
+
+      **Permitted roles:** All Roles
     operationId: listSpacesForIsolationSegment
     tags:
       - Isolation Segments
     parameters:
       - $ref: ../components/parameters/Guid.yaml
-      - $ref: ../components/parameters/Page.yaml
-      - $ref: ../components/parameters/PerPage.yaml
     responses:
       '200':
         description: OK
@@ -435,8 +472,8 @@
                 summary: default
                 value:
                   data:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 885735b5-aea4-4cf5-8e44-961af0e41920
+                    - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f
                   links:
                     self:
                       href: https://api.example.org/v3/isolation_segments/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/spaces
@@ -449,14 +486,44 @@
 /v3/isolation_segments/{guid}/organizations:
   get:
     summary: List organizations for isolation segment
-    description: This endpoint lists the organizations entitled for the isolation segment. For an Admin, this will list all entitled organizations in the system. For any other user, this will list only the entitled organizations to which the user belongs.
+    description: |-
+      Retrieve the organizations entitled to the isolation segment. Return only the organizations the user has access to.
+
+      **Permitted roles:** Admin, Admin Read-Only, Global Auditor, Org Auditor, Org Billing Manager, Org Manager
     operationId: listOrganizationsForIsolationSegmentShort
     tags:
       - Isolation Segments
     parameters:
       - $ref: ../components/parameters/Guid.yaml
+      - name: names
+        in: query
+        schema:
+          type: array
+          items:
+            type: string
+        description: Comma-delimited list of organization names to filter by (case-insensitive)
+      - name: guids
+        in: query
+        schema:
+          type: array
+          items:
+            type: string
+        description: Comma-delimited list of organization guids to filter by
       - $ref: ../components/parameters/Page.yaml
       - $ref: ../components/parameters/PerPage.yaml
+      - name: order_by
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+            - created_at
+            - -created_at
+            - updated_at
+            - -updated_at
+            - name
+            - -name
+        description: Value to sort by; defaults to ascending. Prepend with `-` to sort descending. Valid values are `created_at`, `updated_at`, and `name`
     responses:
       '200':
         description: OK
@@ -478,7 +545,7 @@
                     next: null
                     previous: null
                   resources:
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: 885735b5-aea4-4cf5-8e44-961af0e41920
                       created_at: '2017-02-01T01:33:58Z'
                       updated_at: '2017-02-01T01:33:58Z'
                       name: org1
@@ -495,11 +562,11 @@
                       relationships:
                         quota:
                           data:
-                            guid: 123e4567-e89b-12d3-a456-426614174000
+                            guid: b7887f5c-34bb-40c5-9778-577572e4fb2d
                       metadata:
                         labels: {}
                         annotations: {}
-                    - guid: 123e4567-e89b-12d3-a456-426614174000
+                    - guid: d4c91047-7b29-4fda-b7f9-04033e5c9c9f
                       created_at: '2017-02-02T00:14:30Z'
                       updated_at: '2017-02-02T00:14:30Z'
                       name: org2
@@ -507,7 +574,7 @@
                       relationships:
                         quota:
                           data:
-                            guid: 123e4567-e89b-12d3-a456-426614174000
+                            guid: b7887f5c-34bb-40c5-9778-577572e4fb2d
                       links:
                         self:
                           href: https://api.example.org/v3/organizations/d4c91047-7b29-4fda-b7f9-04033e5c9c9f