> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polyvia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Groups

> Organise documents into named collections

Groups let you organise documents into named collections that can be queried or managed together. Assign documents to a group on ingest, or move them later via the [Documents](/api-reference/endpoint/documents) endpoint.

## List Groups

Return all groups in your workspace.

### Endpoint

`GET /api/v1/groups`

### Response

<ResponseField name="groups" type="array">
  <Expandable title="Group object">
    <ResponseField name="id" type="string">Group identifier</ResponseField>
    <ResponseField name="name" type="string">Display name</ResponseField>
    <ResponseField name="color" type="string">Hex colour used in the Polyvia Platform UI</ResponseField>
    <ResponseField name="created_at" type="integer">Unix timestamp (ms)</ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.polyvia.ai/api/v1/groups" \
    -H "Authorization: Bearer poly_<your-key>"
  ```

  ```python Python SDK theme={null}
  from polyvia import Polyvia

  client = Polyvia(api_key="poly_...")

  for g in client.groups.list():
      print(g.id, g.name)
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  {
    "groups": [
      {
        "id":         "g_finance",
        "name":       "Finance",
        "color":      "#3b82f6",
        "created_at": 1712345678000
      }
    ]
  }
  ```
</ResponseExample>

***

## Create Group

Create a new group.

### Endpoint

`POST /api/v1/groups`

### Request Body

`application/json`

<ParamField body="name" type="string" required>
  Display name for the group
</ParamField>

### Response

<ResponseField name="group_id" type="string">
  The newly created group identifier
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.polyvia.ai/api/v1/groups" \
    -H "Authorization: Bearer poly_<your-key>" \
    -H "Content-Type: application/json" \
    -d '{"name": "Finance"}'
  ```

  ```python Python SDK theme={null}
  group = client.groups.create("Finance")
  group_id = group["group_id"]
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  {
    "group_id": "g_finance"
  }
  ```
</ResponseExample>

***

## Delete All Documents in a Group

Remove all documents assigned to a group. The group itself is kept.

### Endpoint

`DELETE /api/v1/groups/{group_id}/documents`

### Path Parameters

<ParamField path="group_id" type="string" required>
  The group identifier
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://app.polyvia.ai/api/v1/groups/g_finance/documents" \
    -H "Authorization: Bearer poly_<your-key>"
  ```

  ```python Python SDK theme={null}
  client.groups.delete_documents("g_finance")
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  { "ok": true }
  ```
</ResponseExample>

***

## Delete Group

Delete an empty group. The group must have no documents assigned to it — call [Delete All Documents in a Group](#delete-all-documents-in-a-group) first, or pass `delete_documents=true` in the Python SDK.

### Endpoint

`DELETE /api/v1/groups/{group_id}`

### Path Parameters

<ParamField path="group_id" type="string" required>
  The group identifier
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  # First remove all documents from the group, then delete it
  curl -X DELETE "https://app.polyvia.ai/api/v1/groups/g_finance/documents" \
    -H "Authorization: Bearer poly_<your-key>"

  curl -X DELETE "https://app.polyvia.ai/api/v1/groups/g_finance" \
    -H "Authorization: Bearer poly_<your-key>"
  ```

  ```python Python SDK theme={null}
  # Convenience flag — deletes documents first, then the group
  client.groups.delete("g_finance", delete_documents=True)

  # Or in two steps
  client.groups.delete_documents("g_finance")
  client.groups.delete("g_finance")
  ```
</CodeGroup>

<ResponseExample>
  ```json Success theme={null}
  { "ok": true }
  ```
</ResponseExample>

<Warning>
  A group with documents still assigned cannot be deleted — you will receive a `400` error. Remove or reassign all documents first.
</Warning>