swagger.yaml

swagger: '2.0'
info:
  title: Nightscout API
  description: Own your DData with the Nightscout API
  version: "0.8.0"
  license:
    name: AGPL 3
    url: https://www.gnu.org/licenses/agpl.txt
basePath: /api/v1
produces:
  - application/json
security:
  - api_secret: []

paths:

  /entries/{spec}:
    get:
      summary: All Entries matching query
      description: |
        The Entries endpoint returns information about the
        Nightscout entries.

      parameters:
        - name: spec
          in: path
          type: string
          description: |
              entry id, such as `55cf81bc436037528ec75fa5` or a type filter such
              as `sgv`, `mbg`, etc.

          default: sgv
          required: true
        - 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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          type: number
      tags:
        - Entries
      responses:
        "200":
          description: An array of entries
          schema:
            $ref: '#/definitions/Entries'
        default:
          description: Entries
          schema:
            $ref: '#/definitions/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
          type: string
          description: Prefix to use in constructing a prefix-based regex, default is `entries`.
          required: true
          default: entries
        - name: field
          in: path
          type: string
          description: Name of the field to use Regex against in query object, default is `dateString`.
          default: dateString
          required: true
        - name: type
          in: path
          type: string
          description: The type field to search against, default is sgv.
          required: true
          default: sgv
        - name: prefix
          in: path
          type: string
          description: Prefix to use in constructing a prefix-based regex.
          required: true
          default: '2015'
        - name: regex
          in: path
          type: string
          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
          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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          type: number
      tags:
        - Entries
      responses:
        "200":
          description: An array of entries
          schema:
            $ref: '#/definitions/Entries'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/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
          type: string
          description: |
              `entries`, or `treatments` to select the storage layer.

          default: sgv
          required: true
        - name: spec
          in: path
          type: string
          description: |
              entry id, such as `55cf81bc436037528ec75fa5` or a type filter such
              as `sgv`, `mbg`, etc.
              This parameter is optional.

          default: sgv
          required: true
        - 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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          type: number
      tags:
        - Entries
        - Debug
      responses:
        "200":
          description: An array of entries
          schema:
            $ref: '#/definitions/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
          type: string
          description: Prefix to use in constructing a prefix-based regex.
          required: true
        - name: regex
          in: path
          type: string
          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
        - 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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          type: number
      tags:
        - Entries
        - Debug
      responses:
        "200":
          description: An array of entries
          schema:
            $ref: '#/definitions/MongoQuery'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/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
          type: string
          description: Prefix to use in constructing a prefix-based regex.
          required: true
        - name: regex
          in: path
          type: string
          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
        - 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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          type: number
      tags:
        - Entries
      responses:
        "200":
          description: An array of entries
          schema:
            $ref: '#/definitions/Entries'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          type: number
      tags:
        - Entries
      responses:
        "200":
          description: An array of entries
          schema:
            $ref: '#/definitions/Entries'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

    post:
      tags:
        - Entries
      summary: Add new entries.
      description: ""
      operationId: addEntries
      consumes:
        - application/json
        - text/plain
      produces:
        - application/json
        - text/plain
      parameters:
        - in: body
          name: body
          description: Entries to be uploaded.
          required: true
          schema:
            $ref: "#/definitions/Entries"
      responses:
        "405":
          description: Invalid input
        "200":
          description: Rejected list of entries.  Empty list is success.
    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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          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
          type: string
        - name: count
          in: query
          description: Number of entries to return.
          required: false
          type: number
      responses:
        "200":
          description: An array of treatments
          schema:
            $ref: '#/definitions/Treatments'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
          tags:
            - Treatments
          summary: Add new treatments.
          description: ""
          operationId: addTreatments
          consumes:
            - application/json
          produces:
            - application/json
          parameters:
            - in: body
              name: body
              description: Treatments to be uploaded.
              required: true
              schema:
                $ref: "#/definitions/Treatments"
          responses:
            "405":
              description: Invalid input
            "200":
              description: Rejected list of treatments.  Empty list is success.

  /profile:
    get:
      summary: Profile
      description: The Profile endpoint returns information about the Nightscout Treatment Profiles.
      tags:
        - Profile
      responses:
        "200":
          description: An array of treatments
          schema:
            $ref: '#/definitions/Profile'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

  /status:
    get:
      summary: Status
      description: Server side status, default settings and capabilities.
      tags:
        - Status
      responses:
        "200":
          description: Server capabilities and status.
          schema:
            $ref: '#/definitions/Status'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

securityDefinitions:
  api_secret:
    type: apiKey
    name: api_secret
    in: header
    description: The hash of the API_SECRET env var

definitions:
  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: '#/definitions/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: '#/definitions/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: '#/definitions/Settings'
      extendedSettings:
        $ref: '#/definitions/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: '#/definitions/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