Superfacility API Documentation¶
This page presents some general information about the NERSC Superfacility Application Programming Interface (API).
The API can be used to script jobs or workflows running against NERSC systems. The goal is to support everything from a simple script that submits a job to complex workflows that move files, check job progress and make advance compute time reservations.
The API endpoint can be accessed here: https://api.nersc.gov/api/v1.2/
That is also the place to find the up-to-date reference documentation, and it presents a UI to interact with the API from inside your browser.
If you'd like to use the API, please follow these three steps.
Create a Superfacility API Client in Iris.
You can create the client on your profile page in the section "Superfacility API Clients". Every NERSC user can create read-only clients. For r/w-capable clients (i.e. for submitting jobs), please fill out the form that is linked in the client's user interface.
Exchange a client credentials for access tokens.
Use the private key of your client to generate a "client assertion" which, in turn, can be exchanged for an "access token". Access tokens have short lifetimes of approximately 10 minutes.
Call the SuperFacility API (with the access token).
Once you have the access token, you can call the API at: https://api.nersc.gov/api/v1.2/. We also created a number of examples for you to get you started. Make sure to check them out.
Steps one and two are needed for authentication and can be skipped if you use API calls that don't require an access token (for example calls to systems status).
Citing the API¶
A paper specifically about the Superfacility API will be out soon. Some aspects of the API were first described in:
B. Enders et al.,"Cross-facility science with the Superfacility Project at LBNL," 2020 IEEE/ACM 2nd Annual Workshop on Extreme-scale Experiment-in-the-Loop Computing (XLOOP), 2020, pp. 1-7, doi: 10.1109/XLOOP51963.2020.00006.