Groups

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 endpoint.

List Groups

Return all groups in your workspace.

Endpoint

GET /api/v1/groups

Response

array

Show Group object

string

Group identifier

string

Display name

string

Hex colour used in the Polyvia Platform UI

integer

Unix timestamp (ms)

Example

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

from polyvia import Polyvia

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

for g in client.groups.list():
    print(g.id, g.name)

{
  "groups": [
    {
      "id":         "g_finance",
      "name":       "Finance",
      "color":      "#3b82f6",
      "created_at": 1712345678000
    }
  ]
}

Create Group

Create a new group.

Endpoint

POST /api/v1/groups

Request Body

application/json

string

required

Display name for the group

Response

string

The newly created group identifier

Example

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

group = client.groups.create("Finance")
group_id = group["group_id"]

{
  "group_id": "g_finance"
}

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

string

required

The group identifier

Example

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

client.groups.delete_documents("g_finance")

{ "ok": true }

Delete Group

Delete an empty group. The group must have no documents assigned to it — call 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

string

required

The group identifier

Example

# 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>"

# 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")

{ "ok": true }

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

Get Started

Products

API Reference

Releases

List Groups

Endpoint

Response

Example

Create Group

Endpoint

Request Body

Response

Example

Delete All Documents in a Group

Endpoint

Path Parameters

Example

Delete Group

Endpoint

Path Parameters

Example

​List Groups

​Endpoint

​Response

​Example

​Create Group

​Endpoint

​Request Body

​Response

​Example

​Delete All Documents in a Group

​Endpoint

​Path Parameters

​Example

​Delete Group

​Endpoint

​Path Parameters

​Example

List Groups

Endpoint

Response

Example

Create Group

Endpoint

Request Body

Response

Example

Delete All Documents in a Group

Endpoint

Path Parameters

Example

Delete Group

Endpoint

Path Parameters

Example