# Groups

Groups within the workspace. Learn more about group management [here](https://docs.secoda.com/user-management/groups).

## List Groups

> Get a list of user groups in the workspace.

```json
{"openapi":"3.0.0","info":{"title":"Secoda API","version":"8.22.39"},"tags":[{"name":"Groups","description":"Groups within the workspace. Learn more about group management [here](https://docs.secoda.com/user-management/groups).\n"}],"servers":[{"url":"https://api.secoda.co","description":"Base URL for all US cloud based workspaces"},{"url":"https://eapi.secoda.co","description":"Base URL for all EU cloud based workspaces"},{"url":"https://aapi.secoda.co","description":"Base URL for all APAC cloud based workspaces"},{"url":"https://{customer_domain}.secoda.co","description":"Base URL for On Premise Secoda workspaces","variables":{"customer_domain":{"default":"customer_domain","description":"The specific domain set up for your On Premise Secoda workspace."}}}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/auth/group":{"get":{"tags":["Groups"],"summary":"List Groups","description":"Get a list of user groups in the workspace.","responses":{"200":{"description":"List of groups.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/v1_ListResponse"},{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v1_UserGroupResponse"}}}}]}}}},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}},"components":{"schemas":{"v1_ListResponse":{"type":"object","properties":{"links":{"type":"object","description":"Indicates Links to associated pages.","properties":{"next":{"type":"string","description":"The link to the next page (null if there are no more pages)."},"previous":{"type":"string","description":"The link to the previous page (null if on the first page)."}}},"meta":{"type":"object","description":"Reprents the meta data of the response.","properties":{"page":{"type":"integer","description":"The current page number."},"previous_page":{"type":"integer","description":"The previous page number (null if on the first page)."},"next_page":{"type":"integer","description":"The next page number (null if on the last page)."}}},"count":{"type":"integer","description":"The total count of items returned."},"total_pages":{"type":"integer","description":"The total number of pages."}}},"v1_UserGroupResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the group."},"created_at":{"type":"string","description":"The creation timestamp of the group."},"updated_at":{"type":"string","description":"The last update timestamp of the group."},"users":{"type":"array","items":{"type":"string"},"description":"List of user IDs of the members in the group."},"name":{"type":"string","description":"The name of the group."},"icon":{"type":"string","description":"The icon associated with the group."},"description":{"type":"string","description":"The description of the group."},"workspace_id":{"type":"string","description":"The ID of the workspace associated with the grop."},"snowflake_role":{"description":"This field can be ignored."}}}}}}
```

## Create Group

> Create a new user group in the workspace.

```json
{"openapi":"3.0.0","info":{"title":"Secoda API","version":"8.22.39"},"tags":[{"name":"Groups","description":"Groups within the workspace. Learn more about group management [here](https://docs.secoda.com/user-management/groups).\n"}],"servers":[{"url":"https://api.secoda.co","description":"Base URL for all US cloud based workspaces"},{"url":"https://eapi.secoda.co","description":"Base URL for all EU cloud based workspaces"},{"url":"https://aapi.secoda.co","description":"Base URL for all APAC cloud based workspaces"},{"url":"https://{customer_domain}.secoda.co","description":"Base URL for On Premise Secoda workspaces","variables":{"customer_domain":{"default":"customer_domain","description":"The specific domain set up for your On Premise Secoda workspace."}}}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/auth/group":{"post":{"tags":["Groups"],"summary":"Create Group","description":"Create a new user group in the workspace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Indicates the name of the group."},"icon":{"type":"string","description":"Indicates the icon of the team."},"description":{"type":"string","description":"Description of the group."},"users":{"type":"array","description":"A list of user IDs that are part of this group.","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1_UserGroupResponse"}}}},"400":{"description":"Bad Request"},"500":{"description":"Internal Server Error"}}}}},"components":{"schemas":{"v1_UserGroupResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the group."},"created_at":{"type":"string","description":"The creation timestamp of the group."},"updated_at":{"type":"string","description":"The last update timestamp of the group."},"users":{"type":"array","items":{"type":"string"},"description":"List of user IDs of the members in the group."},"name":{"type":"string","description":"The name of the group."},"icon":{"type":"string","description":"The icon associated with the group."},"description":{"type":"string","description":"The description of the group."},"workspace_id":{"type":"string","description":"The ID of the workspace associated with the grop."},"snowflake_role":{"description":"This field can be ignored."}}}}}}
```

## Get Group

> Get a user group by their ID.

```json
{"openapi":"3.0.0","info":{"title":"Secoda API","version":"8.22.39"},"tags":[{"name":"Groups","description":"Groups within the workspace. Learn more about group management [here](https://docs.secoda.com/user-management/groups).\n"}],"servers":[{"url":"https://api.secoda.co","description":"Base URL for all US cloud based workspaces"},{"url":"https://eapi.secoda.co","description":"Base URL for all EU cloud based workspaces"},{"url":"https://aapi.secoda.co","description":"Base URL for all APAC cloud based workspaces"},{"url":"https://{customer_domain}.secoda.co","description":"Base URL for On Premise Secoda workspaces","variables":{"customer_domain":{"default":"customer_domain","description":"The specific domain set up for your On Premise Secoda workspace."}}}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/auth/group/{id}":{"get":{"tags":["Groups"],"summary":"Get Group","description":"Get a user group by their ID.","parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the group to retrieve.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1_UserGroupResponse"}}}},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}}},"components":{"schemas":{"v1_UserGroupResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the group."},"created_at":{"type":"string","description":"The creation timestamp of the group."},"updated_at":{"type":"string","description":"The last update timestamp of the group."},"users":{"type":"array","items":{"type":"string"},"description":"List of user IDs of the members in the group."},"name":{"type":"string","description":"The name of the group."},"icon":{"type":"string","description":"The icon associated with the group."},"description":{"type":"string","description":"The description of the group."},"workspace_id":{"type":"string","description":"The ID of the workspace associated with the grop."},"snowflake_role":{"description":"This field can be ignored."}}}}}}
```

## Delete Group

> Delete a group by their ID.

```json
{"openapi":"3.0.0","info":{"title":"Secoda API","version":"8.22.39"},"tags":[{"name":"Groups","description":"Groups within the workspace. Learn more about group management [here](https://docs.secoda.com/user-management/groups).\n"}],"servers":[{"url":"https://api.secoda.co","description":"Base URL for all US cloud based workspaces"},{"url":"https://eapi.secoda.co","description":"Base URL for all EU cloud based workspaces"},{"url":"https://aapi.secoda.co","description":"Base URL for all APAC cloud based workspaces"},{"url":"https://{customer_domain}.secoda.co","description":"Base URL for On Premise Secoda workspaces","variables":{"customer_domain":{"default":"customer_domain","description":"The specific domain set up for your On Premise Secoda workspace."}}}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/auth/group/{id}":{"delete":{"tags":["Groups"],"summary":"Delete Group","description":"Delete a group by their ID.","parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the group to delete.","schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}}}}
```

## Update Group

> Use this endpoint to update the Group. Editable fields include the name, description, icon, and users.

```json
{"openapi":"3.0.0","info":{"title":"Secoda API","version":"8.22.39"},"tags":[{"name":"Groups","description":"Groups within the workspace. Learn more about group management [here](https://docs.secoda.com/user-management/groups).\n"}],"servers":[{"url":"https://api.secoda.co","description":"Base URL for all US cloud based workspaces"},{"url":"https://eapi.secoda.co","description":"Base URL for all EU cloud based workspaces"},{"url":"https://aapi.secoda.co","description":"Base URL for all APAC cloud based workspaces"},{"url":"https://{customer_domain}.secoda.co","description":"Base URL for On Premise Secoda workspaces","variables":{"customer_domain":{"default":"customer_domain","description":"The specific domain set up for your On Premise Secoda workspace."}}}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/auth/group/{id}":{"patch":{"tags":["Groups"],"summary":"Update Group","description":"Use this endpoint to update the Group. Editable fields include the name, description, icon, and users.","parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the group to update.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Indicates the name of the group."}}}}}},"responses":{"200":{"description":"Group updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1_UserGroupResponse"}}}},"400":{"description":"Bad Request"},"404":{"description":"User not found"},"500":{"description":"Internal Server Error"}}}}},"components":{"schemas":{"v1_UserGroupResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the group."},"created_at":{"type":"string","description":"The creation timestamp of the group."},"updated_at":{"type":"string","description":"The last update timestamp of the group."},"users":{"type":"array","items":{"type":"string"},"description":"List of user IDs of the members in the group."},"name":{"type":"string","description":"The name of the group."},"icon":{"type":"string","description":"The icon associated with the group."},"description":{"type":"string","description":"The description of the group."},"workspace_id":{"type":"string","description":"The ID of the workspace associated with the grop."},"snowflake_role":{"description":"This field can be ignored."}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.secoda.co/api/reference/groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.