Skip to main content

​
Overview

The Cevoid API supports filtering to help you retrieve specific subsets of data from your requests. Filters allow you to narrow down results based on criteria such as label associations, making it easier to work with targeted datasets.

​
Filter Structure

Filters are passed as a URL-encoded JSON string containing an array of filter objects. Each filter object must include three required fields:
  • type: The type of filter to apply
  • operator: How to combine multiple values
  • values: Array of IDs to filter by

​
Supported Filter Types

  • label: Filter posts by their associated labels

​
Supported Operators

  • OR: Returns posts matching any of the provided values
  • AND: Returns posts matching all of the provided values

​
Basic Filtering

​
Filter by Single Label

curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: {your-api-key}" \
  --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011"]}]'

​
Filter by Multiple Labels (OR)

Returns posts that have at least one of the specified labels: 
curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: {your-api-key}" \
  --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]'

​
Filter by Multiple Labels (AND)

Returns posts that have all of the specified labels: 
curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: {your-api-key}" \
  --data-urlencode 'filter=[{"type":"label","operator":"AND","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]'

​
Common Errors

​
Invalid JSON Format

Unexpected token in JSON at position 0
Solution: Ensure your filter is valid JSON and properly URL-encoded.

​
Invalid ID Format

Filter value "invalid-id" is not a valid ID
Solution: All values in the filter must be valid IDs (24-character hexadecimal strings). You can obtain label IDs from your dashboard under Settings → Labels.

​
Unsupported Filter Type

Filter type category is not supported
Solution: Currently only label is supported as a filter type.

​
Unsupported Operator

Filter operator > is not supported
Solution: Only OR and AND operators are supported.

​
Missing Required Fields

Type is required

Operator is required

Values is required
Solution: Each filter object must include type, operator, and values fields.

​
Invalid Array Structure

Filter param needs to be an array
Solution: The filter parameter must be a JSON array, even if you’re only filtering by one label. 
Filter values must be an array
Solution: The values field must be an array of IDs.

​
Filter Best Practices

​
Getting Label IDs

To use label filters, you’ll need the unique ID for each label:
  1. Log in to your Cevoid account
  2. Navigate to Settings → Labels
  3. Find the label you want to filter by
  4. Copy the label ID (shown as a 24-character string)
You can find your labels at: https://app.cevoid.com/settings/labels

​
Important Considerations

Always URL-encode your filter parameter when making requests. Invalid JSON format or incorrectly formatted IDs will result in 400 errors.
⌘I