API Documentation
Endpoints
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /api/v1/health | Health check | public |
| POST | /api/v1/auth/register | Register with email+password+affiliation (optional); sends verification email | public |
| GET | /api/v1/auth/verify?token= | Email verification callback | public |
| POST | /api/v1/auth/login | Sign in; sets HttpOnly session cookie | public |
| POST | /api/v1/auth/logout | Sign out | public |
| POST | /api/v1/auth/reset | Request password-reset email | public |
| POST | /api/v1/auth/reset/apply | Apply a reset token to set a new password | public |
| GET | /api/v1/me | Current user + quota usage + role | session/token |
| PUT | /api/v1/me/password | Change password (revokes all sessions) | session/token |
| POST | /api/v1/tokens | Create API token (plaintext shown once) | session |
| GET | /api/v1/tokens | Token list (name, last 4 chars, timestamps) | session |
| DELETE | /api/v1/tokens/{id} | Revoke token (immediate) | session |
| POST | /api/v1/predict | Six parameters + optional model (optical/full) → spectrum JSON | session/token |
| POST | /api/v1/upload | Upload spectrum FITS/txt/csv ≤ 16 MB | session/token |
| POST | /api/v1/fit | Spectrum fit → async job id (optional fixed logc/logn/logo) | session/token |
| GET | /api/v1/jobs/{id} | Query job status and result | session/token |
| DELETE | /api/v1/jobs/{id} | Cancel a queued/running job | session/token |
| GET | /api/v1/jobs | My job history | session/token |
| GET | /api/v1/models | Available models | public |
Parameter Definitions
Six-dimensional input: Teff, effective temperature (K); log g, surface gravity; log(nHe/nH), log(nC/nH), log(nN/nH), log(nO/nH), helium/carbon/nitrogen/oxygen abundances (dex, log10 number ratios). Interpolation only within the grid boundaries — out-of-domain requests are rejected (HTTP 400). Ranges are also available live from /api/v1/models.
| Parameter | Valid range | Meaning |
|---|---|---|
| teff | 20000 – 60000 K | Effective temperature |
| logg | 5.0 – 6.5 dex | Surface gravity |
| loghe | −4 – 2 dex | Helium abundance log(nHe/nH) |
| logc | −6 – −2 dex | Carbon abundance log(nC/nH) |
| logn | −5 – −3 dex | Nitrogen abundance log(nN/nH) |
| logo | −6 – −3 dex | Oxygen abundance log(nO/nH) |
Available Models
| Model | Wavelength coverage | Grid points | Test error (median dex) |
|---|---|---|---|
| optical (default) | 3650 – 9200 Å | 9245 | 0.00816 |
| full | 100 – 20000 Å | 52984 | 0.01158 |
Error Codes
| HTTP | Description |
|---|---|
| 400 | invalid: invalid request parameters (bad email/password, out-of-range values, expired tokens, etc.) |
| 400 | invalid_file: invalid uploaded file (unsupported format, over 16 MB, too few valid points, parse failure) |
| 400 | mismatch: old password does not match |
| 401 | unauthorized: not signed in or invalid credentials |
| 403 | unverified: email not verified |
| 403 | disabled: account disabled |
| 404 | notfound: resource not found (or not yours) |
| 429 | rate: too many sign-in attempts |
| 429 | quota: daily quota exhausted (reset time returned) |
| 500 | internal: internal server error |
Citation Policy
When using results, cite this service by default (tool + model version + date); credit the method to the published paper (arXiv:2512.20185, ApJS). Until the service paper is published, no second BibTeX entry is provided.
Rate Limits & Quotas
Sign-in failures are counted per email: after the 5th failure within 60 seconds, further attempts are temporarily rejected; a successful sign-in resets the counter.
Terms of Use
Non-commercial scientific use; the model and catalogs are copyrighted by the group; results are statistical estimates, not ground truth — verify before drawing conclusions.
Known Limitations
- Extrapolation beyond the training grid is rejected, not silently returned;
- Precision depends on SNR; errors grow for low-SNR spectra;
- Composite-spectrum decomposition and multi-component fits are not yet supported.