Skip to main content
The BOOM API provides programmatic access to astronomical alert data from multiple surveys including ZTF, LSST, and DECam. The API enables you to create filters, query alert catalogs, and manage users.

​
Base URL

The API is accessible at: 
http://localhost:4000
The domain and port can be configured via environment variables:
  • BOOM_API__DOMAIN - API domain (default: localhost)
  • BOOM_API__PORT - API port (default: 4000)

​
API structure

The BOOM API is organized into several main sections:

​
Authentication

Secure access to the API using JWT tokens. All protected endpoints require authentication.
  • POST /auth - Obtain an access token

​
Filters

Create and manage alert filters using MongoDB aggregation pipelines.
  • GET /filters - List your filters
  • POST /filters - Create a new filter
  • GET /filters/{filter_id} - Get a specific filter
  • PATCH /filters/{filter_id} - Update filter metadata
  • POST /filters/{filter_id}/versions - Add a new filter version
  • POST /filters/test - Test a filter pipeline
  • POST /filters/test/count - Get count of alerts matching a filter
  • GET /filters/schemas/{survey_name} - Get filter data schema for a survey

​
Queries

Execute analytical queries against alert catalogs.
  • POST /queries/find - Find documents matching criteria
  • POST /queries/count - Count documents matching a filter
  • POST /queries/estimated_count - Get estimated document count
  • POST /queries/cone_search - Perform cone search queries
  • POST /queries/pipeline - Execute custom aggregation pipelines

​
Catalogs

Explore and query astronomical data catalogs.
  • GET /catalogs - List available catalogs
  • GET /catalogs/{catalog_name}/indexes - Get catalog indexes
  • GET /catalogs/{catalog_name}/sample - Get sample documents

​
Users

Manage user accounts (admin only).
  • GET /users - List all users
  • POST /users - Create a new user
  • DELETE /users/{user_id} - Delete a user

​
Babamul API

User-facing API for alert access (when enabled).
  • Account management (signup, activate, auth, profile)
  • Password reset functionality
  • Kafka credentials for streaming
  • API tokens for programmatic access
  • Survey data access (alerts, objects, cutouts, cross-matches)
  • Schema access

​
Response format

All API responses follow a consistent JSON structure: 
{
  "message": "success",
  "data": {
    // Response data here
  }
}
For errors, the response includes an error message: 
{
  "message": "Error description"
}

​
HTTP status codes

The API uses standard HTTP status codes:
Status CodeMeaning
200Success
400Bad request - invalid parameters
401Unauthorized - authentication required
403Forbidden - insufficient permissions
404Not found - resource doesn’t exist
409Conflict - resource already exists
500Internal server error

​
Supported surveys

BOOM supports the following astronomical surveys:
  • ZTF - Zwicky Transient Facility
  • LSST - Legacy Survey of Space and Time
  • DECam - Dark Energy Camera
Each survey has its own data schema and requirements. Some surveys require specific permissions to access their data.

​
Rate limiting

Query timeouts can be configured using the max_time_ms parameter available in query endpoints. This prevents long-running queries from consuming excessive resources.

​
Next steps

Authentication

Learn how to authenticate and obtain access tokens

Filters

Create and manage alert filters

Queries

Query alert catalogs and run analyses

Catalogs

Explore available data catalogs

Users

Manage user accounts

Babamul

User-facing alert access API

Build docs developers (and LLMs) love

Get started for freeTalk to us