Download OpenAPI specification:Download
SkyPortal provides an API to access most of its underlying
functionality. To use it, you will need an API token. This
can be generated via the web application from your profile page or, if
you are an admin, you may use the system provisioned token stored
inside of .tokens.yaml
.
Once you have a token, you may access SkyPortal programmatically as follows.
import requests
token = 'ea70a5f0-b321-43c6-96a1-b2de225e0339'
def api(method, endpoint, data=None):
headers = {'Authorization': f'token {token}'}
response = requests.request(method, endpoint, json=data, headers=headers)
return response
response = api('GET', 'http://localhost:5000/api/sysinfo')
print(f'HTTP code: {response.status_code}, {response.reason}')
if response.status_code in (200, 400):
print(f'JSON response: {response.json()}')
curl -s -H 'Authorization: token ea70a5f0-b321-43c6-96a1-b2de225e0339' http://localhost:5000/api/sysinfo
There are two ways to pass information along with a request: path and body parameters.
Path parameters (also called query or URL parameters) are embedded in
the URL called. For example, you can specify numPerPage
or
pageNumber
path parameters when calling /api/candidates
as
follows:
curl -s -H 'Authorization: token ea70a5f0-b321-43c6-96a1-b2de225e0339' \
http://localhost:5000/api/candidates?numPerPage=100&pageNumber=1
When using Python's requests
library, a dictionary of path
parameters can be passed in via the params
keyword argument:
token = 'ea70a5f0-b321-43c6-96a1-b2de225e0339'
response = requests.get(
"http://localhost:5000/api/sources",
params={"includeComments": True, "includeThumbnails": False},
headers={'Authorization': f'token {token}'},
)
Request body parameters (or simply: the body of the request)
contains data uploaded to a specific endpoint. These are the
parameters listed under REQUEST BODY SCHEMA: application/json
in the
API docs.
When using Python's requests
library, body parameters are specified
using the json
keyword argument:
token = "abc"
response = requests.post(
"http://localhost:5000/api/sources",
json={
"id": "14gqr",
"ra": 353.36647,
"dec": 33.646149,
"group_ids": [52, 97],
},
headers={"Authorization": f"token {token}"},
)
In the above examples, the SkyPortal server is located at
http://localhost:5000
. In case of success, the HTTP response is 200:
HTTP code: 200, OK
JSON response: {'status': 'success', 'data': {}, 'version': '0.9.dev0+git20200819.84c453a'}
On failure, it is 400; the JSON response has status="error"
with the reason
for the failure given in message
:
{
"status": "error",
"message": "Invalid API endpoint",
"data": {},
"version": "0.9.1"
}
Several API endpoints (notably the sources and candidates APIs) enforce pagination to limit the number of records that can be fetched per request. These APIs expose parameters that facilitate pagination (see the various API docs for details). A sample pagination script is included here:
import requests
import time
base_url = "https://fritz.science/api/sources"
token = "your_token_id_here"
group_ids = [4, 71] # If applicable
all_sources = []
num_per_page = 500
page = 1
total_matches = None
retry_attempts = 0
max_retry_attempts = 10
while retry_attempts <= max_retry_attempts:
r = requests.get(
f"{base_url}?group_ids={','.join([str(gid) for gid in group_ids])}&pageNumber={page}&numPerPage={num_per_page}&totalMatches={total_matches}",
headers={"Authorization": f"token {token}"},
)
if r.status_code == 429:
print("Request rate limit exceeded; sleeping 1s before trying again...")
time.sleep(1)
continue
data = r.json()
if data["status"] != "success":
print(data) # log as appropriate
retry_attempts += 1
time.sleep(5)
continue
else:
retry_attempts = 0
all_sources.extend(data["data"]["sources"])
total_matches = data["data"]["totalMatches"]
print(f"Fetched {len(all_sources)} of {total_matches} sources.")
if len(all_sources) >= total_matches:
break
page += 1
Produce a report on allocations for an instrument
instrument_id required | integer |
output_format | string Output format for analysis. Can be png or pdf |
{- "status": "success",
- "message": "string"
}
Retrieve an allocation
allocation_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "pi": "string",
- "proposal_id": "string",
- "start_date": "2022-08-17T20:51:00Z",
- "end_date": "2022-08-17T20:51:00Z",
- "hours_allocated": 0,
- "default_share_group_ids": null,
- "group_id": 0,
- "instrument_id": 0,
- "_altdata": "string"
}
}
Update an allocation on a robotic instrument
allocation_id required | integer |
pi | string Nullable The PI of the allocation's proposal. |
proposal_id | string Nullable The ID of the proposal associated with this allocation. |
start_date | string <date-time> Nullable The UTC start date of the allocation. |
end_date | string <date-time> Nullable The UTC end date of the allocation. |
hours_allocated required | number The number of hours allocated. |
default_share_group_ids | any Nullable |
group_id required | integer The ID of the Group the allocation is associated with. |
instrument_id required | integer The ID of the Instrument the allocation is associated with. |
_altdata | string Nullable |
{- "pi": "string",
- "proposal_id": "string",
- "start_date": "2022-08-17T20:51:00Z",
- "end_date": "2022-08-17T20:51:00Z",
- "hours_allocated": 0,
- "default_share_group_ids": null,
- "group_id": 0,
- "instrument_id": 0,
- "_altdata": "string"
}
{- "status": "success",
- "message": "string"
}
{- "status": "success",
- "message": "string"
}
Retrieve all allocations
instrument_id | number Instrument ID to retrieve allocations for |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "pi": "string",
- "proposal_id": "string",
- "start_date": "2022-08-17T20:51:00Z",
- "end_date": "2022-08-17T20:51:00Z",
- "hours_allocated": 0,
- "default_share_group_ids": null,
- "group_id": 0,
- "instrument_id": 0,
- "_altdata": "string"
}
]
}
Post new allocation on a robotic instrument
pi | string Nullable The PI of the allocation's proposal. |
proposal_id | string Nullable The ID of the proposal associated with this allocation. |
start_date | string <date-time> Nullable The UTC start date of the allocation. |
end_date | string <date-time> Nullable The UTC end date of the allocation. |
hours_allocated required | number The number of hours allocated. |
default_share_group_ids | any Nullable |
group_id required | integer The ID of the Group the allocation is associated with. |
instrument_id required | integer The ID of the Instrument the allocation is associated with. |
_altdata | string Nullable |
{- "pi": "string",
- "proposal_id": "string",
- "start_date": "2022-08-17T20:51:00Z",
- "end_date": "2022-08-17T20:51:00Z",
- "hours_allocated": 0,
- "default_share_group_ids": null,
- "group_id": 0,
- "instrument_id": 0,
- "_altdata": "string"
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Retrieve all observation analyses
gcnevent_id | number GcnEvent ID to retrieve observation efficiency analyses for |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "payload": null,
- "status": "string",
- "lightcurves": null,
- "gcnevent_id": 0,
- "localization_id": 0,
- "instrument_id": 0,
- "requester_id": 0
}
]
}
Retrieve all observation plan efficiency analyses
observation_plan_id | number EventObservationPlan ID to retrieve observation plan efficiency analyses for |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "payload": null,
- "status": "string",
- "lightcurves": null,
- "observation_plan_id": 0,
- "requester_id": 0
}
]
}
Retrieve an Analysis Service by id
analysis_service_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "name": "string",
- "display_name": "string",
- "description": "string",
- "version": "string",
- "contact_name": "string",
- "contact_email": "string",
- "url": "string",
- "optional_analysis_parameters": "string",
- "authentication_type": "none",
- "_authinfo": "string",
- "enabled": true,
- "analysis_type": "lightcurve_fitting",
- "input_data_types": [
- null
], - "timeout": 0,
- "upload_only": true
}
}
Delete an Analysis Service.
analysis_service_id required | integer |
{- "status": "success",
- "message": "string"
}
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "name": "string",
- "display_name": "string",
- "description": "string",
- "version": "string",
- "contact_name": "string",
- "contact_email": "string",
- "url": "string",
- "optional_analysis_parameters": "string",
- "authentication_type": "none",
- "_authinfo": "string",
- "enabled": true,
- "analysis_type": "lightcurve_fitting",
- "input_data_types": [
- null
], - "timeout": 0,
- "upload_only": true
}
]
}
Retrieve an Analysis by id
analysis_resource_type required | string What underlying data the analysis is on: must be "obj" (more to be added in the future) |
analysis_id required | int ID of the analysis to return. |
objID | string Return any analysis on an object with ID objID |
includeAnalysisData | boolean Boolean indicating whether to include the data associated with the analysis in the response. Could be a large amount of data. Only works for single analysis requests. Defaults to false. |
includeFilename | boolean Boolean indicating whether to include the filename of the data associated with the analysis in the response. Defaults to false. |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "invalid_after": "2022-08-17T20:51:00Z",
- "token": "string",
- "handled_by_url": "string",
- "status": "queued",
- "duration": 0,
- "last_activity": "2022-08-17T20:51:00Z",
- "status_message": "string",
- "_unique_id": "string",
- "hash": "string",
- "_full_name": "string",
- "show_parameters": true,
- "show_plots": true,
- "show_corner": true,
- "analysis_parameters": "string",
- "author_id": 0,
- "analysis_service_id": 0,
- "obj_id": "string"
}
}
{- "status": "success",
- "message": "string"
}
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "invalid_after": "2022-08-17T20:51:00Z",
- "token": "string",
- "handled_by_url": "string",
- "status": "queued",
- "duration": 0,
- "last_activity": "2022-08-17T20:51:00Z",
- "status_message": "string",
- "_unique_id": "string",
- "hash": "string",
- "_full_name": "string",
- "show_parameters": true,
- "show_plots": true,
- "show_corner": true,
- "analysis_parameters": "string",
- "author_id": 0,
- "analysis_service_id": 0,
- "obj_id": "string"
}
]
}
Begin an analysis run
analysis_resource_type required | string What underlying data the analysis is on: must be "obj" (more to be added in the future) |
resource_id required | string The ID of the underlying data. This would be a string for an object ID. |
analysis_service_id required | string the analysis service id to be used |
show_parameters | boolean Whether to render the parameters of this analysis |
show_plots | boolean Whether to render the plots of this analysis |
show_corner | boolean Whether to render the corner plots of this analysis |
analysis_parameters | object Dictionary of parameters to be passed thru to the analysis |
group_ids | Array of integers List of group IDs corresponding to which groups should be able to view analysis results. Defaults to all of requesting user's groups. |
{- "show_parameters": true,
- "show_plots": true,
- "show_corner": true,
- "analysis_parameters": {
- "property1": "string",
- "property2": "string"
}, - "group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string",
- "data": {
- "analysis_id": 0
}
}
Retrieve an Analysis by id
analysis_resource_type required | string What underlying data the analysis is on: must be "obj" (more to be added in the future) |
analysis_id required | int ID of the analysis to return. |
objID | string Return any analysis on an object with ID objID |
includeAnalysisData | boolean Boolean indicating whether to include the data associated with the analysis in the response. Could be a large amount of data. Only works for single analysis requests. Defaults to false. |
includeFilename | boolean Boolean indicating whether to include the filename of the data associated with the analysis in the response. Defaults to false. |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "invalid_after": "2022-08-17T20:51:00Z",
- "token": "string",
- "handled_by_url": "string",
- "status": "queued",
- "duration": 0,
- "last_activity": "2022-08-17T20:51:00Z",
- "status_message": "string",
- "_unique_id": "string",
- "hash": "string",
- "_full_name": "string",
- "show_parameters": true,
- "show_plots": true,
- "show_corner": true,
- "analysis_parameters": "string",
- "author_id": 0,
- "analysis_service_id": 0,
- "obj_id": "string"
}
}
{- "status": "success",
- "message": "string"
}
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "invalid_after": "2022-08-17T20:51:00Z",
- "token": "string",
- "handled_by_url": "string",
- "status": "queued",
- "duration": 0,
- "last_activity": "2022-08-17T20:51:00Z",
- "status_message": "string",
- "_unique_id": "string",
- "hash": "string",
- "_full_name": "string",
- "show_parameters": true,
- "show_plots": true,
- "show_corner": true,
- "analysis_parameters": "string",
- "author_id": 0,
- "analysis_service_id": 0,
- "obj_id": "string"
}
]
}
Begin an analysis run
analysis_resource_type required | string What underlying data the analysis is on: must be "obj" (more to be added in the future) |
resource_id required | string The ID of the underlying data. This would be a string for an object ID. |
analysis_service_id required | string the analysis service id to be used |
show_parameters | boolean Whether to render the parameters of this analysis |
show_plots | boolean Whether to render the plots of this analysis |
show_corner | boolean Whether to render the corner plots of this analysis |
analysis_parameters | object Dictionary of parameters to be passed thru to the analysis |
group_ids | Array of integers List of group IDs corresponding to which groups should be able to view analysis results. Defaults to all of requesting user's groups. |
{- "show_parameters": true,
- "show_plots": true,
- "show_corner": true,
- "analysis_parameters": {
- "property1": "string",
- "property2": "string"
}, - "group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string",
- "data": {
- "analysis_id": 0
}
}
Retrieve primary data associated with an Analysis.
analysis_resource_type required | string What underlying data the analysis is on: must be "obj" (more to be added in the future) |
analysis_id required | integer |
product_type required | string What type of data to retrieve: must be one of "corner", "results", or "plot" |
plot_number required | integer if product_type == "plot", which plot number should be returned? Default to zero (first plot). |
plot_kwargs | object Extra parameters to pass to the plotting functions if new plots are to be generated (e.g. with corner plots) |
PNG finding chart file
{- "plot_kwargs": {
- "property1": { },
- "property2": { }
}
}
{- "status": "error",
- "message": "string",
- "data": { }
}
Retrieve an observing run assignment
assignment_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "requester_id": 0,
- "last_modified_by_id": 0,
- "obj_id": "string",
- "comment": "string",
- "status": "string",
- "priority": "1",
- "run_id": 0
}
}
Update an assignment
assignment_id required | integer |
requester_id required | integer The ID of the User who created this assignment. |
obj_id required | string ID of the assigned Obj. |
comment | string Nullable A comment on the assignment. Typically a justification for the request, or instructions for taking the data. |
status | string Status of the assignment [done, not done, pending]. |
priority required | string <= 1 characters Enum: "1" "2" "3" "4" "5" Priority of the request (1 = lowest, 5 = highest). |
run_id required | integer ID of the ObservingRun this target was assigned to. |
{- "requester_id": 0,
- "obj_id": "string",
- "comment": "string",
- "status": "string",
- "priority": "1",
- "run_id": 0
}
{- "status": "success",
- "message": "string"
}
{- "status": "success",
- "message": "string"
}
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "requester_id": 0,
- "last_modified_by_id": 0,
- "obj_id": "string",
- "comment": "string",
- "status": "string",
- "priority": "1",
- "run_id": 0
}
]
}
Post new target assignment to observing run
comment | string An optional comment describing the request. |
obj_id required | string The ID of the object to observe. |
priority required | any Enum: "1" "2" "3" "4" "5" Priority of the request, (lowest = 1, highest = 5). |
status | string The status of the request |
run_id required | integer |
{- "comment": "string",
- "obj_id": "string",
- "priority": "1",
- "status": "string",
- "run_id": 0
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Retrieve a candidate
obj_id required | string |
includeComments | boolean Boolean indicating whether to include associated comments. Defaults to false. |
{- "status": "success",
- "message": "string",
- "data": {
- "ra": 0,
- "dec": 0,
- "id": "string",
- "ra_dis": 0,
- "dec_dis": 0,
- "ra_err": 0,
- "dec_err": 0,
- "offset": 0,
- "redshift": 0,
- "redshift_error": 0,
- "redshift_origin": "string",
- "redshift_history": null,
- "altdata": null,
- "dist_nearest_source": 0,
- "mag_nearest_source": 0,
- "e_mag_nearest_source": 0,
- "transient": true,
- "varstar": true,
- "is_roid": true,
- "score": 0,
- "origin": "string",
- "alias": null,
- "internal_key": "string",
- "detect_photometry_count": 0
}
}
Check if a Candidate exists
obj_id required | string |
{- "status": "success",
- "message": "string"
}
Delete candidate(s)
obj_id required | string |
filter_id required | integer |
{- "status": "success",
- "message": "string"
}
Retrieve all candidates
numPerPage | integer Number of candidates to return per paginated request. Defaults to 25. Capped at 500. |
pageNumber | integer Page number for paginated query results. Defaults to 1 |
totalMatches | integer Used only in the case of paginating query results - if provided, this allows for avoiding a potentially expensive query.count() call. |
savedStatus | string Enum: "all" "savedToAllSelected" "savedToAnySelected" "savedToAnyAccessible" "notSavedToAnyAccessible" "notSavedToAnySelected" "notSavedToAllSelected" String indicating the saved status to filter candidate results for. Must be one of the enumerated values. |
startDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by Candidate.passed_at >= startDate |
endDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by Candidate.passed_at <= endDate |
groupIDs | Array of integers Comma-separated string of group IDs (e.g. "1,2"). Defaults to all of user's groups if filterIDs is not provided. |
filterIDs | Array of integers Comma-separated string of filter IDs (e.g. "1,2"). Defaults to all of user's groups' filters if groupIDs is not provided. |
annotationExcludeOrigin | string Only load objects that do not have annotations from this origin. If the annotationsExcludeOutdatedDate is also given, then annotations with this origin will still be loaded if they were modified before that date. |
annotationExcludeOutdatedDate | string An Arrow parseable string designating when an existing annotation is outdated. Only relevant if giving the annotationExcludeOrigin argument. Will treat objects with outdated annotations as if they did not have that annotation, so it will load an object if it doesn't have an annotation with the origin specified or if it does have it but the annotation modified date < annotationsExcludeOutdatedDate |
sortByAnnotationOrigin | string The origin of the Annotation to sort by |
sortByAnnotationKey | string The key of the Annotation data value to sort by |
sortByAnnotationOrder | string The sort order for annotations - either "asc" or "desc". Defaults to "asc". |
annotationFilterList | Array of strings Comma-separated string of JSON objects representing annotation filters. Filter objects are expected to have keys { origin, key, value } for non-numeric value types, or { origin, key, min, max } for numeric values. |
includePhotometry | boolean Boolean indicating whether to include associated photometry. Defaults to false. |
includeSpectra | boolean Boolean indicating whether to include associated spectra. Defaults to false. |
includeComments | boolean Boolean indicating whether to include associated comments. Defaults to false. |
classifications | Array of strings Comma-separated string of classification(s) to filter for candidates matching that/those classification(s). |
minRedshift | number If provided, return only candidates with a redshift of at least this value |
maxRedshift | number If provided, return only candidates with a redshift of at most this value |
listName | string Get only candidates saved to the querying user's list, e.g., "favorites". |
listNameReject | string Get only candidates that ARE NOT saved to the querying user's list, e.g., "rejected_candidates". |
{- "status": "success",
- "message": "string",
- "data": {
- "candidates": [
- {
- "ra": 0,
- "dec": 0,
- "id": "string",
- "ra_dis": 0,
- "dec_dis": 0,
- "ra_err": 0,
- "dec_err": 0,
- "offset": 0,
- "redshift": 0,
- "redshift_error": 0,
- "redshift_origin": "string",
- "redshift_history": null,
- "altdata": null,
- "dist_nearest_source": 0,
- "mag_nearest_source": 0,
- "e_mag_nearest_source": 0,
- "transient": true,
- "varstar": true,
- "is_roid": true,
- "score": 0,
- "origin": "string",
- "alias": null,
- "internal_key": "string",
- "detect_photometry_count": 0,
- "is_source": true
}
], - "totalMatches": 0,
- "pageNumber": 0,
- "numPerPage": 0
}
}
Create new candidate(s) (one per filter).
ra | number Nullable |
dec | number Nullable |
id required | string Name of the object. |
ra_dis | number Nullable J2000 Right Ascension at discovery time [deg]. |
dec_dis | number Nullable J2000 Declination at discovery time [deg]. |
ra_err | number Nullable Error on J2000 Right Ascension at discovery time [deg]. |
dec_err | number Nullable Error on J2000 Declination at discovery time [deg]. |
offset | number Nullable Offset from nearest static object [arcsec]. |
redshift | number Nullable Redshift. |
redshift_error | number Nullable Redshift error. |
redshift_origin | string Nullable Redshift source. |
altdata | any Nullable Misc. alternative metadata stored in JSON format, e.g. |
dist_nearest_source | number Nullable Distance to the nearest Obj [arcsec]. |
mag_nearest_source | number Nullable Magnitude of the nearest Obj [AB]. |
e_mag_nearest_source | number Nullable Error on magnitude of the nearest Obj [mag]. |
transient | boolean Nullable Boolean indicating whether the object is an astrophysical transient. |
varstar | boolean Nullable Boolean indicating whether the object is a variable star. |
is_roid | boolean Nullable Boolean indicating whether the object is a moving object. |
score | number Nullable Machine learning score. |
origin | string Nullable Origin of the object. |
alias | any Nullable Alternative names for this object. |
healpix | integer Nullable |
detect_photometry_count | integer Nullable How many times the object was detected above :math: |
filter_ids required | Array of integers List of associated filter IDs |
passing_alert_id | integer Nullable ID of associated filter that created candidate |
passed_at required | string Nullable Arrow-parseable datetime string indicating when passed filter. |
{- "ra": 0,
- "dec": 0,
- "id": "string",
- "ra_dis": 0,
- "dec_dis": 0,
- "ra_err": 0,
- "dec_err": 0,
- "offset": 0,
- "redshift": 0,
- "redshift_error": 0,
- "redshift_origin": "string",
- "altdata": null,
- "dist_nearest_source": 0,
- "mag_nearest_source": 0,
- "e_mag_nearest_source": 0,
- "transient": true,
- "varstar": true,
- "is_roid": true,
- "score": 0,
- "origin": "string",
- "alias": null,
- "healpix": 0,
- "detect_photometry_count": 0,
- "filter_ids": [
- 0
], - "passing_alert_id": 0,
- "passed_at": "string"
}
{- "status": "success",
- "message": "string",
- "data": {
- "ids": [
- 0
]
}
}
Create new candidate(s) (one per filter).
ra | number Nullable |
dec | number Nullable |
id required | string Name of the object. |
ra_dis | number Nullable J2000 Right Ascension at discovery time [deg]. |
dec_dis | number Nullable J2000 Declination at discovery time [deg]. |
ra_err | number Nullable Error on J2000 Right Ascension at discovery time [deg]. |
dec_err | number Nullable Error on J2000 Declination at discovery time [deg]. |
offset | number Nullable Offset from nearest static object [arcsec]. |
redshift | number Nullable Redshift. |
redshift_error | number Nullable Redshift error. |
redshift_origin | string Nullable Redshift source. |
altdata | any Nullable Misc. alternative metadata stored in JSON format, e.g. |
dist_nearest_source | number Nullable Distance to the nearest Obj [arcsec]. |
mag_nearest_source | number Nullable Magnitude of the nearest Obj [AB]. |
e_mag_nearest_source | number Nullable Error on magnitude of the nearest Obj [mag]. |
transient | boolean Nullable Boolean indicating whether the object is an astrophysical transient. |
varstar | boolean Nullable Boolean indicating whether the object is a variable star. |
is_roid | boolean Nullable Boolean indicating whether the object is a moving object. |
score | number Nullable Machine learning score. |
origin | string Nullable Origin of the object. |
alias | any Nullable Alternative names for this object. |
healpix | integer Nullable |
detect_photometry_count | integer Nullable How many times the object was detected above :math: |
filter_ids required | Array of integers List of associated filter IDs |
passing_alert_id | integer Nullable ID of associated filter that created candidate |
passed_at required | string Nullable Arrow-parseable datetime string indicating when passed filter. |
{- "ra": 0,
- "dec": 0,
- "id": "string",
- "ra_dis": 0,
- "dec_dis": 0,
- "ra_err": 0,
- "dec_err": 0,
- "offset": 0,
- "redshift": 0,
- "redshift_error": 0,
- "redshift_origin": "string",
- "altdata": null,
- "dist_nearest_source": 0,
- "mag_nearest_source": 0,
- "e_mag_nearest_source": 0,
- "transient": true,
- "varstar": true,
- "is_roid": true,
- "score": 0,
- "origin": "string",
- "alias": null,
- "healpix": 0,
- "detect_photometry_count": 0,
- "filter_ids": [
- 0
], - "passing_alert_id": 0,
- "passed_at": "string"
}
{- "status": "success",
- "message": "string",
- "data": {
- "ids": [
- 0
]
}
}
Delete candidate(s)
obj_id required | string |
filter_id required | integer |
{- "status": "success",
- "message": "string"
}
find the sources with classifications
startDate | string Arrow-parseable date string (e.g. 2020-01-01) for when the classification was made. If provided, filter by created_at >= startDate |
endDate | string Arrow-parseable date string (e.g. 2020-01-01) for when the classification was made. If provided, filter by created_at <= endDate |
{- "status": "success",
- "message": "string",
- "data": [
- null
]
}
find the number of sources with and without a Healpix value
{- "status": "success",
- "message": "string",
- "data": {
- "totalWithoutHealpix": 0,
- "totalWithHealpix": 0
}
}
Retrieve a classification
classification_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "classification": "string",
- "taxonomy_id": 0,
- "probability": 0,
- "author_id": 0,
- "author_name": "string",
- "obj_id": "string"
}
}
Update a classification
classification required | integer |
classification required | string The assigned class. |
taxonomy_id required | integer ID of the Taxonomy in which this Classification was made. |
probability | number Nullable User-assigned probability of belonging to this class |
author_id required | integer ID of the User that made this Classification |
author_name required | string User.username or Token.id of the Classification's author. |
obj_id required | string ID of the Classification's Obj. |
group_ids | Array of integers List of group IDs corresponding to which groups should be able to view classification. |
{- "classification": "string",
- "taxonomy_id": 0,
- "probability": 0,
- "author_id": 0,
- "author_name": "string",
- "obj_id": "string",
- "group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string"
}
Delete a classification
classification_id required | integer |
{- "status": "success",
- "message": "string"
}
Retrieve all classifications
startDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by created_at >= startDate |
endDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by created_at <= endDate |
numPerPage | integer Number of sources to return per paginated request. Defaults to 100. Max 500. |
pageNumber | integer Page number for paginated query results. Defaults to 1 |
{- "status": "success",
- "message": "string",
- "data": {
- "sources": [
- {
- "id": 0,
- "classification": "string",
- "taxonomy_id": 0,
- "probability": 0,
- "author_id": 0,
- "author_name": "string",
- "obj_id": "string"
}
], - "totalMatches": 0
}
}
Post a classification
obj_id required | string |
classification required | string |
taxonomy_id required | integer |
probability | float [ 0 .. 1 ] Nullable User-assigned probability of this classification on this taxonomy. If multiple classifications are given for the same source by the same user, the sum of the classifications ought to equal unity. Only individual probabilities are checked. |
group_ids | Array of integers List of group IDs corresponding to which groups should be able to view classification. Defaults to all of requesting user's groups. |
{- "obj_id": "string",
- "classification": "string",
- "taxonomy_id": 0,
- "probability": null,
- "group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string",
- "data": {
- "classification_id": 0
}
}
Retrieve an object's classifications
obj_id required | string |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "classification": "string",
- "taxonomy_id": 0,
- "probability": 0,
- "author_id": 0,
- "author_name": "string",
- "obj_id": "string"
}
]
}
{- "status": "success",
- "message": "string",
- "data": {
- "ALLOWED_SPECTRUM_TYPES": [ ],
- "ALLOWED_MAGSYSTEMS": [ ],
- "ALLOWED_BANDPASSES": [ ],
- "THUMBNAIL_TYPES": [ ],
- "FOLLOWUP_PRIORITIES": [ ],
- "ALLOWED_API_CLASSNAMES": [ ],
- "ANALYSIS_TYPES": [ ],
- "ANALYSIS_INPUT_TYPES": [ ],
- "AUTHENTICATION_TYPES": [ ]
}
}
{- "status": "success",
- "message": "string",
- "data": {
- "Number of candidates": 0,
- "Number of objs": 0,
- "Number of sources": 0,
- "Number of photometry": 0,
- "Number of spectra": 0,
- "Number of groups": 0,
- "Number of users": 0,
- "Number of tokens": 0,
- "Oldest candidate creation datetime": "string",
- "Newest candidate creation datetime": "string"
}
}
Retrieve a single default observation plan
default_observation_plan_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "requester_id": 0,
- "payload": null,
- "allocation_id": 0
}
}
Delete a default observation plan
default_observation_plan_id required | integer |
{- "status": "success",
- "message": "string"
}
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "requester_id": 0,
- "payload": null,
- "allocation_id": 0
}
]
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "name": "string",
- "stream_id": 0,
- "group_id": 0
}
}
Update filter name
filter_id required | integer |
name required | string Filter name. |
stream_id required | integer ID of the Filter's Stream. |
group_id required | integer ID of the Filter's Group. |
{- "name": "string",
- "stream_id": 0,
- "group_id": 0
}
{- "status": "success",
- "message": "string"
}
POST a new filter.
name required | string Filter name. |
stream_id required | integer ID of the Filter's Stream. |
group_id required | integer ID of the Filter's Group. |
{- "name": "string",
- "stream_id": 0,
- "group_id": 0
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Retrieve a filter as stored on Kowalski
filter_id required | integer |
{- "status": "success",
- "message": "string",
- "data": { }
}
POST a new filter version.
name required | string Filter name. |
stream_id required | integer ID of the Filter's Stream. |
group_id required | integer ID of the Filter's Group. |
{- "name": "string",
- "stream_id": 0,
- "group_id": 0
}
{- "status": "success",
- "message": "string",
- "data": {
- "pipeline": [
- { }
]
}
}
Delete a filter on Kowalski
filter_id required | integer |
{- "status": "success",
- "message": "string"
}
Update a filter on Kowalski
filter_id required | integer |
filter_id required | integer >= 1 [fritz] science program filter id for this user group id |
active | boolean activate or deactivate filter |
active_fid | string 6 characters set fid as active version |
autosave | boolean automatically save passing candidates to filter's group |
update_annotations | boolean update annotations for existing candidates |
{- "filter_id": 1,
- "active": true,
- "active_fid": "string",
- "autosave": true,
- "update_annotations": true
}
{- "status": "success",
- "message": "string"
}
Create default observation plan requests.
target_group_ids | Array of integers IDs of groups to share the results of the default observation plan request with. |
payload | any Content of the default observation plan request. |
allocation_id required | integer Observation plan request allocation ID. |
{- "target_group_ids": [
- 0
], - "payload": null,
- "allocation_id": 0
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Post a message from a remote facility
new_status required | string |
followup_request_id required | integer |
{- "new_status": "string",
- "followup_request_id": 0
}
{- "status": "success",
- "message": "string"
}
Retrieve followup requests schedule
sourceID | string Portion of ID to filter on |
startDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by created_at >= startDate |
endDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by created_at <= endDate |
status | string String to match status of request against |
observationStartDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, start time of observation window, otherwise now. |
observationEndDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, end time of observation window, otherwise 12 hours from now. |
output_format | string Output format for schedule. Can be png, pdf, or csv |
A PDF/PNG schedule file
{- "status": "error",
- "message": "string",
- "data": { }
}
Reprioritize followup requests schedule automatically based on either magnitude or location within skymap.
{- "status": "success",
- "message": "string"
}
Update a follow-up request
request_id required | string |
obj_id required | string ID of the target Obj. |
target_group_ids | Array of integers IDs of groups to share the results of the followup request with. |
payload | any Content of the followup request. |
allocation_id required | integer Followup request allocation ID. |
status | string Default: "pending submission" The status of the request. |
{- "obj_id": "string",
- "target_group_ids": [
- 0
], - "payload": null,
- "allocation_id": 0,
- "status": "pending submission"
}
{- "status": "success",
- "message": "string"
}
Delete follow-up request.
request_id required | string |
{- "status": "success",
- "message": "string"
}
Submit follow-up request.
obj_id required | string ID of the target Obj. |
target_group_ids | Array of integers IDs of groups to share the results of the followup request with. |
payload | any Content of the followup request. |
allocation_id required | integer Followup request allocation ID. |
status | string Default: "pending submission" The status of the request. |
{- "obj_id": "string",
- "target_group_ids": [
- 0
], - "payload": null,
- "allocation_id": 0,
- "status": "pending submission"
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Get photometry request.
request_id required | string |
{- "status": "success",
- "message": "string"
}
Upload galaxies from GLADE+ catalog. If no file_name or file_url is provided, will look for the GLADE+ catalog in the data directory. If it can't be found, it will download it.
file_name | string Name of the file containing the galaxies (in the data directory) |
file_url | string URL of the file containing the galaxies |
{- "file_name": "string",
- "file_url": "string"
}
{- "status": "success",
- "message": "string"
}
Upload galaxies from ASCII file
catalogData | any Catalog data Ascii string |
catalogName | string Galaxy catalog name. |
{- "catalogData": null,
- "catalogName": "string"
}
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "ra": 0,
- "dec": 0,
- "catalog_name": "string",
- "name": "string",
- "alt_name": "string",
- "distmpc": 0,
- "distmpc_unc": 0,
- "redshift": 0,
- "redshift_error": 0,
- "sfr_fuv": 0,
- "mstar": 0,
- "magb": 0,
- "magk": 0,
- "a": 0,
- "b2a": 0,
- "pa": 0,
- "btc": 0
}
]
}
Retrieve all galaxies
catalog_name | string Filter by catalog name (exact match) |
minDistance | number If provided, return only galaxies with a distance of at least this value |
maxDistance | number If provided, return only galaxies with a distance of at most this value |
minRedshift | number If provided, return only galaxies with a redshift of at least this value |
maxRedshift | number If provided, return only galaxies with a redshift of at most this value |
localizationDateobs | string Event time in ISO 8601 format ( |
localizationName | string Name of localization / skymap to use. Can be found in Localization.localization_name queried from /api/localization endopoint or skymap name in GcnEvent page table. |
localizationCumprob | number Cumulative probability up to which to include galaxies |
includeGeoJSON | boolean Boolean indicating whether to include associated GeoJSON. Defaults to false. |
numPerPage | integer Number of galaxies to return per paginated request. Defaults to 100. Can be no larger than {MAX_OBSERVATIONS}. |
pageNumber | integer Page number for paginated query results. Defaults to 1 |
catalogNamesOnly | boolean Boolean indicating whether to just return catalog names. Defaults to false. |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "ra": 0,
- "dec": 0,
- "catalog_name": "string",
- "name": "string",
- "alt_name": "string",
- "distmpc": 0,
- "distmpc_unc": 0,
- "redshift": 0,
- "redshift_error": 0,
- "sfr_fuv": 0,
- "mstar": 0,
- "magb": 0,
- "magk": 0,
- "a": 0,
- "b2a": 0,
- "pa": 0,
- "btc": 0
}
]
}
Ingest a Galaxy catalog
catalog_name | string Galaxy catalog name. |
catalog_data | Array of any Galaxy catalog data |
{- "catalog_name": "string",
- "catalog_data": [
- null
]
}
{- "status": "success",
- "message": "string"
}
Delete a galaxy catalog
catalog_name required | str |
{- "status": "success",
- "message": "string"
}
Retrieve an instrument
instrument_id required | integer |
includeGeoJSON | boolean Boolean indicating whether to include associated GeoJSON. Defaults to false. |
includeGeoJSONSummary | boolean Boolean indicating whether to include associated GeoJSON summary bounding box. Defaults to false. |
includeRegion | boolean Boolean indicating whether to include associated DS9 region. Defaults to false. |
localizationDateobs | string Include fields within a given localization.
Event time in ISO 8601 format ( |
localizationName | string Name of localization / skymap to use. Can be found in Localization.localization_name queried from /api/localization endpoint or skymap name in GcnEvent page table. |
localizationCumprob | number Cumulative probability up to which to include fields. Defaults to 0.95. |
{- "status": "success",
- "message": "string",
- "data": {
- "region": "string",
- "id": 0,
- "name": "string",
- "type": "imager",
- "band": "string",
- "telescope_id": 0,
- "filters": [
- null
], - "sensitivity_data": null,
- "api_classname": "ATLASAPI",
- "api_classname_obsplan": "ATLASAPI",
- "listener_classname": "SEDMListener",
- "treasuremap_id": 0,
- "tns_id": 0
}
}
Update instrument
instrument_id required | integer |
region | string Nullable Instrument astropy.regions representation. |
name required | string Instrument name. |
type required | string <= 20 characters Enum: "imager" "spectrograph" "imaging spectrograph" Instrument type, one of Imager, Spectrograph, or Imaging Spectrograph. |
band | string Nullable The spectral band covered by the instrument (e.g., Optical, IR). |
telescope_id required | integer The ID of the Telescope that hosts the Instrument. |
filters | Array of any List of filters on the instrument (if any). |
sensitivity_data | any Nullable JSON describing the filters on the instrument and the filter's corresponding limiting magnitude and exposure time. |
api_classname | string <= 11 characters Nullable Enum: "ATLASAPI" "KAITAPI" "SEDMAPI" "SEDMV2API" "IOOAPI" "IOIAPI" "SPRATAPI" "SINISTROAPI" "SPECTRALAPI" "FLOYDSAPI" "MUSCATAPI" "MMAAPI" "PS1API" "SLACKAPI" "UVOTXRTAPI" "ZTFAPI" "ZTFMMAAPI" Name of the instrument's API class. |
api_classname_obsplan | string <= 11 characters Nullable Enum: "ATLASAPI" "KAITAPI" "SEDMAPI" "SEDMV2API" "IOOAPI" "IOIAPI" "SPRATAPI" "SINISTROAPI" "SPECTRALAPI" "FLOYDSAPI" "MUSCATAPI" "MMAAPI" "PS1API" "SLACKAPI" "UVOTXRTAPI" "ZTFAPI" "ZTFMMAAPI" Name of the instrument's ObservationPlan API class. |
listener_classname | string <= 12 characters Nullable Value: "SEDMListener" Name of the instrument's listener class. |
treasuremap_id | integer Nullable treasuremap.space API ID for this instrument |
tns_id | integer Nullable TNS API ID for this instrument |
{- "region": "string",
- "name": "string",
- "type": "imager",
- "band": "string",
- "telescope_id": 0,
- "filters": [
- null
], - "sensitivity_data": null,
- "api_classname": "ATLASAPI",
- "api_classname_obsplan": "ATLASAPI",
- "listener_classname": "SEDMListener",
- "treasuremap_id": 0,
- "tns_id": 0
}
{- "status": "success",
- "message": "string"
}
Delete an instrument
instrument_id required | integer |
{- "status": "success",
- "message": "string"
}
Retrieve all instruments
name | string Filter by name (exact match) |
includeGeoJSON | boolean Boolean indicating whether to include associated GeoJSON. Defaults to false. |
includeGeoJSONSummary | boolean Boolean indicating whether to include associated GeoJSON summary bounding box. Defaults to false. |
includeRegion | boolean Boolean indicating whether to include associated DS9 region. Defaults to false. |
localizationDateobs | string Include fields within a given localization.
Event time in ISO 8601 format ( |
localizationName | string Name of localization / skymap to use. Can be found in Localization.localization_name queried from /api/localization endpoint or skymap name in GcnEvent page table. |
localizationCumprob | number Cumulative probability up to which to include fields. Defaults to 0.95. |
airmassTime | string Time to use for airmass calculation in
ISO 8601 format ( |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "region": "string",
- "id": 0,
- "name": "string",
- "type": "imager",
- "band": "string",
- "telescope_id": 0,
- "filters": [
- null
], - "sensitivity_data": null,
- "api_classname": "ATLASAPI",
- "api_classname_obsplan": "ATLASAPI",
- "listener_classname": "SEDMListener",
- "treasuremap_id": 0,
- "tns_id": 0
}
]
}
Add a new instrument
region | string Nullable Instrument astropy.regions representation. |
name required | string Instrument name. |
type required | string <= 20 characters Enum: "imager" "spectrograph" "imaging spectrograph" Instrument type, one of Imager, Spectrograph, or Imaging Spectrograph. |
band | string Nullable The spectral band covered by the instrument (e.g., Optical, IR). |
telescope_id required | integer The ID of the Telescope that hosts the Instrument. |
filters | Array of strings Default: [] Items Enum: "bessellux" "bessellb" "bessellv" "bessellr" "besselli" "standard::u" "standard::b" "standard::v" "standard::r" "standard::i" "desg" "desr" "desi" "desz" "desy" "sdssu" "sdssg" "sdssr" "sdssi" "sdssz" "f435w" "f475w" "f555w" "f606w" "f625w" "f775w" "f850lp" "nicf110w" "nicf160w" "f098m" "f105w" "f110w" "f125w" "f127m" "f139m" "f140w" "f153m" "f160w" "f218w" "f225w" "f275w" "f300x" "f336w" "f350lp" "f390w" "f689m" "f763m" "f845m" "f438w" "uvf475w" "uvf555w" "uvf606w" "uvf625w" "uvf775w" "uvf814w" "uvf850lp" "kepler" "cspb" "csphs" "csphd" "cspjs" "cspjd" "cspv3009" "cspv3014" "cspv9844" "cspys" "cspyd" "cspg" "cspi" "cspk" "cspr" "cspu" "f070w" "f090w" "f115w" "f150w" "f200w" "f277w" "f356w" "f444w" "f140m" "f162m" "f182m" "f210m" "f250m" "f300m" "f335m" "f360m" "f410m" "f430m" "f460m" "f480m" "f560w" "f770w" "f1000w" "f1130w" "f1280w" "f1500w" "f1800w" "f2100w" "f2550w" "f1065c" "f1140c" "f1550c" "f2300c" "lsstu" "lsstg" "lsstr" "lssti" "lsstz" "lssty" "keplercam::us" "keplercam::b" "keplercam::v" "keplercam::r" "keplercam::i" "4shooter2::us" "4shooter2::b" "4shooter2::v" "4shooter2::r" "4shooter2::i" "f062" "f087" "f106" "f129" "f158" "f184" "f213" "f146" "ztfg" "ztfr" "ztfi" "uvot::b" "uvot::u" "uvot::uvm2" "uvot::uvw1" "uvot::uvw2" "uvot::v" "uvot::white" "ps1::open" "ps1::g" "ps1::r" "ps1::i" "ps1::z" "ps1::y" "ps1::w" "atlasc" "atlaso" "2massj" "2massh" "2massks" List of filters on the instrument (if any). |
sensitivity_data | object Nullable JSON describing the filters on the instrument and the filter's corresponding limiting magnitude and exposure time. |
api_classname | string <= 11 characters Nullable Enum: "ATLASAPI" "KAITAPI" "SEDMAPI" "SEDMV2API" "IOOAPI" "IOIAPI" "SPRATAPI" "SINISTROAPI" "SPECTRALAPI" "FLOYDSAPI" "MUSCATAPI" "MMAAPI" "PS1API" "SLACKAPI" "UVOTXRTAPI" "ZTFAPI" "ZTFMMAAPI" Name of the instrument's API class. |
api_classname_obsplan | string <= 11 characters Nullable Enum: "ATLASAPI" "KAITAPI" "SEDMAPI" "SEDMV2API" "IOOAPI" "IOIAPI" "SPRATAPI" "SINISTROAPI" "SPECTRALAPI" "FLOYDSAPI" "MUSCATAPI" "MMAAPI" "PS1API" "SLACKAPI" "UVOTXRTAPI" "ZTFAPI" "ZTFMMAAPI" Name of the instrument's ObservationPlan API class. |
listener_classname | string <= 12 characters Nullable Value: "SEDMListener" Name of the instrument's listener class. |
treasuremap_id | integer Nullable treasuremap.space API ID for this instrument |
tns_id | integer Nullable TNS API ID for this instrument |
field_data | dict List of ID, RA, and Dec for each field. |
field_region | str Serialized version of a regions.Region describing the shape of the instrument field. Note: should only include field_region or field_fov_type. |
field_fov_type | str Option for instrument field shape. Must be either circle or rectangle. Note: should only include field_region or field_fov_type. |
field_fov_attributes | list Option for instrument field shape parameters. Single float radius in degrees in case of circle or list of two floats (height and width) in case of a rectangle. |
{- "region": "string",
- "name": "string",
- "type": "imager",
- "band": "string",
- "telescope_id": 0,
- "filters": [
- null
], - "sensitivity_data": {
- "filter_name": "bessellux"
}, - "api_classname": "ATLASAPI",
- "api_classname_obsplan": "ATLASAPI",
- "listener_classname": "SEDMListener",
- "treasuremap_id": 0,
- "tns_id": 0,
- "field_data": null,
- "field_region": null,
- "field_fov_type": null,
- "field_fov_attributes": null
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Retrieve all comments associated with specified resource
associated_resource_type required | string Value: "sources" What underlying data the comment is on, e.g., "sources" or "spectra" or "gcn_event". |
resource_id required | string The ID of the underlying data. This would be a string for a source ID or an integer for other data types like spectrum or gcn_event. |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "attachment_bytes": "string",
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0
}
]
}
Update a comment
associated_resource_type required | string Enum: "sources" "spectrum" "gcn_event" "shift" What underlying data the comment is on: "sources" or "spectra" or "gcn_event" or "shift". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" "shift" The ID of the source or spectrum that the comment is posted to. This would be a string for an object ID or an integer for a spectrum, gcn_event or shift. |
comment_id required | integer |
attachment_bytes | string Nullable Binary representation of the attachment. |
text required | string Comment body. |
attachment_name | string Nullable Filename of the attachment. |
origin | string Nullable Comment origin. |
bot | boolean Boolean indicating whether comment was posted via a bot (token-based request). |
obj_id required | string ID of the Comment's Obj. |
author_id required | integer ID of the Comment author's User instance. |
group_ids | Array of integers List of group IDs corresponding to which groups should be able to view comment. |
{- "attachment_bytes": "string",
- "text": "string",
- "attachment_name": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0,
- "group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string"
}
Post a comment
associated_resource_type required | string Enum: "sources" "spectrum" "gcn_event" What underlying data the comment is on: "source" or "spectrum" or "gcn_event". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" The ID of the source or spectrum that the comment is posted to. This would be a string for a source ID or an integer for a spectrum. |
text required | string |
group_ids | Array of integers List of group IDs corresponding to which groups should be able to view comment. Defaults to all of requesting user's groups. |
attachment | object |
{- "text": "string",
- "group_ids": [
- 0
], - "attachment": {
- "body": "string",
- "name": "string"
}
}
{- "status": "success",
- "message": "string",
- "data": {
- "comment_id": 0
}
}
Delete a comment
associated_resource_type required | string What underlying data the comment is on: "sources" or "spectra". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" The ID of the source or spectrum that the comment is posted to. This would be a string for a source ID or an integer for a spectrum or gcn_event. |
comment_id required | integer |
{- "status": "success",
- "message": "string"
}
Retrieve a comment
associated_resource_type required | string What underlying data the comment is on: "sources" or "spectra" or "gcn_event". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" The ID of the source, spectrum, or gcn_event that the comment is posted to. This would be a string for a source ID or an integer for a spectrum or gcn_event |
comment_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "attachment_bytes": "string",
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0
}
}
Update a comment
associated_resource_type required | string Enum: "sources" "spectrum" "gcn_event" "shift" What underlying data the comment is on: "sources" or "spectra" or "gcn_event" or "shift". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" "shift" The ID of the source or spectrum that the comment is posted to. This would be a string for an object ID or an integer for a spectrum, gcn_event or shift. |
comment_id required | integer |
attachment_bytes | string Nullable Binary representation of the attachment. |
text required | string Comment body. |
attachment_name | string Nullable Filename of the attachment. |
origin | string Nullable Comment origin. |
bot | boolean Boolean indicating whether comment was posted via a bot (token-based request). |
obj_id required | string ID of the Comment's Obj. |
author_id required | integer ID of the Comment author's User instance. |
group_ids | Array of integers List of group IDs corresponding to which groups should be able to view comment. |
{- "attachment_bytes": "string",
- "text": "string",
- "attachment_name": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0,
- "group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string"
}
Delete a comment
associated_resource_type required | string What underlying data the comment is on: "sources" or "spectra". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" The ID of the source or spectrum that the comment is posted to. This would be a string for a source ID or an integer for a spectrum or gcn_event. |
comment_id required | integer |
{- "status": "success",
- "message": "string"
}
Download comment attachment
associated_resource_type required | string Enum: "sources" "spectrum" "gcn_event" What underlying data the comment is on: "sources" or "spectra". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" The ID of the source or spectrum that the comment is posted to. This would be a string for a source ID or an integer for a spectrum. |
comment_id required | integer |
download | boolean If true, download the attachment; else return file data as text. True by default. |
Download comment attachment
associated_resource_type required | string Enum: "sources" "spectrum" "gcn_event" What underlying data the comment is on: "sources" or "spectra". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" The ID of the source or spectrum that the comment is posted to. This would be a string for a source ID or an integer for a spectrum. |
comment_id required | integer |
download | boolean If true, download the attachment; else return file data as text. True by default. |
Retrieve all comments associated with specified resource
associated_resource_type required | string Value: "sources" What underlying data the comment is on, e.g., "sources" or "spectra" or "gcn_event". |
resource_id required | string The ID of the underlying data. This would be a string for a source ID or an integer for other data types like spectrum or gcn_event. |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "attachment_bytes": "string",
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0
}
]
}
Retrieve all annotations associated with specified resource
associated_resource_type required | string Enum: "sources" "spectra" What underlying data the annotation is on: must be one of either "sources" or "spectra". |
resource_id required | string The ID of the underlying data. This would be a string for a source ID or an integer for other data types like spectra. |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "data": null,
- "origin": "string",
- "author_id": 0,
- "obj_id": "string"
}
]
}
Retrieve a comment
associated_resource_type required | string What underlying data the comment is on: "sources" or "spectra" or "gcn_event". |
resource_id required | string Enum: "sources" "spectra" "gcn_event" The ID of the source, spectrum, or gcn_event that the comment is posted to. This would be a string for a source ID or an integer for a spectrum or gcn_event |
comment_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "attachment_bytes": "string",
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0
}
}
Retrieve a reminder
associated_resource_type required | string Enum: "source" "spectra" "gcn_event" "shift" What underlying data the reminder is on: "sources" or "spectra" or "gcn_event" or "shift". |
resource_id required | string The ID of the source, spectrum, gcn_event or shift that the reminder is posted to. This would be a string for a source ID or an integer for a spectrum or gcn_event |
reminder_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "text": "string",
- "origin": "string",
- "bot": true,
- "next_reminder": "2022-08-17T20:51:00Z",
- "reminder_delay": 0,
- "number_of_reminders": 0,
- "obj_id": "string",
- "user_id": 0
}
}
Retrieve all reminders associated with specified resource
associated_resource_type required | string Enum: "source" "spectra" "gcn_event" "shift" What underlying data the reminder is on: "sources" or "spectra" or "gcn_event" or "shift". |
resource_id required | string The ID of the underlying data. This would be a string for a source ID or an integer for other data types like spectrum or gcn_event. |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "text": "string",
- "origin": "string",
- "bot": true,
- "next_reminder": "2022-08-17T20:51:00Z",
- "reminder_delay": 0,
- "number_of_reminders": 0,
- "obj_id": "string",
- "user_id": 0
}
]
}
Retrieve all spectra associated with an Object
obj_id required | string ID of the object to retrieve spectra for |
normalization | string what normalization is needed for the spectra (e.g., "median"). If omitted, returns the original spectrum. Options for normalization are:
|
{- "status": "success",
- "message": "string",
- "data": {
- "obj_id": "string",
- "spectra": [
- {
- "id": 0,
- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-08-17T20:51:00Z",
- "origin": "string",
- "type": "source",
- "label": "string",
- "instrument_id": 0,
- "followup_request_id": 0,
- "assignment_id": 0,
- "altdata": null,
- "original_file_string": "string",
- "original_file_filename": "string",
- "owner_id": 0
}
]
}
}
Retrieve all annotations associated with specified resource
associated_resource_type required | string Enum: "sources" "spectra" What underlying data the annotation is on: must be one of either "sources" or "spectra". |
resource_id required | string The ID of the underlying data. This would be a string for a source ID or an integer for other data types like spectra. |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "data": null,
- "origin": "string",
- "author_id": 0,
- "obj_id": "string"
}
]
}
Retrieve an annotation
associated_resource_type required | string Enum: "sources" "spectra" What underlying data the annotation is on: must be one of either "sources" or "spectra". |
resource_id required | string The ID of the underlying data. This would be a string for a source ID or an integer for other data types like spectra. |
annotation_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "data": null,
- "origin": "string",
- "author_id": 0,
- "obj_id": "string"
}
}
Retrieve a spectrum
spectrum_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-08-17T20:51:00Z",
- "origin": "string",
- "type": "source",
- "label": "string",
- "instrument_id": 0,
- "followup_request_id": 0,
- "assignment_id": 0,
- "altdata": null,
- "original_file_string": "string",
- "original_file_filename": "string",
- "owner_id": 0
}
}
Update spectrum
spectrum_id required | integer |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
altdata | any Miscellaneous alternative metadata. |
wavelengths required | Array of numbers Wavelengths of the spectrum [Angstrom]. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
label | string User defined label (can be used to replace default instrument/date labeling on plot legends). |
followup_request_id | integer ID of the Followup request that generated this spectrum, if any. |
units | string Units of the fluxes/errors. Options are Jy, AB, or erg/s/cm/cm/AA). |
group_ids | any Default: [] IDs of the Groups to share this spectrum with. Set to "all" to make this spectrum visible to all users. |
errors | Array of numbers Errors on the fluxes of the spectrum [F_lambda, same units as |
external_observer | string Nullable Default: null Free text provided as an external observer |
observed_at required | string <date-time> The ISO UTC time the spectrum was taken. |
observed_by | Array of integers Default: [] IDs of the Users who observed this Spectrum, or to use as points of contact given an external observer. |
fluxes required | Array of numbers Flux of the Spectrum [F_lambda, arbitrary units]. |
instrument_id required | integer ID of the Instrument that acquired the Spectrum. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source''host''host_center'. Defaults to 'fsource'. |
obj_id required | string ID of this Spectrum's Obj. |
origin | string Origin of the spectrum. |
reduced_by | Array of integers Default: [] IDs of the Users who reduced this Spectrum, or to use as points of contact given an external reducer. |
{- "assignment_id": 0,
- "altdata": null,
- "wavelengths": [
- 0
], - "external_reducer": null,
- "label": "string",
- "followup_request_id": 0,
- "units": "string",
- "group_ids": [ ],
- "errors": [
- 0
], - "external_observer": null,
- "observed_at": "2022-08-17T20:51:00Z",
- "observed_by": [ ],
- "fluxes": [
- 0
], - "instrument_id": 0,
- "type": "source",
- "obj_id": "string",
- "origin": "string",
- "reduced_by": [ ]
}
{- "status": "success",
- "message": "string"
}
Retrieve multiple spectra with given criteria
minimalPayload | boolean If true, return only the minimal metadata about each spectrum, instead of returning the potentially large payload that includes wavelength/flux and also comments and annotations. The metadata that is always included is: id, obj_id, owner_id, origin, type, label, observed_at, created_at, modified, instrument_id, instrument_name, original_file_name, followup_request_id, assignment_id, and altdata. |
observedBefore | string Arrow-parseable date string (e.g. 2020-01-01). If provided, return only spectra observed before this time. |
observedAfter | string Arrow-parseable date string (e.g. 2020-01-01). If provided, return only spectra observed after this time. |
objID | string Return any spectra on an object with ID that has a (partial) match to this argument (i.e., the given argument is "in" the object's ID). |
instrumentIDs | any If provided, filter only spectra observed with one of these instrument IDs. |
groupIDs | list If provided, filter only spectra saved to one of these group IDs. |
followupRequestIDs | list If provided, filter only spectra associate with these followup request IDs. |
assignmentIDs | list If provided, filter only spectra associate with these assignment request IDs. |
origin | string Return any spectra that have an origin with a (partial) match to any of the values in this comma separated list. |
label | string Return any spectra that have an origin with a (partial) match to any of the values in this comma separated list. |
type | string Return spectra of the given type or types (match multiple values using a comma separated list). Types of spectra are defined in the config, e.g., source, host or host_center. |
commentsFilter | Array of strings Comma-separated string of comment text to filter for spectra matching. |
commentsFilterAuthor | string Comma separated string of authors. Only comments from these authors are used when filtering with the commentsFilter. |
commentsFilterBefore | string Arrow-parseable date string (e.g. 2020-01-01). If provided, only return sources that have comments before this time. |
commentsFilterAfter | string Arrow-parseable date string (e.g. 2020-01-01). If provided, only return sources that have comments after this time. |
Upload spectrum
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
altdata | any Miscellaneous alternative metadata. |
wavelengths required | Array of numbers Wavelengths of the spectrum [Angstrom]. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
label | string User defined label (can be used to replace default instrument/date labeling on plot legends). |
followup_request_id | integer ID of the Followup request that generated this spectrum, if any. |
units | string Units of the fluxes/errors. Options are Jy, AB, or erg/s/cm/cm/AA). |
group_ids | any Default: [] IDs of the Groups to share this spectrum with. Set to "all" to make this spectrum visible to all users. |
errors | Array of numbers Errors on the fluxes of the spectrum [F_lambda, same units as |
external_observer | string Nullable Default: null Free text provided as an external observer |
observed_at required | string <date-time> The ISO UTC time the spectrum was taken. |
observed_by | Array of integers Default: [] IDs of the Users who observed this Spectrum, or to use as points of contact given an external observer. |
fluxes required | Array of numbers Flux of the Spectrum [F_lambda, arbitrary units]. |
instrument_id required | integer ID of the Instrument that acquired the Spectrum. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source''host''host_center'. Defaults to 'fsource'. |
obj_id required | string ID of this Spectrum's Obj. |
origin | string Origin of the spectrum. |
reduced_by | Array of integers Default: [] IDs of the Users who reduced this Spectrum, or to use as points of contact given an external reducer. |
{- "assignment_id": 0,
- "altdata": null,
- "wavelengths": [
- 0
], - "external_reducer": null,
- "label": "string",
- "followup_request_id": 0,
- "units": "string",
- "group_ids": [ ],
- "errors": [
- 0
], - "external_observer": null,
- "observed_at": "2022-08-17T20:51:00Z",
- "observed_by": [ ],
- "fluxes": [
- 0
], - "instrument_id": 0,
- "type": "source",
- "obj_id": "string",
- "origin": "string",
- "reduced_by": [ ]
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Parse spectrum from ASCII file
wave_column | integer Default: 0 The 0-based index of the ASCII column corresponding to the wavelength values of the spectrum (default 0). |
ascii required | string The content of the ASCII file to be parsed. The file can optionally contain a header which will be parsed and stored. The lines that make up the ASCII header must appear at the beginning of the file and all be formatted the same way within a single file. They can be formatted in one of two ways.
Example of format 1:
Example of format 2:
The data must be at least 2 column ascii (wavelength, flux). If flux errors are provided in an additional column, the column must be specified in the call. If more than 2 columns are given, by default the first two are interpreted as (wavelength, flux). The column indices of each of these arguments can be controlled by passing the integer column index to the POST JSON. Examples of valid data sections: Many-column ASCII:
3-column ASCII:
2-column ASCII:
2-column ASCII:
|
flux_column | integer Default: 1 The 0-based index of the ASCII column corresponding to the flux values of the spectrum (default 1). |
fluxerr_column | integer Nullable Default: null The 0-based index of the ASCII column corresponding to the flux error values of the spectrum (default None). If a column for errors is provided, set to the corresponding 0-based column number, otherwise, it will be ignored. |
{- "wave_column": 0,
- "ascii": "string",
- "flux_column": 1,
- "fluxerr_column": null
}
{- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-08-17T20:51:00Z",
- "origin": "string",
- "type": "source",
- "label": "string",
- "instrument_id": 0,
- "followup_request_id": 0,
- "assignment_id": 0,
- "altdata": null,
- "original_file_string": "string",
- "original_file_filename": "string"
}
Upload spectrum from ASCII file
wave_column | integer Default: 0 The 0-based index of the ASCII column corresponding to the wavelength values of the spectrum (default 0). |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
label | string User defined label to be placed in plot legends, instead of the default |
followup_request_id | integer ID of the Followup request that generated this spectrum, if any. |
group_ids | Array of integers The IDs of the groups to share this spectrum with. |
ascii required | string The content of the ASCII file to be parsed. The file can optionally contain a header which will be parsed and stored. The lines that make up the ASCII header must appear at the beginning of the file and all be formatted the same way within a single file. They can be formatted in one of two ways.
Example of format 1:
Example of format 2:
The data must be at least 2 column ascii (wavelength, flux). If flux errors are provided in an additional column, the column must be specified in the call. If more than 2 columns are given, by default the first two are interpreted as (wavelength, flux). The column indices of each of these arguments can be controlled by passing the integer column index to the POST JSON. Examples of valid data sections: Many-column ASCII:
3-column ASCII:
2-column ASCII:
2-column ASCII:
|
filename required | string The original filename (for bookkeeping purposes). |
observed_at required | string <date-time> The ISO UTC time the spectrum was taken. |
observed_by | Array of integers Default: [] IDs of the Users who observed this Spectrum, or to use as points of contact given an external observer. |
external_observer | string Nullable Default: null Free text provided as an external observer |
flux_column | integer Default: 1 The 0-based index of the ASCII column corresponding to the flux values of the spectrum (default 1). |
instrument_id required | integer The ID of the instrument that took the spectrum. |
fluxerr_column | integer Nullable Default: null The 0-based index of the ASCII column corresponding to the flux error values of the spectrum (default None). If a column for errors is provided, set to the corresponding 0-based column number, otherwise, it will be ignored. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source', 'host', 'host_center'. Defaults to 'fsource'. |
obj_id required | string The ID of the object that the spectrum is of. |
reduced_by | Array of integers Default: [] IDs of the Users who reduced this Spectrum, or to use as points of contact given an external reducer. |
{- "wave_column": 0,
- "assignment_id": 0,
- "external_reducer": null,
- "label": "string",
- "followup_request_id": 0,
- "group_ids": [
- 0
], - "ascii": "string",
- "filename": "string",
- "observed_at": "2022-08-17T20:51:00Z",
- "observed_by": [ ],
- "external_observer": null,
- "flux_column": 1,
- "instrument_id": 0,
- "fluxerr_column": null,
- "type": "source",
- "obj_id": "string",
- "reduced_by": [ ]
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Create synthetic photometry from a spectrum
spectrum_id required | integer |
filters required | list List of filters |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-08-17T20:51:01Z",
- "origin": "string",
- "type": "source",
- "label": "string",
- "instrument_id": 0,
- "followup_request_id": 0,
- "assignment_id": 0,
- "altdata": null,
- "original_file_string": "string",
- "original_file_filename": "string",
- "owner_id": 0
}
}
Retrieve spectra for given instrument within date range
instrument_ids | list of integers Instrument id numbers of spectrum. If None, retrieve for all instruments. |
min_date | ISO UTC date string Minimum UTC date of range in ISOT format. If None, open ended range. |
max_date | ISO UTC date string Maximum UTC date of range in ISOT format. If None, open ended range. |
{- "status": "success",
- "message": "string",
- "data": {
- "obj_id": "string",
- "spectra": [
- {
- "id": 0,
- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-08-17T20:51:01Z",
- "origin": "string",
- "type": "source",
- "label": "string",
- "instrument_id": 0,
- "followup_request_id": 0,
- "assignment_id": 0,
- "altdata": null,
- "original_file_string": "string",
- "original_file_filename": "string",
- "owner_id": 0
}
]
}
}
Retrieve a spectrum
spectrum_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-08-17T20:51:01Z",
- "origin": "string",
- "type": "source",
- "label": "string",
- "instrument_id": 0,
- "followup_request_id": 0,
- "assignment_id": 0,
- "altdata": null,
- "original_file_string": "string",
- "original_file_filename": "string",
- "owner_id": 0
}
}
Update spectrum
spectrum_id required | integer |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
altdata | any Miscellaneous alternative metadata. |
wavelengths required | Array of numbers Wavelengths of the spectrum [Angstrom]. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
label | string User defined label (can be used to replace default instrument/date labeling on plot legends). |
followup_request_id | integer ID of the Followup request that generated this spectrum, if any. |
units | string Units of the fluxes/errors. Options are Jy, AB, or erg/s/cm/cm/AA). |
group_ids | any Default: [] IDs of the Groups to share this spectrum with. Set to "all" to make this spectrum visible to all users. |
errors | Array of numbers Errors on the fluxes of the spectrum [F_lambda, same units as |
external_observer | string Nullable Default: null Free text provided as an external observer |
observed_at required | string <date-time> The ISO UTC time the spectrum was taken. |