The NMMA API is asynchronous. Jobs are submitted and processed in the background. Follow these steps:
| Code | Meaning |
|---|---|
| 200 | OK — result found in cache or status retrieved |
| 202 | Accepted job submitted, processing in background |
| 400 | Bad request - missing or invalid parameter |
| 404 | Not found - job ID does not exist |
| 429 | Rate limit exceeded - 10 requests/day per user |
| 500 | Internal server error |
Each authenticated user (Astro-COLIBRI UID) is limited to 10 fit requests per day. When the limit is exceeded, the API returns HTTP 429 with a reset time.
The lightcurve_url must point to a CSV file with the following columns:
| Column | Type | Description |
|---|---|---|
| time | String (ISO) | Observation time (e.g. 2022-07-15T03:12:00) |
| magnitude | Float | Observed magnitude |
| magnitude_error | Float | Photometric uncertainty (mag) |
| filter | String | Filter name (e.g. ztfr, ztfg) |
| telescope | String | Telescope source (e.g. ztf) |
| quality | String | Data quality flag (e.g. good, bad) |
The timeshift parameter adjusts the reference time of the fit.
Pass it as a scalar or as a prior dict matching the model prior type
(use GET /nmma/api/prior_info/<model> to check):
| Shape | Prior type | Example |
|---|---|---|
| {"min": ..., "max": ...} | uniform / log-uniform | {"min": -30, "max": 1} |
| {"mu": ..., "sigma": ...} | gaussian | {"mu": 0, "sigma": 5} |
| {"peak": ...} | fixed (delta function) | {"peak": -10} |
| float | fixed scalar | -10.0 |
| null | no timeshift | null |
Returns the list of available light-curve models. Results are cached for 1 hour.
| Field | Type | Description |
|---|---|---|
| models | Object | Dictionary of model key => human-readable label |
| count | Int | Number of available models |
Returns the timeshift prior metadata for a given model.
Use this to know which shape to pass in the timeshift field of POST /nmma/api/fit.
| Parameter | Type | Description |
|---|---|---|
| model | String | Model name (e.g. salt3, Bu2019lm) |
| Field | Type | Description |
|---|---|---|
| timeshift_type | String | uniform, log-uniform, fixed, gaussian, empty |
| timeshift_min | Float | Minimum bound (uniform / log-uniform) |
| timeshift_max | Float | Maximum bound (uniform / log-uniform) |
| timeshift_peak | Float | Fixed value (delta function) |
| timeshift_mu | Float | Mean (gaussian) |
| timeshift_sigma | Float | Standard deviation (gaussian) |
Submits a light-curve fitting job. The server responds immediately with HTTP 202 and a job ID,
then processes the fit asynchronously. Poll GET /nmma/api/status/<_id>
every ~10 seconds to retrieve results. Identical requests return cached results instantly (HTTP 200).
Rate limit: 10 requests per day per Astro-COLIBRI UID.
| Parameter | Type | Description |
|---|---|---|
| event_name | String | Name of the transient candidate (e.g. SN2022oqm) |
| lightcurve_url | String | URL to the photometry CSV file - see Workflow section for format |
| uid | String | Astro-COLIBRI user ID (authentication and rate limiting) |
| Parameter | Default | Type | Description |
|---|---|---|---|
| model | salt3 | String | Model name — see GET /nmma/api/models |
| source_filter | ztf | String | Telescope source(s), comma-separated (e.g. ztf, atlas) |
| tmin | -10.0 | Float | Start time relative to trigger (days) |
| tmax | 100.0 | Float | End time relative to trigger (days) |
| dt | 0.5 | Float | Time step for model grid (days) |
| error_budget | 0.1 | Float | Photometric error budget added in quadrature (mag) |
| nlive | 2048 | Int | Live points &MDASH; higher = more accurate but slower |
| generation_seed | 42 | Int | Random seed for reproducibility |
| sampler | pymultinest | String | pymultinest, dynesty, or ultranest |
| interpolation_type | sklearn_gp | String | sklearn_gp or tensorflow |
| use_ebv | true | Boolean | Enable E(B-V) as a free parameter (sampled between 0 and ebv_max) |
| ebv_max | 0.5724 | Float | Maximum E(B-V) — pre-filled from SFD dust map at event position, user-editable |
| timeshift | null | Float or Dict | Timeshift prior — see Workflow section for all shapes |
| bestfit | true | Boolean | Save and return best-fit parameters |
| plot_colibri | true | Boolean | Generate Astro-COLIBRI light-curve plot |
| ylim | 22,16 | String | Magnitude axis limits (upper,lower) |
| xlim | 0,14 | String | Time axis limits in days (start,end) |
| Field | Type | Description |
|---|---|---|
| _id | String | SHA1 job ID - use to poll GET /nmma/api/status/<_id> |
| status | String | Always "pending" at submission |
Polls the status of a submitted fitting job. Returns the full result when
status == "completed". Recommended polling interval: every 10 seconds.
| Parameter | Type | Description |
|---|---|---|
| job_id | String | SHA1 job ID returned by POST /nmma/api/fit |
| Field | Type | When present | Description |
|---|---|---|---|
| _id | String | always | SHA1 job ID |
| status | String | always | pending | running | completed | failed |
| bestfit_params | Object | completed | Best-fit parameter values |
| lightcurve | Object | completed | {"url": "..."} - Storage URL for light-curve PNG |
| corner | Object | completed | {"url": "..."} - Storage URL for corner plot PNG |
| nmma_settings | Object | completed | All settings used for the fit |
| error | String | failed | Error message describing the failure |