Aggregate

Show:

The Aggregate endpoint groups documents in a bucket by a metadata field and returns the count for each distinct value. Use it to build facets, histograms, or category summaries.

Note: This endpoint uses collection in request bodies for backward compatibility. In newer Schift APIs the same concept is called a bucket.

POST /v1/aggregate

Group and count documents by a metadata key.

Request headers

Header	Required	Description
`Authorization`	Yes	Bearer API key (`Bearer $SCHIFT_API_KEY`).
`Content-Type`	Yes	Must be `application/json`.

Request body

Parameter	Type	Required	Description
`collection`	string	Yes	Bucket name to aggregate. Kept as `collection` for compatibility.
`group_by`	string	Yes	Metadata key to group by.
`filter_key`	string	No	Optional metadata key to filter on before grouping.
`filter_value`	string	No	Optional value to match for the filter key.

Request example

Count documents by category:

curl -X POST https://api.schift.io/v1/aggregate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "collection": "product-docs",
    "group_by": "category"
  }'

Response body

Field	Type	Description
`groups`	array	List of groups with value and count.
`groups[].value`	string	The grouped value.
`groups[].count`	integer	Number of items in this group.
`total`	integer	Total count across all groups.

Response example

{
  "groups": [
    {
      "value": "Getting Started",
      "count": 12
    },
    {
      "value": "API Reference",
      "count": 28
    },
    {
      "value": "Troubleshooting",
      "count": 7
    }
  ],
  "total": 47
}

Filtered aggregation

You can pre-filter documents before grouping by supplying filter_key and filter_value. Only documents whose metadata contains the matching value are included in the aggregation.

curl -X POST https://api.schift.io/v1/aggregate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "collection": "product-docs",
    "group_by": "status",
    "filter_key": "category",
    "filter_value": "API Reference"
  }'

Response:

{
  "groups": [
    {
      "value": "published",
      "count": 22
    },
    {
      "value": "draft",
      "count": 6
    }
  ],
  "total": 28
}

Errors

Status	Meaning	Example response
402	Query quota exceeded or not allowed.	`{"detail": {"allowed": false, ...}}`
403	Query quota unavailable for the current plan.	`{"detail": "Query quota unavailable. Upgrade your plan."}`
404	The specified collection or bucket was not found.	`{"detail": "Collection not found: product-docs"}`
501	The configured vector backend does not support aggregation.	`{"detail": "Aggregate not supported by backend: <BackendName>"}`

API versions

Version	Status	Notes
`v1`	Deprecated	Current endpoint. The `collection` parameter is retained for compatibility with legacy integrations.