Babamul - BOOM

Babamul is a user-facing API that provides public access to astronomical alert data. When enabled via config.babamul.enabled, it allows users to sign up, authenticate, and query alert streams from surveys like ZTF and LSST.

Babamul must be enabled in your configuration file to use these endpoints. Set babamul.enabled: true in config.yaml.

Account Management

Create a new Babamul account using an email address. An activation code will be sent to your email.

curl -X POST http://localhost:4000/babamul/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Request

string

required

Valid email address for the account. Must be unique.

Response

message

string

Success message with next steps

activation_required

boolean

Whether activation is required (always true)

Show Example response

{
  "message": "Signup successful. An activation code has been sent to [email protected]. Use the /babamul/activate endpoint to activate your account and receive your password.",
  "activation_required": true
}

Activate account

Activate your Babamul account using the activation code sent to your email. Upon successful activation, you’ll receive your password.

curl -X POST http://localhost:4000/babamul/activate \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "activation_code": "your-activation-code"
  }'

Request

string

required

Email address used during signup

activation_code

string

required

Activation code received via email

Response

message

string

Success message

activated

boolean

Whether the account is activated

username

string

Generated username (derived from email)

string

Account email address

password

string

Generated password (only returned once on initial activation)

The password is only returned once during activation. Save it securely - you cannot retrieve it again.

Authenticate

Authenticate with email and password to receive a JWT access token.

curl -X POST http://localhost:4000/babamul/auth \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=your_password"

Request

string

required

Account email address (can also use username field)

password

string

required

Account password

Response

access_token

string

JWT access token for authenticating subsequent requests

token_type

string

Token type (always Bearer)

expires_in

number

Token expiration time in seconds

Get user profile

Retrieve the authenticated user’s profile information.

curl http://localhost:4000/babamul/profile \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

string

User ID (UUID)

username

string

Username

string

Email address

created_at

number

Account creation timestamp (Unix timestamp)

Password Reset

Request password reset

Request a password reset link. A reset token will be sent to the email if an activated account exists.

curl -X POST http://localhost:4000/babamul/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Request

string

required

Email address of the account

The response is always the same to prevent account enumeration. If the email exists and the account is activated, a reset link will be sent.

Reset password

Reset your password using the reset token received via email.

curl -X POST http://localhost:4000/babamul/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "token": "your-reset-token",
    "new_password": "NewSecurePassword123!"
  }'

Request

string

required

Account email address

token

string

required

Password reset token received via email

new_password

string

required

New password meeting complexity requirements:

At least 12 characters
At least one uppercase letter
At least one lowercase letter
At least one digit
At least one special character

Password resets are rate-limited to once every 15 minutes (configurable via babamul.password_reset_cooldown_minutes).

Kafka Credentials

Kafka credentials allow you to consume alert streams directly from Kafka topics.

Create Kafka credential

Create a new Kafka credential for consuming alert streams.

curl -X POST http://localhost:4000/babamul/kafka-credentials \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Kafka Client"}'

Request

name

string

required

User-defined name for the credential

Response

string

Credential ID (UUID)

name

string

User-defined name

kafka_username

string

Kafka username (format: babamul-{credential_id})

kafka_password

string

Kafka password (only returned on creation - save it securely!)

created_at

number

Creation timestamp (Unix timestamp)

The Kafka password is only returned when the credential is created. It can be retrieved later, but store it securely.

List Kafka credentials

Retrieve all Kafka credentials for the authenticated user.

curl http://localhost:4000/babamul/kafka-credentials \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

Returns an array of Kafka credential objects including decrypted passwords.

Delete Kafka credential

Delete a Kafka credential and revoke its access to Kafka topics.

curl -X DELETE http://localhost:4000/babamul/kafka-credentials/CREDENTIAL_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Path parameters

credential_id

string

required

ID of the Kafka credential to delete

API Tokens

API tokens provide long-lived authentication for programmatic access.

Create API token

Create a new API token for the authenticated user.

curl -X POST http://localhost:4000/babamul/tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Script",
    "expires_in_days": 365
  }'

Request

name

string

required

User-defined name for the token

expires_in_days

number

default:"365"

Token expiration in days (1-1095, i.e., up to 3 years)

Response

string

Token ID (UUID)

name

string

Token name

access_token

string

API token (format: bbml_...) - save this securely!

created_at

number

Creation timestamp

expires_at

number

Expiration timestamp

You can create up to 10 API tokens per user. Delete unused tokens to free up space.

List API tokens

Retrieve all API tokens for the authenticated user.

curl http://localhost:4000/babamul/tokens \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

Returns an array of token objects (without the actual token values).

string

Token ID

name

string

Token name

created_at

number

Creation timestamp

expires_at

number

Expiration timestamp

last_used_at

number

Last usage timestamp (if token has been used)

Delete API token

Revoke an API token by deleting it.

curl -X DELETE http://localhost:4000/babamul/tokens/TOKEN_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Path parameters

token_id

string

required

ID of the token to delete

Survey Data Access

Query alerts

Query alerts from a survey’s alert stream with flexible filtering options.

curl "http://localhost:4000/babamul/surveys/ztf/alerts?object_id=ZTF18aabcdef" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path parameters

survey

string

required

Survey name: ztf or lsst

Query parameters

You must provide at least one of: object_id, or (ra, dec, radius_arcsec), or a time range less than 1 Julian Date.

object_id

string

Object ID to filter alerts

number

Right Ascension in degrees for cone search

dec

number

Declination in degrees for cone search

radius_arcsec

number

Search radius in arcseconds (max 600)

start_jd

number

Start Julian Date for time range filter

end_jd

number

End Julian Date for time range filter

min_magpsf

number

Minimum PSF magnitude

max_magpsf

number

Maximum PSF magnitude

min_drb

number

Minimum DRB/reliability score

is_rock

boolean

Filter for likely rock candidates

is_star

boolean

Filter for likely star candidates

limit

number

default:"100000"

Maximum number of alerts to return (1-100000)

skip

number

default:"0"

Number of alerts to skip for pagination

For ZTF, only public alerts (programid=1) are returned through Babamul.

Get object by ID

Retrieve detailed information about a specific object including its photometric history and cross-matches.

curl http://localhost:4000/babamul/surveys/ztf/objects/ZTF18aabcdef \
  -H "Authorization: Bearer YOUR_TOKEN"

Path parameters

survey

string

required

Survey name: ztf or lsst

object_id

string

required

Object identifier

Response

Returns detailed object information including:

Most recent candidate/alert data
Full photometric history (previous candidates and forced photometry)
Cross-matches with other catalogs
Survey-to-survey matches (e.g., ZTF object matched to LSST)
Properties and classifications

Search objects

Search for objects by partial object ID.

curl "http://localhost:4000/babamul/objects?object_id=ZTF18aa&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query parameters

object_id

string

required

Partial object ID to search (supports ZTF and LSST naming)

limit

number

default:"10"

Maximum results (1-100)

Get cutouts

Retrieve image cutouts (science, template, difference) for an alert.

curl "http://localhost:4000/babamul/surveys/ztf/cutouts?candid=1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path parameters

survey

string

required

Survey name: ztf or lsst

Query parameters

Must provide either candid OR objectId:

candid

number

Alert candidate ID

objectId

string

Object ID (uses which parameter to select alert)

which

string

default:"brightest"

Which alert to use when querying by objectId: first, last, brightest, or faintest

band

string

Filter band to retrieve (e.g., g, r, i)

Response

candid

number

Alert candidate ID

cutoutScience

string

Base64-encoded FITS cutout of science image

cutoutTemplate

string

Base64-encoded FITS cutout of template image

cutoutDifference

string

Base64-encoded FITS cutout of difference image

Get Avro schema

Retrieve the Avro schema used for encoding alerts in Kafka streams.

curl http://localhost:4000/babamul/surveys/ztf/schemas

Path parameters

survey

string

required

Survey name: ztf or lsst

This endpoint does not require authentication as schemas are public.

Configuration

Babamul is configured in config.yaml:

babamul:
  enabled: true
  webapp_url: "https://your-webapp.com"  # Optional: URL for activation/reset links
  password_reset_cooldown_minutes: 15    # Rate limit for password resets

Best practices

Secure credentials - Store passwords and API tokens securely using environment variables or secret managers
Use API tokens - For programmatic access, use long-lived API tokens instead of passwords
Limit Kafka credentials - Only create Kafka credentials when needed for streaming access
Monitor usage - Track last_used_at timestamps on tokens to identify unused credentials
Filter efficiently - Use indexed fields (objectId, coordinates) for faster queries
Batch requests - Use cone-search endpoints for querying multiple positions efficiently
Respect rate limits - Be mindful of query limits and pagination for large result sets

Getting Started

Core Concepts

Guides

API Reference

Development

​Account Management

​Sign up for account

​Request

​Response

​Activate account

​Request

​Response

​Authenticate

​Request

​Response

​Get user profile

​Response

​Password Reset

​Request password reset

​Request

​Reset password

​Request

​Kafka Credentials

​Create Kafka credential

​Request

​Response

​List Kafka credentials

​Response

​Delete Kafka credential

​Path parameters

​API Tokens

​Create API token

​Request

​Response

​List API tokens

​Response

​Delete API token

​Path parameters

​Survey Data Access

​Query alerts

​Path parameters

​Query parameters

​Get object by ID

​Path parameters

​Response

​Search objects

​Query parameters

​Get cutouts

​Path parameters

​Query parameters

​Response

​Get Avro schema

​Path parameters

​Configuration

​Best practices

Build docs developers (and LLMs) love

Account Management

Sign up for account

Request

Response

Activate account

Request

Response

Authenticate

Request

Response

Get user profile

Response

Password Reset

Request password reset

Request

Reset password

Request

Kafka Credentials

Create Kafka credential

Request

Response

List Kafka credentials

Response

Delete Kafka credential

Path parameters

API Tokens

Create API token

Request

Response

List API tokens

Response

Delete API token

Path parameters

Survey Data Access

Query alerts

Path parameters

Query parameters

Get object by ID

Path parameters

Response

Search objects

Query parameters

Get cutouts

Path parameters

Query parameters

Response

Get Avro schema

Path parameters

Configuration

Best practices