swagger.yaml

openapi: 3.0.0
servers:
  - url: /api/v1
info:
  title: Nightscout API
  description: Own your DData with the Nightscout API
  version: 0.10.3-master-20180805
  license:
    name: AGPL 3
    url: 'https://www.gnu.org/licenses/agpl.txt'
security:
  - api_secret: []
    token_in_url: []
    jwtoken: []
paths:
  '/entries/{spec}':
    get:
      summary: All Entries matching query
      description: |
        The Entries endpoint returns information about the
        Nightscout entries.
      parameters:
        - name: spec
          in: path
          description: |
            entry id, such as `55cf81bc436037528ec75fa5` or a type filter such
            as `sgv`, `mbg`, etc.
          required: true
          schema:
            type: string
            default: sgv
        - name: find
          in: query
          description: |
            The query used to find entries, support nested query syntax, for
            example `find[dateString][$gte]=2015-08-27`.  All find parameters
            are interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      tags:
        - Entries
      responses:
        '200':
          description: An array of entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entries'
        default:
          description: Entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entries'
  '/slice/{storage}/{field}/{type}/{prefix}/{regex}':
    get:
      summary: All Entries matching query
      description: The Entries endpoint returns information about the Nightscout entries.
      parameters:
        - name: storage
          in: path
          description: >-
            Prefix to use in constructing a prefix-based regex, default is
            `entries`.
          required: true
          schema:
            type: string
            default: entries
        - name: field
          in: path
          description: >-
            Name of the field to use Regex against in query object, default is
            `dateString`.
          required: true
          schema:
            type: string
            default: dateString
        - name: type
          in: path
          description: 'The type field to search against, default is sgv.'
          required: true
          schema:
            type: string
            default: sgv
        - name: prefix
          in: path
          description: Prefix to use in constructing a prefix-based regex.
          required: true
          schema:
            type: string
            default: '2015'
        - name: regex
          in: path
          description: >
            Tail part of regexp to use in expanding/construccting a query
            object.

            Regexp also has bash-style brace and glob expansion applied to it,

            creating ways to search for modal times of day, perhaps using

            something like this syntax: `T{15..17}:.*`, this would search for

            all records from 3pm to 5pm.
          required: true
          schema:
            type: string
            default: .*
        - name: find
          in: query
          description: |
            The query used to find entries, support nested query syntax, for
            example `find[dateString][$gte]=2015-08-27`.  All find parameters
            are interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      tags:
        - Entries
      responses:
        '200':
          description: An array of entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entries'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/echo/{storage}/{spec}':
    get:
      summary: View generated Mongo Query object
      description: |
        Information about the mongo query object created by the query.
      parameters:
        - name: storage
          in: path
          description: |
            `entries`, or `treatments` to select the storage layer.
          required: true
          schema:
            type: string
            default: sgv
        - name: spec
          in: path
          description: |
            entry id, such as `55cf81bc436037528ec75fa5` or a type filter such
            as `sgv`, `mbg`, etc.
            This parameter is optional.
          required: true
          schema:
            type: string
            default: sgv
        - name: find
          in: query
          description: |
            The query used to find entries, support nested query syntax, for
            example `find[dateString][$gte]=2015-08-27`.  All find parameters
            are interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      tags:
        - Entries
        - Debug
      responses:
        '200':
          description: An array of entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MongoQuery'
  '/times/echo/{prefix}/{regex}':
    get:
      summary: Echo the query object to be used.
      description: Echo debug information about the query object constructed.
      parameters:
        - name: prefix
          in: path
          description: Prefix to use in constructing a prefix-based regex.
          required: true
          schema:
            type: string
        - name: regex
          in: path
          description: >
            Tail part of regexp to use in expanding/construccting a query
            object.

            Regexp also has bash-style brace and glob expansion applied to it,

            creating ways to search for modal times of day, perhaps using

            something like this syntax: `T{15..17}:.*`, this would search for

            all records from 3pm to 5pm.
          required: true
          schema:
            type: string
        - name: find
          in: query
          description: >-
            The query used to find entries, support nested query syntax, for
            example `find[dateString][$gte]=2015-08-27`.  All find parameters
            are interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      tags:
        - Entries
        - Debug
      responses:
        '200':
          description: An array of entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MongoQuery'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/times/{prefix}/{regex}':
    get:
      summary: All Entries matching query
      description: The Entries endpoint returns information about the Nightscout entries.
      parameters:
        - name: prefix
          in: path
          description: Prefix to use in constructing a prefix-based regex.
          required: true
          schema:
            type: string
        - name: regex
          in: path
          description: >
            Tail part of regexp to use in expanding/construccting a query
            object.

            Regexp also has bash-style brace and glob expansion applied to it,

            creating ways to search for modal times of day, perhaps using

            something like this syntax: `T{15..17}:.*`, this would search for

            all records from 3pm to 5pm.
          required: true
          schema:
            type: string
        - name: find
          in: query
          description: >-
            The query used to find entries, support nested query syntax, for
            example `find[dateString][$gte]=2015-08-27`.  All find parameters
            are interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      tags:
        - Entries
      responses:
        '200':
          description: An array of entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entries'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /entries:
    get:
      summary: All Entries matching query
      description: The Entries endpoint returns information about the Nightscout entries.
      parameters:
        - name: find
          in: query
          description: >-
            The query used to find entries, support nested query syntax, for
            example `find[dateString][$gte]=2015-08-27`.  All find parameters
            are interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      tags:
        - Entries
      responses:
        '200':
          description: An array of entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entries'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Entries
      summary: Add new entries.
      description: ''
      operationId: addEntries
      responses:
        '200':
          description: Rejected list of entries.  Empty list is success.
        '405':
          description: Invalid input
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entries'
          text/plain:
            schema:
              $ref: '#/components/schemas/Entries'
        description: Entries to be uploaded.
        required: true
    delete:
      tags:
        - Entries
      summary: Delete entries matching query.
      description: 'Remove entries, same search syntax as GET.'
      operationId: remove
      parameters:
        - name: find
          in: query
          description: >-
            The query used to find entries, support nested query syntax, for
            example `find[dateString][$gte]=2015-08-27`.  All find parameters
            are interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      responses:
        '200':
          description: Empty list is success.
  /treatments:
    get:
      summary: Treatments
      description: >-
        The Treatments endpoint returns information about the Nightscout
        treatments.
      tags:
        - Treatments
      parameters:
        - name: find
          in: query
          description: >-
            The query used to find entries, supports nested query syntax. 
            Examples `find[insulin][$gte]=3` `find[carb][$gte]=100`
            `find[eventType]=Correction+Bolus` All find parameters are
            interpreted as strings.
          required: false
          schema:
            type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          schema:
            type: number
      responses:
        '200':
          description: An array of treatments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Treatments'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Treatments
      summary: Add new treatments.
      description: ''
      operationId: addTreatments
      responses:
        '200':
          description: Rejected list of treatments.  Empty list is success.
        '405':
          description: Invalid input
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Treatments'
        description: Treatments to be uploaded.
        required: true
  /profile:
    get:
      summary: Profile
      description: >-
        The Profile endpoint returns information about the Nightscout Treatment
        Profiles.
      tags:
        - Profile
      responses:
        '200':
          description: An array of treatments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /status:
    get:
      summary: Status
      description: 'Server side status, default settings and capabilities.'
      tags:
        - Status
      responses:
        '200':
          description: Server capabilities and status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    api_secret:
      type: apiKey
      name: api_secret
      in: header
      description: The hash of the API_SECRET env var
    token_in_url:
      type: apiKey
      name: token
      in: query
      description: Add token as query item in the URL. You can manage access Token in `/admin`. This uses json webtokens.
    jwtoken:
      type: http
      scheme: bearer
      description: Use this if you know the temporary json webtoken.
      bearerFormat: JWT
  schemas:
    Entry:
      properties:
        type:
          type: string
          description: 'sgv, mbg, cal, etc'
        dateString:
          type: string
          description: 'dateString, prefer ISO `8601`'
        date:
          type: number
          description: Epoch
        sgv:
          type: number
          description: The glucose reading. (only available for sgv types)
        direction:
          type: string
          description: >-
            Direction of glucose trend reported by CGM. (only available for sgv
            types)
        noise:
          type: number
          description: Noise level at time of reading. (only available for sgv types)
        filtered:
          type: number
          description: >-
            The raw filtered value directly from CGM transmitter. (only
            available for sgv types)
        unfiltered:
          type: number
          description: >-
            The raw unfiltered value directly from CGM transmitter. (only
            available for sgv types)
        rssi:
          type: number
          description: >-
            The signal strength from CGM transmitter. (only available for sgv
            types)
    Entries:
      type: array
      items:
        $ref: '#/components/schemas/Entry'
    Treatment:
      properties:
        _id:
          type: string
          description: Internally assigned id.
        eventType:
          type: string
          description: The type of treatment event.
        created_at:
          type: string
          description: 'The date of the event, might be set retroactively .'
        glucose:
          type: string
          description: Current glucose.
        glucoseType:
          type: string
          description: 'Method used to obtain glucose, Finger or Sensor.'
        carbs:
          type: number
          description: Number of carbs.
        insulin:
          type: number
          description: 'Amount of insulin, if any.'
        units:
          type: string
          description: 'The units for the glucose value, mg/dl or mmol.'
        notes:
          type: string
          description: Description/notes of treatment.
        enteredBy:
          type: string
          description: Who entered the treatment.
    Treatments:
      type: array
      items:
        $ref: '#/components/schemas/Treatment'
    Profile:
      properties:
        sens:
          type: integer
          description: Internally assigned id
        dia:
          type: integer
          description: Internally assigned id
        carbratio:
          type: integer
          description: Internally assigned id
        carbs_hr:
          type: integer
          description: Internally assigned id
        _id:
          type: string
          description: Internally assigned id
    Status:
      properties:
        apiEnabled:
          type: boolean
          description: Whether or not the REST API is enabled.
        careportalEnabled:
          type: boolean
          description: Whether or not the careportal is enabled in the API.
        head:
          type: string
          description: The git identifier for the running instance of the app.
        name:
          type: string
          description: Nightscout (static)
        version:
          type: string
          description: The version label of the app.
        settings:
          $ref: '#/components/schemas/Settings'
        extendedSettings:
          $ref: '#/components/schemas/ExtendedSettings'
    Settings:
      properties:
        units:
          type: string
          description: Default units for glucose measurements across the server.
        timeFormat:
          type: string
          description: Default time format
          enum:
            - 12
            - 24
        customTitle:
          type: string
          description: Default custom title to be displayed system wide.
        nightMode:
          type: boolean
          description: Should Night mode be enabled by default?
        theme:
          type: string
          description: >-
            Default theme to be displayed system wide, `default`, `colors`,
            `colorblindfriendly`.
        language:
          type: string
          description: Default language code to be used system wide
        showPlugins:
          type: string
          description: Plugins that should be shown by default
        showRawbg:
          type: string
          description: >-
            If Raw BG is enabled when should it be shown? `never`, `always`,
            `noise`
        alarmTypes:
          type: array
          items:
            type: string
          enum:
            - simple
            - predict
          description: 'Enabled alarm types, can be multiple'
        alarmUrgentHigh:
          type: boolean
          description: >-
            Enable/Disable client-side Urgent High alarms by default, for use
            with `simple` alarms.
        alarmHigh:
          type: boolean
          description: >-
            Enable/Disable client-side High alarms by default, for use with
            `simple` alarms.
        alarmLow:
          type: boolean
          description: >-
            Enable/Disable client-side Low alarms by default, for use with
            `simple` alarms.
        alarmUrgentLow:
          type: boolean
          description: >-
            Enable/Disable client-side Urgent Low alarms by default, for use
            with `simple` alarms.
        alarmTimeagoWarn:
          type: boolean
          description: Enable/Disable client-side stale data alarms by default.
        alarmTimeagoWarnMins:
          type: number
          description: Number of minutes before a stale data warning is generated.
        alarmTimeagoUrgent:
          type: boolean
          description: Enable/Disable client-side urgent stale data alarms by default.
        alarmTimeagoUrgentMins:
          type: number
          description: Number of minutes before a stale data warning is generated.
        enable:
          type: array
          items:
            type: string
          description: Enabled features
        thresholds:
          $ref: '#/components/schemas/Threshold'
    Threshold:
      properties:
        bg_high:
          type: integer
          description: High BG range.
        bg_target_top:
          type: integer
          description: Top of target range.
        bg_target_bottom:
          type: integer
          description: Bottom of target range.
        bg_low:
          type: integer
          description: Low BG range.
    ExtendedSettings:
      description: Extended settings of client side plugins
    MongoQuery:
      description: Mongo Query object.
    Error:
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        fields:
          type: object