MAST application programming interfaces (APIs) provide a direct and efficient means for experienced users to search for and retrieve data products. The APIs that are most relevant for JWST are illustrated via a collection of tutorials which you can customize to your own scientific needs.
On this page...
MAST Web Services
Much of the functionality of MAST is provided through a variety of web services. The MAST Portal itself is a Web application that calls MAST web services to provide data search, selection, and retrieval functionality. Most of these same services are available to users via multiple MAST application programming interfaces (APIs). These APIs offer a very efficient means to create custom, scripted access to JWST data products. The figure below is a simplified view of the interaction between users and MAST back-end services.
Figure 1 — Users (right) interact with a MAST Web UI or an API, either of which call back-end services (left) to access databases and data files. The information is retrieved and is forwarded back to the interface.
Most data in MAST can be retrieved anonymously. But retrieving protected data with an API requires both authentication and authorization. Authorization is granted by MAST to program Principal Investigators, and may be granted by a PI to their collaborators. Authentication in the Portal is achieved by logging in with your MyST credentials; authentication for scripted retrieval is achieved with a MAST API token. These tokens, which are long alpha-numeric strings, may be provided to a script:
- with a command-line argument
- by a user responding to a prompt
- by storing the token string in the shell environment variable
Users of bash can do this in the shell they use to access an API with the following command (or, optionally, store in their
export MAST_API_TOKEN=<token string>
Generate the token with the tokens page.
Token Expiration Policy
For security reasons MAST tokens expire after 10 days of inactivity or 60 days after creation, whichever comes first. If you have a script which used to work but now fails with an authorization error, check to see if your token is still active. It is easy to generate a new MAST token.
The following subsections provide a variety of examples of how to use the MAST APIs with python or shell scripts. For a more extensive discussion of MAST APIs, with many more worked examples, see MAST Web Services. Some of the tutorials below take the form of Jupyter notebooks, which reside in an STScI notebook repository.