diff --git a/docs/sources/developers/http_api/team_sync.md b/docs/sources/developers/http_api/team_sync.md index c4c0e607a2d..e3061524684 100644 --- a/docs/sources/developers/http_api/team_sync.md +++ b/docs/sources/developers/http_api/team_sync.md @@ -147,3 +147,54 @@ Status Codes: - **401** - Unauthorized - **403** - Permission denied - **404** - Team not found/Group not found + +## Search Team Groups + +`GET /api/teams/:teamId/groups/search` + +Search for team groups with pagination support. + +**Required permissions** + +| Action | Scope | +| ---------------------- | -------- | +| teams.permissions:read | teams:\* | + +**Example Request**: + +```http +GET /api/teams/1/groups/search?name=editors&query=group&page=1&perpage=10 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +[ + { + "totalCount": 1, + "teamGroups": [ + { + "orgId": 1, + "teamId": 1, + "groupId": "cn=editors,ou=groups,dc=grafana,dc=org" + } + ], + "page": 1, + "perPage": 10 + } +] +``` + +Status Codes: + +- **200** - Ok +- **400** - Bad Request (invalid team ID format or missing query parameter) +- **401** - Unauthorized +- **403** - Permission denied +- **500** - Internal Server Error diff --git a/public/api-enterprise-spec.json b/public/api-enterprise-spec.json index 532f039a68f..08eb4aebd31 100644 --- a/public/api-enterprise-spec.json +++ b/public/api-enterprise-spec.json @@ -2369,6 +2369,69 @@ } } } + }, + "/teams/{teamId}/groups/search": { + "get": { + "tags": [ + "sync_team_groups", + "enterprise" + ], + "summary": "Search for team groups with optional filtering and pagination.", + "operationId": "searchTeamGroups", + "parameters": [ + { + "type": "integer", + "format": "int64", + "name": "teamId", + "in": "path", + "required": true + }, + { + "type": "integer", + "format": "int64", + "default": 1, + "name": "page", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "default": 1000, + "description": "Number of items per page", + "name": "perpage", + "in": "query" + }, + { + "type": "string", + "description": "If set it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded.", + "name": "query", + "in": "query" + }, + { + "type": "string", + "description": "Filter by exact name match", + "name": "name", + "in": "query" + } + ], + "responses": { + "200": { + "$ref": "#/responses/searchTeamGroupsResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "403": { + "$ref": "#/responses/forbiddenError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } } }, "definitions": { @@ -7370,6 +7433,29 @@ } } }, + "SearchTeamGroupsQueryResult": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "format": "int64" + }, + "perPage": { + "type": "integer", + "format": "int64" + }, + "teamGroups": { + "type": "array", + "items": { + "$ref": "#/definitions/TeamGroupDTO" + } + }, + "totalCount": { + "type": "integer", + "format": "int64" + } + } + }, "SearchTeamQueryResult": { "type": "object", "properties": { @@ -10352,6 +10438,12 @@ "$ref": "#/definitions/SearchResult" } }, + "searchTeamGroupsResponse": { + "description": "", + "schema": { + "$ref": "#/definitions/SearchTeamGroupsQueryResult" + } + }, "searchTeamsResponse": { "description": "", "schema": { diff --git a/public/api-merged.json b/public/api-merged.json index 8da6fc47894..b7e77910163 100644 --- a/public/api-merged.json +++ b/public/api-merged.json @@ -9550,6 +9550,69 @@ } } }, + "/teams/{teamId}/groups/search": { + "get": { + "tags": [ + "sync_team_groups", + "enterprise" + ], + "summary": "Search for team groups with optional filtering and pagination.", + "operationId": "searchTeamGroups", + "parameters": [ + { + "type": "integer", + "format": "int64", + "name": "teamId", + "in": "path", + "required": true + }, + { + "type": "integer", + "format": "int64", + "default": 1, + "name": "page", + "in": "query" + }, + { + "type": "integer", + "format": "int64", + "default": 1000, + "description": "Number of items per page", + "name": "perpage", + "in": "query" + }, + { + "type": "string", + "description": "If set it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded.", + "name": "query", + "in": "query" + }, + { + "type": "string", + "description": "Filter by exact name match", + "name": "name", + "in": "query" + } + ], + "responses": { + "200": { + "$ref": "#/responses/searchTeamGroupsResponse" + }, + "400": { + "$ref": "#/responses/badRequestError" + }, + "401": { + "$ref": "#/responses/unauthorisedError" + }, + "403": { + "$ref": "#/responses/forbiddenError" + }, + "500": { + "$ref": "#/responses/internalServerError" + } + } + } + }, "/teams/{team_id}": { "get": { "tags": [ @@ -20612,6 +20675,29 @@ } } }, + "SearchTeamGroupsQueryResult": { + "type": "object", + "properties": { + "page": { + "type": "integer", + "format": "int64" + }, + "perPage": { + "type": "integer", + "format": "int64" + }, + "teamGroups": { + "type": "array", + "items": { + "$ref": "#/definitions/TeamGroupDTO" + } + }, + "totalCount": { + "type": "integer", + "format": "int64" + } + } + }, "SearchTeamQueryResult": { "type": "object", "properties": { @@ -24949,6 +25035,12 @@ "$ref": "#/definitions/SearchResult" } }, + "searchTeamGroupsResponse": { + "description": "(empty)", + "schema": { + "$ref": "#/definitions/SearchTeamGroupsQueryResult" + } + }, "searchTeamsResponse": { "description": "(empty)", "schema": { diff --git a/public/openapi3.json b/public/openapi3.json index c757125dde7..ca7f23f4414 100644 --- a/public/openapi3.json +++ b/public/openapi3.json @@ -1909,6 +1909,16 @@ }, "description": "(empty)" }, + "searchTeamGroupsResponse": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchTeamGroupsQueryResult" + } + } + }, + "description": "(empty)" + }, "searchTeamsResponse": { "content": { "application/json": { @@ -10641,6 +10651,29 @@ }, "type": "object" }, + "SearchTeamGroupsQueryResult": { + "properties": { + "page": { + "format": "int64", + "type": "integer" + }, + "perPage": { + "format": "int64", + "type": "integer" + }, + "teamGroups": { + "items": { + "$ref": "#/components/schemas/TeamGroupDTO" + }, + "type": "array" + }, + "totalCount": { + "format": "int64", + "type": "integer" + } + }, + "type": "object" + }, "SearchTeamQueryResult": { "properties": { "page": { @@ -23945,6 +23978,79 @@ ] } }, + "/teams/{teamId}/groups/search": { + "get": { + "operationId": "searchTeamGroups", + "parameters": [ + { + "in": "path", + "name": "teamId", + "required": true, + "schema": { + "format": "int64", + "type": "integer" + } + }, + { + "in": "query", + "name": "page", + "schema": { + "default": 1, + "format": "int64", + "type": "integer" + } + }, + { + "description": "Number of items per page", + "in": "query", + "name": "perpage", + "schema": { + "default": 1000, + "format": "int64", + "type": "integer" + } + }, + { + "description": "If set it will return results where the query value is contained in the name field. Query values with spaces need to be URL encoded.", + "in": "query", + "name": "query", + "schema": { + "type": "string" + } + }, + { + "description": "Filter by exact name match", + "in": "query", + "name": "name", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/searchTeamGroupsResponse" + }, + "400": { + "$ref": "#/components/responses/badRequestError" + }, + "401": { + "$ref": "#/components/responses/unauthorisedError" + }, + "403": { + "$ref": "#/components/responses/forbiddenError" + }, + "500": { + "$ref": "#/components/responses/internalServerError" + } + }, + "summary": "Search for team groups with optional filtering and pagination.", + "tags": [ + "sync_team_groups", + "enterprise" + ] + } + }, "/teams/{team_id}": { "delete": { "operationId": "deleteTeamByID",