Skip to main content
Filters allow you to define custom criteria for selecting astronomical alerts from surveys. They use MongoDB aggregation pipelines to process alert data in real-time.

​
Create a filter

Create a new filter with a MongoDB aggregation pipeline. 
curl -X POST http://localhost:4000/filters \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High significance transients",
    "description": "Alerts with significance > 5 sigma",
    "survey": "ZTF",
    "permissions": {
      "ZTF": [1, 2, 3]
    },
    "pipeline": [
      {
        "$match": {
          "candidate.rb": {"$gte": 0.9},
          "candidate.drb": {"$gte": 0.9}
        }
      }
    ]
  }'

​
Request

​
name
string
required
Descriptive name for the filter
​
description
string
Optional detailed description of what the filter does
​
survey
string
required
Survey to run the filter on: ZTF, LSST, or DECam
​
permissions
object
required
Survey permissions mapping. For ZTF, this maps to program IDs. Required for surveys that need permissions.
​
pipeline
array
required
MongoDB aggregation pipeline stages. Must start with a $match stage.

​
Response

​
id
string
Unique identifier for the filter
​
name
string
Filter name
​
survey
string
Survey the filter runs on
​
active
boolean
Whether the filter is currently active
​
active_fid
string
ID of the currently active filter version
​
fv
array
Array of filter versions, each containing:
  • fid - Version identifier
  • pipeline - Pipeline JSON string
  • changelog - Optional change description
  • created_at - Creation timestamp (Julian Date)

​
List filters

Retrieve all filters you have access to. Admins see all filters; regular users see only their own. 
curl http://localhost:4000/filters \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get a specific filter

Retrieve details for a single filter by ID. 
curl http://localhost:4000/filters/FILTER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Update filter metadata

Update a filter’s name, description, active status, or permissions. 
curl -X PATCH http://localhost:4000/filters/FILTER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated filter name",
    "active": true,
    "active_fid": "version-id-here"
  }'

​
Request

​
name
string
New filter name
​
description
string
New description
​
active
boolean
Enable or disable the filter
​
active_fid
string
Set which filter version is active. Must be a valid version ID from fv array.
​
permissions
object
Update survey permissions

​
Add a filter version

Create a new version of an existing filter with an updated pipeline. 
curl -X POST http://localhost:4000/filters/FILTER_ID/versions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": [
      {
        "$match": {
          "candidate.rb": {"$gte": 0.95}
        }
      }
    ],
    "changelog": "Increased RB threshold to 0.95",
    "set_as_active": true
  }'

​
Request

​
pipeline
array
required
New MongoDB aggregation pipeline
​
changelog
string
Description of changes in this version
​
set_as_active
boolean
default:"true"
Whether to make this version active immediately

​
Test a filter

Test a filter pipeline against real alert data without creating a filter. 
curl -X POST http://localhost:4000/filters/test \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "survey": "ZTF",
    "permissions": {"ZTF": [1, 2, 3]},
    "pipeline": [
      {"$match": {"candidate.rb": {"$gte": 0.9}}}
    ],
    "start_jd": 2459000.5,
    "end_jd": 2459001.5,
    "limit": 10
  }'

​
Request

​
survey
string
required
Survey to test against
​
permissions
object
required
Survey permissions
​
pipeline
array
required
Pipeline to test
​
start_jd
number
Start Julian Date for test window
​
end_jd
number
End Julian Date for test window (max 7 days from start)
​
object_ids
array
List of object IDs to test (max 1000)
​
candids
array
List of candidate IDs to test (max 100000)
​
sort_by
string
Field to sort results by
​
sort_order
string
Sort order: Ascending or Descending
​
limit
number
Maximum number of results to return

​
Response

​
pipeline
array
The complete pipeline that was executed, including permissions filters
​
results
array
Array of matching alert documents

​
Test filter count

Get a count of alerts matching a filter without retrieving the full documents. 
curl -X POST http://localhost:4000/filters/test/count \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "survey": "ZTF",
    "permissions": {"ZTF": [1, 2, 3]},
    "pipeline": [
      {"$match": {"candidate.rb": {"$gte": 0.9}}}
    ],
    "start_jd": 2459000.5,
    "end_jd": 2459001.5
  }'

​
Response

​
count
number
Number of alerts matching the filter
​
pipeline
array
The complete pipeline that was executed

​
Get filter schema

Retrieve the Avro schema showing the data structure available for filtering. 
curl http://localhost:4000/filters/schemas/ZTF
Supported surveys: ZTF, LSST

​
Permissions

Only filter owners and admins can modify filters. All authenticated users can create filters and view their own.

​
Filter constraints

  • Pipelines must start with a $match stage
  • Test time windows cannot exceed 7 days (7.0 JD)
  • Maximum 1000 object IDs per test
  • Maximum 100000 candidate IDs per test
  • Surveys like ZTF require permissions to be defined

Build docs developers (and LLMs) love

Get started for freeTalk to us