Using UltraViolet’s REST API

The following documentation serves as a reference for using the UltraViolet REST API. Files over 50 GB cannot be downloaded via the web browser interface, so you will need to use the API to get at some files. UltraViolet is built on InvenioRDM and full documentation for InvenioRDM’s API can be found on their website: https://inveniordm.docs.cern.ch/reference/rest_api_index. These instructions are specified adaptations for UltraViolet, so for what is not mentioned here, refer to the general InvenioRDM API documentation.

Instructions below use cURL to interact with UltraViolet’s API. Most systems, including Windows 10+, macOS, and Linux, come with cURL pre-installed. Users can also interact with the API using another programming language of their choice (e.g. Python, R).

Download Metadata Only from UltraViolet via REST API

  1. Open a Terminal or Command Prompt
    To open a Terminal or Command Prompt,
    on Windows: Press Windows Key + R, type cmd, and hit Enter.
    on macOS: Press Command + Space, type Terminal, and hit Enter.

  2. Get the Record ID.
    Extract the record ID from the link to the record. In this example for https://ultraviolet.library.nyu.edu/records/8kwtw-sfc84, the ID is 8kwtw-sfc84.

  3. Use the GET command with curl.
    Run the following command. Replace RECORD_ID with the actual record ID:

    $ curl -X GET "https://ultraviolet.library.nyu.edu/api/records/RECORD_ID/"

    Once complete, it will print the Record information to the terminal window.

  4. For restricted records, you will need an authorization code.
    Login to UltraViolet, and visit:
    https://ultraviolet.library.nyu.edu/account/settings/applications

    Where it says “Personal Access Token,” create a new token and name it whatever you want. Copy and save the newly generated token (you can never get this again, so if you lose this, you’ll need to recreate a new token). Click “Save” for it to come into effect.

    To use curl to download restricted record, replace the RECORD_ID with the restricted record’s ID and replace the YOUR_ACCESS_TOKEN with the recently generated token:

    $ curl -X GET "https://ultraviolet.library.nyu.edu/api/records/RECORD_ID/" -H "Authorization: Bearer YOUR_ACCESS_TOKEN”

Download a File from UltraViolet via REST API

  1. Open a Terminal or Command Prompt
    To open a Terminal or Command Prompt,
    on Windows: Press Windows Key + R, type cmd, and hit Enter.
    on macOS: Press Command + Space, type Terminal, and hit Enter.

  2. Get the Record ID.
    Extract the record ID from the link to the record. In this example for https://ultraviolet.library.nyu.edu/records/8kwtw-sfc84, the ID is 8kwtw-sfc84.

  3. Get the File Name from the Record.
    Identify the file name you want to download, such as 2024_Sarmiento_Thesis.pdf.

  4. Use the curl Command. 
    Run the following command. Replace RECORD_ID and FILE_NAME with the actual record ID and then what you want the downloaded file to be called. Using the -o flag means the file will be saved to your computer rather than just read out on the screen. Once complete, it will be saved in the same folder as where you ran the command in the terminal.

    $ curl -X GET "https://ultraviolet.library.nyu.edu/api/records/RECORD_ID/files/FILE_NAME/content" -o "FILE_NAME"

    Example; copy and paste the following into your terminal and press enter:

    $ curl -X GET "https://ultraviolet.library.nyu.edu/api/records/8kwtw-sfc84/files/2024_Sarmiento_Thesis.pdf/content" -o "2024_SarimentoThesis.pdf"

    If successful, the output will look like this:

    % Total % Received % Xferd AverageDload SpeedUpload
    100     423k    100  423k   10.0M

    TotalTime TimeSpent TimeLeft  CurrentSpeed
    --:--:-- --:--:-- --:--:-- 10.3M

  5. For restricted records, you will need an authorization code.
    Login to UltraViolet, and visit: https://ultraviolet.library.nyu.edu/account/settings/applications

    Where it says “Personal Access Token,” create a new token and name it whatever you want. Copy and save the newly generated token (you can never get this again, so if you lose this, you’ll need to recreate a new token). Click “Save” for it to come into effect.

    Use curl to download a restricted file, replacing the YOUR_ACCESS_TOKEN with the generated token.

    $ curl -X GET "https://ultraviolet.library.nyu.edu/api/records/8kwtw-sfc84/files/2024_Sarmiento_Thesis.pdf/content" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -o "2024_Sarmiento_Thesis.pdf"