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
Retrieve an allocation
allocation_id required | integer |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "pi": "string",
- "proposal_id": "string",
- "start_date": "2022-05-12T05:00:12Z",
- "end_date": "2022-05-12T05:00:12Z",
- "hours_allocated": 0,
- "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. |
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-05-12T05:00:13Z",
- "end_date": "2022-05-12T05:00:13Z",
- "hours_allocated": 0,
- "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-05-12T05:00:13Z",
- "end_date": "2022-05-12T05:00:13Z",
- "hours_allocated": 0,
- "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. |
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-05-12T05:00:13Z",
- "end_date": "2022-05-12T05:00:13Z",
- "hours_allocated": 0,
- "group_id": 0,
- "instrument_id": 0,
- "_altdata": "string"
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
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
status | string The status of the request |
priority required | any Enum: "1" "2" "3" "4" "5" Priority of the request, (lowest = 1, highest = 5). |
comment | string An optional comment describing the request. |
obj_id required | string The ID of the object to observe. |
run_id required | integer |
{- "status": "string",
- "priority": "1",
- "comment": "string",
- "obj_id": "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"
}
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": [ ]
}
}
{- "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"
}
}
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"
}
{- "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"
}
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 location within skymap.
{- "status": "success",
- "message": "string"
}
Update a follow-up request
request_id required | string |
status | string Default: "pending submission" The status of the request. |
payload | any Content of the followup request. |
obj_id required | string ID of the target Obj. |
allocation_id required | integer Followup request allocation ID. |
target_group_ids | Array of integers IDs of groups to share the results of the followup request with. |
{- "status": "pending submission",
- "payload": null,
- "obj_id": "string",
- "allocation_id": 0,
- "target_group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string"
}
Delete follow-up request.
request_id required | string |
{- "status": "success",
- "message": "string"
}
Submit follow-up request.
status | string Default: "pending submission" The status of the request. |
payload | any Content of the followup request. |
obj_id required | string ID of the target Obj. |
allocation_id required | integer Followup request allocation ID. |
target_group_ids | Array of integers IDs of groups to share the results of the followup request with. |
{- "status": "pending submission",
- "payload": null,
- "obj_id": "string",
- "allocation_id": 0,
- "target_group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Get photometry request.
request_id required | string |
{- "status": "success",
- "message": "string"
}
Retrieve all galaxies
catalog_name | string Filter by catalog name (exact match) |
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. |
{- "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_data | Array of any Galaxy catalog data |
catalog_name | string Galaxy catalog name. |
{- "catalog_data": [
- null
], - "catalog_name": "string"
}
{- "status": "success",
- "message": "string"
}
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": [
- {
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0
}
]
}
Update a comment
associated_resource_type required | string Enum: "sources" "spectrum" "gcn_event" 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 or spectrum that the comment is posted to. This would be a string for an object ID or an integer for a spectrum or gcn_event. |
comment_id required | integer |
text required | string Comment body. |
attachment_name | string Nullable Filename of the attachment. |
attachment_bytes | string Nullable Binary representation 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. |
{- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "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": {
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0
}
}
Update a comment
associated_resource_type required | string Enum: "sources" "spectrum" "gcn_event" 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 or spectrum that the comment is posted to. This would be a string for an object ID or an integer for a spectrum or gcn_event. |
comment_id required | integer |
text required | string Comment body. |
attachment_name | string Nullable Filename of the attachment. |
attachment_bytes | string Nullable Binary representation 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. |
{- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "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": [
- {
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "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": {
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_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-05-12T05:00:13Z",
- "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-05-12T05:00:13Z",
- "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 |
wavelengths required | Array of numbers Wavelengths of the spectrum [Angstrom]. |
fluxes required | Array of numbers Flux of the Spectrum [F_lambda, arbitrary units]. |
errors | Array of numbers Errors on the fluxes of the spectrum [F_lambda, same units as |
instrument_id required | integer ID of the Instrument that acquired the Spectrum. |
obj_id required | string ID of this Spectrum's Obj. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
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). |
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. |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
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. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source''host''host_center'. Defaults to 'fsource'. |
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. |
label | string User defined label (can be used to replace default instrument/date labeling on plot legends). |
altdata | any Miscellaneous alternative metadata. |
group_ids | any Default: [] IDs of the Groups to share this spectrum with. Set to "all" to make this spectrum visible to all users. |
origin | string Origin of the spectrum. |
{- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "instrument_id": 0,
- "obj_id": "string",
- "external_reducer": null,
- "followup_request_id": 0,
- "units": "string",
- "observed_by": [ ],
- "assignment_id": 0,
- "reduced_by": [ ],
- "type": "source",
- "external_observer": null,
- "observed_at": "2022-05-12T05:00:13Z",
- "label": "string",
- "altdata": null,
- "group_ids": [ ],
- "origin": "string"
}
{- "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
wavelengths required | Array of numbers Wavelengths of the spectrum [Angstrom]. |
fluxes required | Array of numbers Flux of the Spectrum [F_lambda, arbitrary units]. |
errors | Array of numbers Errors on the fluxes of the spectrum [F_lambda, same units as |
instrument_id required | integer ID of the Instrument that acquired the Spectrum. |
obj_id required | string ID of this Spectrum's Obj. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
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). |
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. |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
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. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source''host''host_center'. Defaults to 'fsource'. |
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. |
label | string User defined label (can be used to replace default instrument/date labeling on plot legends). |
altdata | any Miscellaneous alternative metadata. |
group_ids | any Default: [] IDs of the Groups to share this spectrum with. Set to "all" to make this spectrum visible to all users. |
origin | string Origin of the spectrum. |
{- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "instrument_id": 0,
- "obj_id": "string",
- "external_reducer": null,
- "followup_request_id": 0,
- "units": "string",
- "observed_by": [ ],
- "assignment_id": 0,
- "reduced_by": [ ],
- "type": "source",
- "external_observer": null,
- "observed_at": "2022-05-12T05:00:13Z",
- "label": "string",
- "altdata": null,
- "group_ids": [ ],
- "origin": "string"
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Parse spectrum from ASCII file
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:
|
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 | integer Default: 0 The 0-based index of the ASCII column corresponding to the wavelength values of the spectrum (default 0). |
flux_column | integer Default: 1 The 0-based index of the ASCII column corresponding to the flux values of the spectrum (default 1). |
{- "ascii": "string",
- "fluxerr_column": null,
- "wave_column": 0,
- "flux_column": 1
}
{- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-05-12T05:00:13Z",
- "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
instrument_id required | integer The ID of the instrument that took the spectrum. |
obj_id required | string The ID of the object that the spectrum is of. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
filename required | string The original filename (for bookkeeping purposes). |
followup_request_id | integer ID of the Followup request that generated this spectrum, if any. |
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. |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
wave_column | integer Default: 0 The 0-based index of the ASCII column corresponding to the wavelength values of the spectrum (default 0). |
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. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source', 'host', 'host_center'. Defaults to 'fsource'. |
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:
|
external_observer | string Nullable Default: null Free text provided as an external observer |
label | string User defined label to be placed in plot legends, instead of the default |
observed_at required | string <date-time> The ISO UTC time the spectrum was taken. |
flux_column | integer Default: 1 The 0-based index of the ASCII column corresponding to the flux values of the spectrum (default 1). |
group_ids | Array of integers The IDs of the groups to share this spectrum with. |
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. |
{- "instrument_id": 0,
- "obj_id": "string",
- "external_reducer": null,
- "filename": "string",
- "followup_request_id": 0,
- "observed_by": [ ],
- "assignment_id": 0,
- "wave_column": 0,
- "reduced_by": [ ],
- "type": "source",
- "ascii": "string",
- "external_observer": null,
- "label": "string",
- "observed_at": "2022-05-12T05:00:13Z",
- "flux_column": 1,
- "group_ids": [
- 0
], - "fluxerr_column": null
}
{- "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-05-12T05:00:13Z",
- "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-05-12T05:00:13Z",
- "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-05-12T05:00:13Z",
- "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 |
wavelengths required | Array of numbers Wavelengths of the spectrum [Angstrom]. |
fluxes required | Array of numbers Flux of the Spectrum [F_lambda, arbitrary units]. |
errors | Array of numbers Errors on the fluxes of the spectrum [F_lambda, same units as |
instrument_id required | integer ID of the Instrument that acquired the Spectrum. |
obj_id required | string ID of this Spectrum's Obj. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
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). |
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. |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
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. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source''host''host_center'. Defaults to 'fsource'. |
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. |
label | string User defined label (can be used to replace default instrument/date labeling on plot legends). |
altdata | any Miscellaneous alternative metadata. |
group_ids | any Default: [] IDs of the Groups to share this spectrum with. Set to "all" to make this spectrum visible to all users. |
origin | string Origin of the spectrum. |
{- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "instrument_id": 0,
- "obj_id": "string",
- "external_reducer": null,
- "followup_request_id": 0,
- "units": "string",
- "observed_by": [ ],
- "assignment_id": 0,
- "reduced_by": [ ],
- "type": "source",
- "external_observer": null,
- "observed_at": "2022-05-12T05:00:13Z",
- "label": "string",
- "altdata": null,
- "group_ids": [ ],
- "origin": "string"
}
{- "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
wavelengths required | Array of numbers Wavelengths of the spectrum [Angstrom]. |
fluxes required | Array of numbers Flux of the Spectrum [F_lambda, arbitrary units]. |
errors | Array of numbers Errors on the fluxes of the spectrum [F_lambda, same units as |
instrument_id required | integer ID of the Instrument that acquired the Spectrum. |
obj_id required | string ID of this Spectrum's Obj. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
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). |
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. |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
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. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source''host''host_center'. Defaults to 'fsource'. |
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. |
label | string User defined label (can be used to replace default instrument/date labeling on plot legends). |
altdata | any Miscellaneous alternative metadata. |
group_ids | any Default: [] IDs of the Groups to share this spectrum with. Set to "all" to make this spectrum visible to all users. |
origin | string Origin of the spectrum. |
{- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "instrument_id": 0,
- "obj_id": "string",
- "external_reducer": null,
- "followup_request_id": 0,
- "units": "string",
- "observed_by": [ ],
- "assignment_id": 0,
- "reduced_by": [ ],
- "type": "source",
- "external_observer": null,
- "observed_at": "2022-05-12T05:00:13Z",
- "label": "string",
- "altdata": null,
- "group_ids": [ ],
- "origin": "string"
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0
}
}
Parse spectrum from ASCII file
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:
|
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 | integer Default: 0 The 0-based index of the ASCII column corresponding to the wavelength values of the spectrum (default 0). |
flux_column | integer Default: 1 The 0-based index of the ASCII column corresponding to the flux values of the spectrum (default 1). |
{- "ascii": "string",
- "fluxerr_column": null,
- "wave_column": 0,
- "flux_column": 1
}
{- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-05-12T05:00:13Z",
- "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
instrument_id required | integer The ID of the instrument that took the spectrum. |
obj_id required | string The ID of the object that the spectrum is of. |
external_reducer | string Nullable Default: null Free text provided as an external reducer |
filename required | string The original filename (for bookkeeping purposes). |
followup_request_id | integer ID of the Followup request that generated this spectrum, if any. |
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. |
assignment_id | integer ID of the classical assignment that generated this spectrum, if any. |
wave_column | integer Default: 0 The 0-based index of the ASCII column corresponding to the wavelength values of the spectrum (default 0). |
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. |
type | string Enum: "source" "host" "host_center" Type of spectrum. One of: 'source', 'host', 'host_center'. Defaults to 'fsource'. |
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:
|
external_observer | string Nullable Default: null Free text provided as an external observer |
label | string User defined label to be placed in plot legends, instead of the default |
observed_at required | string <date-time> The ISO UTC time the spectrum was taken. |
flux_column | integer Default: 1 The 0-based index of the ASCII column corresponding to the flux values of the spectrum (default 1). |
group_ids | Array of integers The IDs of the groups to share this spectrum with. |
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. |
{- "instrument_id": 0,
- "obj_id": "string",
- "external_reducer": null,
- "filename": "string",
- "followup_request_id": 0,
- "observed_by": [ ],
- "assignment_id": 0,
- "wave_column": 0,
- "reduced_by": [ ],
- "type": "source",
- "ascii": "string",
- "external_observer": null,
- "label": "string",
- "observed_at": "2022-05-12T05:00:13Z",
- "flux_column": 1,
- "group_ids": [
- 0
], - "fluxerr_column": null
}
{- "status": "success",
- "message": "string",
- "data": {
- "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-05-12T05:00:13Z",
- "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
}
]
}
}
Submit a (classification) spectrum to TNS
spectrum_id required | integer |
tnsrobotID required | int SkyPortal TNS Robot ID |
classificationID | string Classification ID (see TNS documentation at https://www.wis-tns.org/content/tns-getting-started for options) |
classifiers | string List of those performing classification. |
spectrumType | string Type of spectrum that this is. Valid options are: ['object', 'host', 'sky', 'arcs', 'synthetic'] |
spectrumComment | string Comment on the spectrum. |
classificationComment | string Comment on the classification. |
{- "status": "success",
- "message": "string",
- "data": {
- "id": 0,
- "wavelengths": [
- 0
], - "fluxes": [
- 0
], - "errors": [
- 0
], - "units": "string",
- "obj_id": "string",
- "observed_at": "2022-05-12T05:00:13Z",
- "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 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": [
- {
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "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": {
- "id": 0,
- "text": "string",
- "attachment_name": "string",
- "attachment_bytes": "string",
- "origin": "string",
- "bot": true,
- "obj_id": "string",
- "author_id": 0
}
}
Retrieve offset stars to aid in spectroscopy
obj_id required | string |
facility | string Enum: "Keck" "Shane" "P200" Which facility to generate the starlist for |
num_offset_stars | integer [ 0 .. 10 ] Requested number of offset stars (set to zero to get starlist of just the source itself) |
obstime | string datetime of observation in isoformat (e.g. 2020-12-30T12:34:10) |
use_ztfref | boolean Use ZTFref catalog for offset star positions, otherwise Gaia DR2 |
{- "status": "success",
- "message": "string",
- "data": {
- "facility": "Keck",
- "starlist_str": "string",
- "starlist_info": [
- {
- "str": "string",
- "ra": 0,
- "dec": 0,
- "name": "string",
- "dras": "string",
- "ddecs": "string",
- "mag": 0
}
], - "ra": 0,
- "dec": 0,
- "queries_issued": 0,
- "noffsets": 0,
- "query": "string"
}
}
Generate a PDF/PNG finding chart to aid in spectroscopy
obj_id required | string |
imsize | float [ 2 .. 15 ] Image size in arcmin (square) |
facility | string Enum: "Keck" "Shane" "P200" |
image_source | string Enum: "desi" "dss" "ztfref" "ps1" Source of the image used in the finding chart. Defaults to ps1 |
use_ztfref | boolean Use ZTFref catalog for offset star positions, otherwise DR2 |
obstime | string datetime of observation in isoformat (e.g. 2020-12-30T12:34:10) |
type | string Enum: "png" "pdf" output type |
num_offset_stars | integer [ 0 .. 4 ] output desired number of offset stars [0,5] (default: 3) |
A PDF/PNG finding chart file
{- "status": "error",
- "message": "string",
- "data": { }
}
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"
}
]
}
Retrieve basic info on Groups that an Obj is saved to
obj_id required | integer |
{- "status": "success",
- "message": "string",
- "data": [
- {
- "id": 0,
- "name": "string",
- "nickname": "string",
- "description": "string",
- "private": true,
- "single_user_group": true
}
]
}
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 source
obj_id required | string |
includePhotometry | boolean Boolean indicating whether to include associated photometry. Defaults to false. |
includeComments | boolean Boolean indicating whether to include comment metadata in response. Defaults to false. |
includePhotometryExists | boolean Boolean indicating whether to return if a source has any photometry points. Defaults to false. |
includeSpectrumExists | boolean Boolean indicating whether to return if a source has a spectra. Defaults to false. |
includePeriodExists | boolean Boolean indicating whether to return if a source has a period set. Defaults to false. |
includeThumbnails | boolean Boolean indicating whether to include associated thumbnails. 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
}
}
Update a source
obj_id required | string |
ra | number Nullable |
dec | number Nullable |
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. |
redshift_history | any Nullable Record of who set which redshift values and when. |
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. |
internal_key | string Internal key used for secure websocket messaging. |
detect_photometry_count | integer Nullable How many times the object was detected above :math: |
{- "ra": 0,
- "dec": 0,
- "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
}
{- "status": "success",
- "message": "string"
}
Retrieve all sources
ra | number RA for spatial filtering (in decimal degrees) |
dec | number Declination for spatial filtering (in decimal degrees) |
radius | number Radius for spatial filtering if ra & dec are provided (in decimal degrees) |
sourceID | string Portion of ID to filter on |
simbadClass | string Simbad class to filter on |
alias | Array of any additional name for the same object |
origin | string who posted/discovered this source |
hasTNSname | boolean If true, return only those matches with TNS names |
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 |
totalMatches | integer Used only in the case of paginating query results - if provided, this allows for avoiding a potentially expensive query.count() call. |
startDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by last_detected_at >= startDate |
endDate | string Arrow-parseable date string (e.g. 2020-01-01). If provided, filter by last_detected_at <= endDate |
listName | string Get only sources saved to the querying user's list, e.g., "favorites". |
group_ids | list If provided, filter only sources saved to one of these group IDs. |
includePhotometry | boolean Boolean indicating whether to include associated photometry. Defaults to false. |
includeColorMagnitude | boolean Boolean indicating whether to include the color-magnitude data from Gaia. This will only include data for objects that have an annotation with the appropriate format: a key named Gaia that contains a dictionary with keys named Mag_G, Mag_Bp, Mag_Rp, and Plx (underscores and case are ignored when matching all the above keys). The result is saved in a field named 'color_magnitude'. If no data is available, returns an empty array. Defaults to false (do not search for nor include this info). |
includeRequested | boolean Boolean indicating whether to include requested saves. Defaults to false. |
pendingOnly | boolean Boolean indicating whether to only include requested/pending saves. Defaults to false. |
savedBefore | string Only return sources that were saved before this UTC datetime. |
savedAfter | string Only return sources that were saved after this UTC datetime. |
hasSpectrumAfter | string Only return sources with a spectrum saved after this UTC datetime |
hasSpectrumBefore | string Only return sources with a spectrum saved before this UTC datetime |
saveSummary | boolean Boolean indicating whether to only return the source save
information in the response (defaults to false). If true,
the response will contain a list of dicts with the following
schema under
|
sortBy | string The field to sort by. Currently allowed options are ["id", "ra", "dec", "redshift", "saved_at"] |
sortOrder | string The sort order - either "asc" or "desc". Defaults to "asc" |
includeComments | boolean Boolean indicating whether to include comment metadata in response. Defaults to false. |
includePhotometryExists | boolean Boolean indicating whether to return if a source has any photometry points. Defaults to false. |
includeSpectrumExists | boolean Boolean indicating whether to return if a source has a spectra. Defaults to false. |
removeNested | boolean Boolean indicating whether to remove nested output. Defaults to false. |
includeThumbnails | boolean Boolean indicating whether to include associated thumbnails. Defaults to false. |
includeDetectionStats | boolean Boolean indicating whether to include photometry detection statistics for each source (last detection and peak detection). Defaults to false. |
classifications | Array of strings Comma-separated string of "taxonomy: classification" pair(s) to filter for sources matching that/those classification(s), i.e. "Sitewide Taxonomy: Type II, Sitewide Taxonomy: AGN" |
nonclassifications | Array of strings Comma-separated string of "taxonomy: classification" pair(s) to filter for sources NOT matching that/those classification(s), i.e. "Sitewide Taxonomy: Type II, Sitewide Taxonomy: AGN" |
annotationsFilter | Array of strings Comma-separated string of "annotation: value: operator" triplet(s) to filter for sources matching that/those annotation(s), i.e. "redshift: 0.5: lt" |
annotationsFilterOrigin | string Comma separated string of origins. Only annotations from these origins are used when filtering with the annotationsFilter. |
annotationsFilterBefore | string Only return sources that have annotations before this UTC datetime. |
annotationsFilterAfter | string Only return sources that have annotations after this UTC datetime. |
commentsFilter | Array of strings Comma-separated string of comment text to filter for sources matching. |
commentsFilterAuthor | string Comma separated string of authors. Only comments from these authors are used when filtering with the commentsFilter. |
commentsFilterBefore | string Only return sources that have comments before this UTC datetime. |
commentsFilterAfter | string Only return sources that have comments after this UTC datetime. |
minRedshift | number If provided, return only sources with a redshift of at least this value |
maxRedshift | number If provided, return only sources with a redshift of at most this value |
minPeakMagnitude | number If provided, return only sources with a peak photometry magnitude of at least this value |
maxPeakMagnitude | number If provided, return only sources with a peak photometry magnitude of at most this value |
minLatestMagnitude | number If provided, return only sources whose latest photometry magnitude is at least this value |
maxLatestMagnitude | number If provided, return only sources whose latest photometry magnitude is at most this value |
hasSpectrum | boolean If true, return only those matches with at least one associated spectrum |
createdOrModifiedAfter | string Arrow-parseable date-time string (e.g. 2020-01-01 or 2020-01-01T00:00:00 or 2020-01-01T00:00:00+00:00). If provided, filter by created_at or modified > createdOrModifiedAfter |
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 endpoint or skymap name in GcnEvent page table. |
localizationCumprob | number Cumulative probability up to which to include sources |
includeGeoJSON | boolean Boolean indicating whether to include associated GeoJSON. Defaults to false. |
{- "status": "success",
- "message": "string",
- "data": {
- "sources": [
- {
- "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
}
], - "totalMatches": 0,
- "pageNumber": 0,
- "numPerPage": 0
}
}
Add a new source
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: |
group_ids | Array of integers List of associated group IDs. If not specified, all of the user or token's groups will be used. |
{- "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,
- "group_ids": [
- 0
]
}
{- "status": "success",
- "message": "string",
- "data": {
- "id": "string"
}
}
Retrieve all sources
ra | number RA for spatial filtering (in decimal degrees) |
dec | number Declination for spatial filtering (in decimal degrees) |
radius | number Radius for spatial filtering if ra & dec are provided (in decimal degrees) |
Save or request group(s) to save source, and optionally unsave from group(s).
objId required | string ID of the object in question. |
inviteGroupIds required | Array of integers List of group IDs to save or invite to save specified source. |
unsaveGroupIds | Array of integers List of group IDs from which specified source is to be unsaved. |
{- "objId": "string",
- "inviteGroupIds": [
- 0
], - "unsaveGroupIds": [
- 0
]
}