openapi: 3.0.1
info:
  title: AuroraX Application.wadl Data Distribution API
  description: "## Overview\n\nThis webpage is an interactive documentation interface for the AuroraX RESTful API. This API\nis used by several applications including the AuroraX Conjunction Search, Event Explorer,\nKeogramist, PyAuroraX, and IDL-AuroraX. You can view these applications and libraries at\n<a href='https://aurorax.space' target='_blank'>https://aurorax.space</a> and\n<a href='https://github.com/aurorax-space' target='_blank'>https://github.com/aurorax-space</a>.\n\nDetailed documentation about the AuroraX platform and examples of using this API can be found at\n<a href='https://docs.aurorax.space' target='_blank'>https://docs.aurorax.space</a>.\n\nBelow, we outline the major categories of endpoints available for use:\n\n| Interface        | Description                                                                 |\n| ---------------- | --------------------------------------------------------------------------- |\n| Accounts         | Operations relating to user accounts, API keys, and saved user data         |\n| Authentication   | Authentication using an email address and password, or an API key           |\n| Availability     | Retrieve information describing what data is in the database                |\n| Data Sources     | Interact with data sources                                                  |\n| Conjunctions     | Search for conjunctions between multiple sets of data sources               |\n| Ephemeris        | Search and manage ephemeris data associated with a data source              |\n| Data Products    | Search and manage data products data associated with a data source          |\n| Utils            | Utilities, such as describing a search query in an SQL-like format          |\n\n## Authentication\n\nAuroraX allows for two methods of authentication:\n\n1. Authenticate via username and password using the /authenticate endpoint to obtain an access\n   token. Access tokens need to be sent on every request for secure resources. Inactive access tokens\n   timeout after 30 minutes.\n\n2. Authenticate using an API key sent in the request header (key called 'x-aurorax-api-key')\n\nMore information can be found\n<a href='https://docs.aurorax.space/code/advanced_usage/authentication' target='_blank'>here</a>.\n\n## Errors\n\nThis API uses standard HTTP status codes to indicate the success or failure of the\nAPI call. When an error occurs, the body of the response will be JSON and contain an error code\nand message. All errors will respond with this format:\n```\n{\n    \"error_code\": \"DUPLICATE\",\n    \"error_message\": \"There was a duplicate record found. No changes were made.\"\n}\n```\n"
  version: stable
servers:
- url: https://api.aurorax.space
  description: AuroraX production server
  variables: {}
- url: https://api.staging.aurorax.space
  description: AuroraX staging server
  variables: {}
- url: http://localhost:8080/
  description: Local Development and Debugging
  variables: {}
tags:
- name: Data Distribution
  description: Endpoints supporting data distribution
paths:
  /api/v1/data_distribution/datasets:
    get:
      tags:
      - Data Distribution
      summary: Retrieve available datasets
      description: "Retrieve information about available datasets. Filter based on parameters supplied.\n\nNotes:\n  - filtering is case insensitive\n  - data level description: https://www.earthdata.nasa.gov/engage/open-data-services-and-software/data-information-policy/data-levels"
      operationId: retrieve_datasets_api_v1_data_distribution_datasets_get
      parameters:
      - name: name
        in: query
        required: false
        schema:
          nullable: true
          type: string
          title: Name
      - name: level
        in: query
        required: false
        schema:
          type: string
          enum:
          - L0
          - L1
          - L1A
          - L2
          - L3
          title: Level
      responses:
        '200':
          description: Dataset information
          content:
            application/json:
              schema:
                type: array
                items:
                  anyOf:
                  - $ref: '#/components/schemas/Dataset'
                  - $ref: '#/components/schemas/DatasetLegacy1'
                  - $ref: '#/components/schemas/DatasetLegacy2'
                title: Response Retrieve Datasets Api V1 Data Distribution Datasets Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/data_distribution/urls:
    get:
      tags:
      - Data Distribution
      summary: Retrieve list of URLs for a given dataset
      description: "Retrieve list of URLs for a given dataset and timeframe.\n\nNotes:\n  - start and end times are inclusive\n  - start and end time format is YYYY-mm-ddTHH:MM:SS. Excluding values from the right to \n    the left result in default values being used (eg. YYYY-mm-ddTHH results in YYYY-mm-ddTHH:00:00)\n  - dataset matching is case insensitive\n  - site_uid is expected to be the 4-letter site code, and is case insensitive\n  - device_uid is expected to be the instrument identifier such as \"themis02\", \"rego-657\", or \"rgb-07\",\n    and is case insensitive"
      operationId: retrieve_urls_api_v1_data_distribution_urls_get
      parameters:
      - name: name
        in: query
        required: true
        schema:
          type: string
          title: Name
      - name: start
        in: query
        required: true
        schema:
          type: string
          format: date-time
          title: Start
      - name: end
        in: query
        required: true
        schema:
          type: string
          format: date-time
          title: End
      - name: site_uid
        in: query
        required: false
        schema:
          nullable: true
          type: string
          title: Site Uid
      - name: device_uid
        in: query
        required: false
        schema:
          nullable: true
          type: string
          title: Device Uid
      - name: include_total_bytes
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Total Bytes
      responses:
        '200':
          description: URLs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListingResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Data retrieval error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/data_distribution/observatories:
    get:
      tags:
      - Data Distribution
      summary: Retrieve information about observatories
      description: "Retrieve information about observatories. Filter based on parameters supplied.\n\nNotes:\n  - filtering for \"uid\" is case insensitive"
      operationId: retrieve_observatories_api_v1_data_distribution_observatories_get
      parameters:
      - name: instrument_array
        in: query
        required: true
        schema:
          type: string
          enum:
          - norstar_riometer
          - rego
          - smile_asi
          - swan_hsr
          - themis_asi
          - trex_blue
          - trex_nir
          - trex_rgb
          - trex_spectrograph
          title: Instrument Array
      - name: uid
        in: query
        required: false
        schema:
          nullable: true
          type: string
          title: Uid
      responses:
        '200':
          description: Observatory information
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Observatory'
                title: Response Retrieve Observatories Api V1 Data Distribution Observatories Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/data_distribution/imaging_timeframes:
    post:
      tags:
      - Data Distribution
      summary: Retrieve imaging start and end times for a set of locations
      description: "Retrieve imaging start and end times for a set of locations. This is specific to the optical \ninstrumentation we provide data for.\n\nThe timestamp is expected to be UTC time.\n\nEach location in the 'locations' array can be specified either by a 4-letter site UID, or by\nproviding geodetic latitude and longitude. If the site_uid is provided, it is resolved to\ncoordinates using the known observatory list.\n\nNotes:\n  - The threshold parameter is the solar zenith angle (in degrees) above which imaging occurs. \n    The default value of 102.0 corresponds to nautical twilight, and what all UCalgary optical\n    instruments use.\n  - The `site_uid` parameter matching is case insensitive"
      operationId: retrieve_imaging_timeframes_api_v1_data_distribution_imaging_timeframes_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImagingTimeframesRequest'
        required: true
      responses:
        '200':
          description: Imaging times
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ImagingTimeframeResponse'
                type: array
                title: Response Retrieve Imaging Timeframes Api V1 Data Distribution Imaging Timeframes Post
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Site not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ImagingTimeframeResponse:
      properties:
        timestamp:
          type: string
          title: Timestamp
        site_uid:
          nullable: true
          type: string
          title: Site Uid
        geodetic_latitude:
          type: number
          title: Geodetic Latitude
        geodetic_longitude:
          type: number
          title: Geodetic Longitude
        imaging_start:
          nullable: true
          type: string
          format: date-time
          title: Imaging Start
        imaging_end:
          nullable: true
          type: string
          format: date-time
          title: Imaging End
      type: object
      required:
      - timestamp
      - geodetic_latitude
      - geodetic_longitude
      title: ImagingTimeframeResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DatasetLegacy2:
      properties:
        name:
          type: string
          title: Name
        short_description:
          type: string
          title: Short Description
        long_description:
          type: string
          title: Long Description
        data_tree_url:
          type: string
          title: Data Tree Url
        file_listing_supported:
          type: boolean
          title: File Listing Supported
        level:
          type: string
          title: Level
        doi:
          nullable: true
          type: string
          title: Doi
        doi_details:
          nullable: true
          type: string
          title: Doi Details
        citation:
          nullable: true
          type: string
          title: Citation
        supported_libraries:
          items:
            type: string
            enum:
            - pyaurorax
            - pyucrio
            - idl-aurorax
            - idl-ucrio
            - pyucalgarysrs
          type: array
          title: Supported Libraries
          default: []
      type: object
      required:
      - name
      - short_description
      - long_description
      - data_tree_url
      - file_listing_supported
      - level
      title: DatasetLegacy2
      description: Dataset object for queries from PyAuroraX v1.3.3 or earlier
    FileListingResponse:
      properties:
        urls:
          items:
            type: string
          type: array
          title: Urls
        path_prefix:
          type: string
          title: Path Prefix
        count:
          type: integer
          title: Count
        total_bytes:
          nullable: true
          type: integer
          title: Total Bytes
        dataset:
          anyOf:
          - $ref: '#/components/schemas/Dataset'
          - $ref: '#/components/schemas/DatasetLegacy1'
          - $ref: '#/components/schemas/DatasetLegacy2'
          title: Dataset
      type: object
      required:
      - urls
      - path_prefix
      - count
      - total_bytes
      - dataset
      title: FileListingResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DatasetLegacy1:
      properties:
        name:
          type: string
          title: Name
        short_description:
          type: string
          title: Short Description
        long_description:
          type: string
          title: Long Description
        data_tree_url:
          type: string
          title: Data Tree Url
        file_listing_supported:
          type: boolean
          title: File Listing Supported
        level:
          type: string
          title: Level
        doi:
          nullable: true
          type: string
          title: Doi
        doi_details:
          nullable: true
          type: string
          title: Doi Details
        citation:
          nullable: true
          type: string
          title: Citation
      type: object
      required:
      - name
      - short_description
      - long_description
      - data_tree_url
      - file_listing_supported
      - level
      title: DatasetLegacy1
      description: Dataset object for queries from PyAuroraX v1.3.3 or earlier
    ErrorMessage:
      properties:
        detail:
          type: string
          title: Detail
      type: object
      required:
      - detail
      title: ErrorMessage
    ImagingTimeframesRequest:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        locations:
          items:
            $ref: '#/components/schemas/ImagingTimeframeLocation'
          type: array
          title: Locations
        threshold:
          type: number
          title: Threshold
          default: 102.0
      type: object
      required:
      - timestamp
      - locations
      title: ImagingTimeframesRequest
    Observatory:
      properties:
        uid:
          type: string
          title: Uid
        full_name:
          type: string
          title: Full Name
        geodetic_latitude:
          type: number
          title: Geodetic Latitude
        geodetic_longitude:
          type: number
          title: Geodetic Longitude
      type: object
      required:
      - uid
      - full_name
      - geodetic_latitude
      - geodetic_longitude
      title: Observatory
    Dataset:
      properties:
        name:
          type: string
          title: Name
        short_description:
          type: string
          title: Short Description
        long_description:
          type: string
          title: Long Description
        data_tree_url:
          type: string
          title: Data Tree Url
        file_listing_supported:
          type: boolean
          title: File Listing Supported
        level:
          type: string
          title: Level
        doi:
          nullable: true
          type: string
          title: Doi
        doi_details:
          nullable: true
          type: string
          title: Doi Details
        citation:
          nullable: true
          type: string
          title: Citation
        supported_libraries:
          items:
            type: string
            enum:
            - pyaurorax
            - pyucrio
            - idl-aurorax
            - idl-ucrio
            - pyucalgarysrs
          type: array
          title: Supported Libraries
          default: []
        file_time_resolution:
          type: string
          enum:
          - 1min
          - 1hr
          - 1day
          - not_applicable
          title: File Time Resolution
      type: object
      required:
      - name
      - short_description
      - long_description
      - data_tree_url
      - file_listing_supported
      - level
      - file_time_resolution
      title: Dataset
    ImagingTimeframeLocation:
      properties:
        site_uid:
          nullable: true
          type: string
          title: Site Uid
        geodetic_latitude:
          nullable: true
          type: number
          title: Geodetic Latitude
        geodetic_longitude:
          nullable: true
          type: number
          title: Geodetic Longitude
      type: object
      title: ImagingTimeframeLocation
  securitySchemes:
    AccessToken:
      type: http
      description: Send the Authorization header found in the response of a successful /authentication request on all  secure endpoints. Copy it verbatim to the request header. It is fine to send this header on all requests  to the API. The value in Swagger UI should only include the access token part (leave out 'Bearer').
      name: Authorization
      in: header
      scheme: bearer
      bearerFormat: Generated by server
    ApiKeyAuth:
      type: apiKey
      description: API keys are intended to be used by non-interactive software interfacing with the REST API. These can  be used instead of an Access Token approach.
      name: x-aurorax-api-key
      in: header