diff --git a/docs/api-reference/organization/add-org-member.mdx b/docs/api-reference/organization/add-org-member.mdx
index 53056658e5..82bda4a15d 100644
--- a/docs/api-reference/organization/add-org-member.mdx
+++ b/docs/api-reference/organization/add-org-member.mdx
@@ -1,4 +1,9 @@
 ---
 title: 'Add Member'
 openapi: post /api/v1/orgs/organizations/{org_id}/members/
----
\ No newline at end of file
+---
+
+The API provides two roles for organization members:
+
+- `READER`: Allows viewing of organization resources.
+- `OWNER`: Grants full administrative access to manage the organization and its resources.
diff --git a/docs/api-reference/organization/update-org-member.mdx b/docs/api-reference/organization/update-org-member.mdx
index 126787fa9d..d682bbcf8f 100644
--- a/docs/api-reference/organization/update-org-member.mdx
+++ b/docs/api-reference/organization/update-org-member.mdx
@@ -1,4 +1,9 @@
 ---
 title: 'Update Member'
 openapi: put /api/v1/orgs/organizations/{org_id}/members/
----
\ No newline at end of file
+---
+
+The API provides two roles for organization members:
+
+- `READER`: Allows viewing of organization resources.
+- `OWNER`: Grants full administrative access to manage the organization and its resources.
\ No newline at end of file
diff --git a/docs/api-reference/project/add-project-member.mdx b/docs/api-reference/project/add-project-member.mdx
index 721fd45f32..c0e5c40304 100644
--- a/docs/api-reference/project/add-project-member.mdx
+++ b/docs/api-reference/project/add-project-member.mdx
@@ -1,4 +1,9 @@
 ---
 title: 'Add Member'
 openapi: post /api/v1/orgs/organizations/{org_id}/projects/{project_id}/members/
----
\ No newline at end of file
+---
+
+The API provides two roles for project members:
+
+- `READER`: Allows viewing of project resources.
+- `OWNER`: Grants full administrative access to manage the project and its resources.
diff --git a/docs/api-reference/project/update-project-member.mdx b/docs/api-reference/project/update-project-member.mdx
index de438d92e2..5b3fb7ec34 100644
--- a/docs/api-reference/project/update-project-member.mdx
+++ b/docs/api-reference/project/update-project-member.mdx
@@ -1,4 +1,9 @@
 ---
 title: 'Update Member'
 openapi: put /api/v1/orgs/organizations/{org_id}/projects/{project_id}/members/
----
\ No newline at end of file
+---
+
+The API provides two roles for project members:
+
+- `READER`: Allows viewing of project resources.
+- `OWNER`: Grants full administrative access to manage the project and its resources.
diff --git a/docs/openapi.json b/docs/openapi.json
index 2c287e738e..23fdb3d7c9 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -158,7 +158,12 @@
 											},
 											"type": {
 												"type": "string",
-												"description": "Type of the entity (e.g., 'user', 'agent')"
+												"enum": [
+													"user",
+													"agent",
+													"app",
+													"run"
+												]
 											}
 										},
 										"required": [
@@ -229,20 +234,28 @@
 				"operationId": "entities_read",
 				"parameters": [
 					{
-						"name": "org_name",
-						"in": "query",
+						"name": "entity_type",
+						"in": "path",
+						"required": true,
 						"schema": {
-							"type": "string"
+							"type": "string",
+							"enum": [
+								"user",
+								"agent",
+								"app",
+								"run"
+							]
 						},
-						"description": "Filter entities by organization name"
+						"description": "The type of the entity (user, agent, app, or run)"
 					},
 					{
-						"name": "project_name",
-						"in": "query",
+						"name": "entity_id",
+						"in": "path",
+						"required": true,
 						"schema": {
 							"type": "string"
 						},
-						"description": "Filter entities by project name"
+						"description": "The unique identifier of the entity"
 					}
 				],
 				"responses": {
@@ -472,7 +485,9 @@
 												"type": "string",
 												"enum": [
 													"user",
-													"agent"
+													"agent",
+													"app",
+													"run"
 												]
 											}
 										},
@@ -805,7 +820,9 @@
 												"type": "string",
 												"enum": [
 													"user",
-													"agent"
+													"agent",
+													"app",
+													"run"
 												]
 											}
 										},