diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index f644c84f9e..3dd66a2a44 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -5893,6 +5893,7 @@ project_id_server:
 project_id_server_action:
   description: |
     The ID of the project which initiated the server action.
+    This can be ``null`` for ``nova-manage``-initiated actions.
   in: body
   required: true
   type: string
@@ -7395,6 +7396,7 @@ user_id_migration_2_80:
 user_id_server_action:
   description: |
     The ID of the user which initiated the server action.
+    This can be ``null`` for ``nova-manage``-initiated actions.
   in: body
   required: true
   type: string
diff --git a/nova/api/openstack/compute/schemas/instance_actions.py b/nova/api/openstack/compute/schemas/instance_actions.py
index 67dc1b3fac..61a229b799 100644
--- a/nova/api/openstack/compute/schemas/instance_actions.py
+++ b/nova/api/openstack/compute/schemas/instance_actions.py
@@ -60,6 +60,9 @@ index_response = {
                     'action': {'type': 'string'},
                     'instance_uuid': {'type': 'string', 'format': 'uuid'},
                     'message': {'type': ['null', 'string']},
+                    # NOTE(stephenfin): While this will always be set for
+                    # API-initiated actions, it will not be set for e.g.
+                    # `nova-manage`-initiated actions
                     'project_id': {
                         'type': ['null', 'string'],
                         'pattern': '^[a-zA-Z0-9-]*$',
@@ -68,6 +71,8 @@ index_response = {
                     },
                     'request_id': {'type': 'string'},
                     'start_time': {'type': 'string', 'format': 'date-time'},
+                    # NOTE(stephenfin): As with project_id, this can be null
+                    # under select circumstances.
                     'user_id': {
                         'type': ['null', 'string'],
                         'pattern': '^[a-zA-Z0-9-]*$',