Skip to main content
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

​
groups
array

​
Example

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

{
  "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
​
name
string
required
Display name for the group

​
Response

​
group_id
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_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

​
group_id
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>"

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

​
group_id
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>"

{ "ok": true }
A group with documents still assigned cannot be deleted — you will receive a 400 error. Remove or reassign all documents first.