Skip to content

Facets

Show:

Note: The bucket facets route is deprecated and is not part of the v2 consumer API. Do not use it in new product integrations. For faceted filtering, use POST /v2/buckets/\{bucket_id\}/search and pass user-visible metadata predicates in the filters object. Schift keeps facet-style aggregation and filter discovery as an internal operator capability; it is not a public API surface for new consumers.

API Versions

Version	Status	Notes
`v2`	Current	Use `POST /v2/buckets/\{bucket_id\}/search` with `filters` for all new integrations.
`v1`	Deprecated	`POST /v1/buckets/\{bucket_id\}/facets` is kept for existing clients and is hidden from the public OpenAPI schema.

POST /v1/buckets/{bucket_id}/facets

Aggregate metadata key/value cardinality across a bucket’s searchable collections. The response shows the most common values for each requested field, which can be used to populate filter dropdowns or sanity-check dataset coverage.

Note: This endpoint is excluded from the public schema (include_in_schema=false). New code should migrate to v2 bucket search instead of calling it directly.

Path parameters

Name	Type	Description
`bucket_id`	string	UUID or slug of the bucket to aggregate.

Request headers

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

Request body

Field	Type	Required	Default	Description
`fields`	array of string	Yes	—	Metadata keys to aggregate. Minimum 1, maximum 20. Empty list rejected.
`limit_per_field`	integer	No	`20`	Maximum number of distinct values to return per field. Minimum 1, maximum 200.

Request example

curl -X POST https://api.schift.io/v1/buckets/product-docs/facets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "fields": ["tag", "source_url"],
    "limit_per_field": 20
  }'

Response body

Field	Type	Description
`bucket_id`	string	Resolved bucket identifier.
`facets`	object	Map of requested field names to arrays of `{value, count}` pairs.
`facets[].value`	string	A distinct metadata value for the field.
`facets[].count`	integer	Number of chunks matching that value.
`totals`	object	Map of field names to the total number of values seen across the bucket’s searchable collections.

Response example

{
  "bucket_id": "product-docs",
  "facets": {
    "tag": [
      {"value": "urgent", "count": 142},
      {"value": "reviewed", "count": 87}
    ],
    "source_url": [
      {"value": "https://docs.example.com/enterprise", "count": 65}
    ]
  },
  "totals": {
    "tag": 229,
    "source_url": 312
  }
}

Error examples

Status	Meaning	Example response
403	Query quota unavailable for the current plan.	`{"detail": "Query quota unavailable. Upgrade your plan."}`
403	No searchable collections exist for this bucket.	`{"detail": "No searchable collections for this bucket"}`
404	The specified bucket was not found.	`{"detail": "Bucket not found"}`

Migrate to v2 search with filters

Instead of discovering values with facets, new integrations should send the filter values directly to the v2 search endpoint:

curl -X POST https://api.schift.io/v2/buckets/product-docs/search \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "refund policy",
    "filters": {
      "status": "published",
      "product": "enterprise"
    }
  }'

See Filter Operators for the full predicate syntax, including eq, in, like, prefix, ranges, and cross-key $or.

See also