openapi: 3.0.3
info:
  title: Dexcom Developer API
  version: v3
  description: >-
    The Dexcom Developer API provides authorized third-party applications with
    read access to a Dexcom user's continuous glucose monitoring (CGM) data.
    Resources include estimated glucose values (EGVs), calibrations, events,
    alerts, devices, and data range. The API uses OAuth 2.0 authorization code
    flow and exposes separate sandbox and production environments.
  contact:
    name: Dexcom Developer Program
    url: https://developer.dexcom.com/
  termsOfService: https://developer.dexcom.com/terms-of-use
  x-generated-from: documentation
  x-source-url: https://developer.dexcom.com/docs/dexcomv3/endpoint-overview
  x-last-validated: '2026-05-05'
servers:
  - url: https://api.dexcom.com
    description: Production (United States)
  - url: https://api.dexcom.eu
    description: Production (Europe / International)
  - url: https://api.dexcom.jp
    description: Production (Japan)
  - url: https://sandbox-api.dexcom.com
    description: Sandbox (Development)
security:
  - OAuth2: []
tags:
  - name: Authentication
    description: OAuth 2.0 authorization and token operations.
  - name: Estimated Glucose Values
    description: Time-series CGM glucose readings for the authorized user.
  - name: Events
    description: User-entered events such as carbohydrate intake, insulin doses, exercise, and health events.
  - name: Calibrations
    description: User calibration entries from fingerstick blood glucose meter readings.
  - name: Alerts
    description: Alert events generated by the user's CGM display device.
  - name: Devices
    description: Information about the user's CGM transmitters and display devices.
  - name: Data Range
    description: Earliest and latest record times available for the authorized user.
paths:
  /v2/oauth2/login:
    get:
      tags:
        - Authentication
      operationId: userAuthorization
      summary: Initiate OAuth 2.0 Authorization
      description: >-
        Redirect the end user to the Dexcom hosted login page to obtain an
        authorization code. The user authenticates with Dexcom credentials and
        consents to share CGM data with the requesting application.
      parameters:
        - name: client_id
          in: query
          required: true
          description: The application's registered client identifier.
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          description: Registered redirect URI to which the authorization code is appended.
          schema:
            type: string
            format: uri
        - name: response_type
          in: query
          required: true
          description: Must be set to `code` for authorization code flow.
          schema:
            type: string
            enum:
              - code
        - name: scope
          in: query
          required: true
          description: Must be `offline_access` (the only currently accepted value).
          schema:
            type: string
            enum:
              - offline_access
        - name: state
          in: query
          required: false
          description: Opaque value used to maintain state between request and callback (CSRF protection).
          schema:
            type: string
      responses:
        '302':
          description: Redirect to the registered redirect URI with an authorization code.
          headers:
            Location:
              schema:
                type: string
                format: uri
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v2/oauth2/token:
    post:
      tags:
        - Authentication
      operationId: exchangeAuthorizationCode
      summary: Exchange Authorization Code for Tokens
      description: >-
        Exchange a single-use authorization code for an access token and
        refresh token, or refresh an existing access token using a refresh
        token. Tokens must be stored on the partner's server.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token and refresh token returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                ExchangeAuthorizationCode200Example:
                  summary: Default exchangeAuthorizationCode 200 response
                  x-microcks-default: true
                  value:
                    access_token: '{your_access_token}'
                    expires_in: 7200
                    token_type: Bearer
                    refresh_token: '{your_refresh_token}'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/users/self/dataRange:
    get:
      tags:
        - Data Range
      operationId: getDataRangeV3
      summary: Get Data Range
      description: >-
        Retrieve the earliest and latest record timestamps available for the
        authorized user across calibrations, EGVs, and events. Use this to
        efficiently page historical data and to determine when new data is
        available.
      parameters:
        - name: lastSyncTime
          in: query
          required: false
          description: Optional ISO 8601 timestamp; the response only reflects records updated since this time.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Data range retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataRangeResponse'
              examples:
                GetDataRangeV3200Example:
                  summary: Default getDataRangeV3 200 response
                  x-microcks-default: true
                  value:
                    recordType: dataRange
                    recordVersion: '3.0'
                    userId: 35d77a14-243f-4d5d-9f3f-3b3a7d7e9c3a
                    calibrations:
                      start:
                        systemTime: '2026-01-15T08:32:11'
                        displayTime: '2026-01-15T01:32:11'
                      end:
                        systemTime: '2026-04-30T19:18:24'
                        displayTime: '2026-04-30T12:18:24'
                    egvs:
                      start:
                        systemTime: '2026-01-15T08:00:00'
                        displayTime: '2026-01-15T01:00:00'
                      end:
                        systemTime: '2026-04-30T23:55:00'
                        displayTime: '2026-04-30T16:55:00'
                    events:
                      start:
                        systemTime: '2026-01-15T09:14:02'
                        displayTime: '2026-01-15T02:14:02'
                      end:
                        systemTime: '2026-04-29T17:42:55'
                        displayTime: '2026-04-29T10:42:55'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/users/self/egvs:
    get:
      tags:
        - Estimated Glucose Values
      operationId: getEgvsV3
      summary: Get Estimated Glucose Values
      description: >-
        Retrieve estimated glucose values (EGVs) for the authorized user
        between `startDate` and `endDate`. The maximum window is 30 days and
        timestamps are interpreted against the device `systemTime` field.
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Successful EGV retrieval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EgvsResponse'
              examples:
                GetEgvsV3200Example:
                  summary: Default getEgvsV3 200 response
                  x-microcks-default: true
                  value:
                    recordType: egv
                    recordVersion: '3.0'
                    userId: 35d77a14-243f-4d5d-9f3f-3b3a7d7e9c3a
                    records:
                      - recordId: 1f3a9b56-1f4f-4c70-9d2c-bb4f5d6e0001
                        systemTime: '2026-04-30T15:00:00'
                        displayTime: '2026-04-30T08:00:00'
                        transmitterId: 8GA1JK
                        transmitterTicks: 12345678
                        value: 142
                        status: ok
                        trend: flat
                        trendRate: 0.3
                        unit: mg/dL
                        rateUnit: mg/dL/min
                        displayDevice: iOS
                        transmitterGeneration: g7
                      - recordId: 1f3a9b56-1f4f-4c70-9d2c-bb4f5d6e0002
                        systemTime: '2026-04-30T15:05:00'
                        displayTime: '2026-04-30T08:05:00'
                        transmitterId: 8GA1JK
                        transmitterTicks: 12345978
                        value: 148
                        status: ok
                        trend: fortyFiveUp
                        trendRate: 1.2
                        unit: mg/dL
                        rateUnit: mg/dL/min
                        displayDevice: iOS
                        transmitterGeneration: g7
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/users/self/events:
    get:
      tags:
        - Events
      operationId: getEventsV3
      summary: Get User-Entered Events
      description: >-
        Retrieve user-entered event records (carbohydrates, insulin, exercise,
        and health events) between `startDate` and `endDate`.
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Successful events retrieval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
              examples:
                GetEventsV3200Example:
                  summary: Default getEventsV3 200 response
                  x-microcks-default: true
                  value:
                    recordType: event
                    recordVersion: '3.0'
                    userId: 35d77a14-243f-4d5d-9f3f-3b3a7d7e9c3a
                    records:
                      - recordId: 9b2e4f78-9aa4-4f10-aa01-2c0d1e7f0001
                        systemTime: '2026-04-30T12:30:00'
                        displayTime: '2026-04-30T05:30:00'
                        eventType: carbs
                        eventSubType: null
                        value: 45
                        unit: grams
                        eventStatus: created
                        transmitterId: 8GA1JK
                        transmitterGeneration: g7
                        displayDevice: iOS
                      - recordId: 9b2e4f78-9aa4-4f10-aa01-2c0d1e7f0002
                        systemTime: '2026-04-30T12:35:00'
                        displayTime: '2026-04-30T05:35:00'
                        eventType: insulin
                        eventSubType: fastActing
                        value: 4.5
                        unit: units
                        eventStatus: created
                        transmitterId: 8GA1JK
                        transmitterGeneration: g7
                        displayDevice: iOS
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/users/self/calibrations:
    get:
      tags:
        - Calibrations
      operationId: getCalibrationsV3
      summary: Get Calibration Entries
      description: >-
        Retrieve calibration entries (fingerstick blood glucose meter values
        entered by the user) between `startDate` and `endDate`.
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Successful calibrations retrieval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalibrationsResponse'
              examples:
                GetCalibrationsV3200Example:
                  summary: Default getCalibrationsV3 200 response
                  x-microcks-default: true
                  value:
                    recordType: calibration
                    recordVersion: '3.0'
                    userId: 35d77a14-243f-4d5d-9f3f-3b3a7d7e9c3a
                    records:
                      - recordId: 7d8e0011-3a55-4b40-9c32-aa991100c001
                        systemTime: '2026-04-30T08:11:30'
                        displayTime: '2026-04-30T01:11:30'
                        unit: mg/dL
                        value: 117
                        displayDevice: receiver
                        transmitterId: 8GA1JK
                        transmitterTicks: 12345610
                        transmitterGeneration: g6
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/users/self/alerts:
    get:
      tags:
        - Alerts
      operationId: getAlertsV3
      summary: Get Alert Events
      description: >-
        Retrieve alert events (high, low, urgent low, rise, fall, no readings,
        and out-of-range alerts) generated by the user's CGM display device
        between `startDate` and `endDate`.
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: Successful alerts retrieval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsResponse'
              examples:
                GetAlertsV3200Example:
                  summary: Default getAlertsV3 200 response
                  x-microcks-default: true
                  value:
                    recordType: alert
                    recordVersion: '3.0'
                    userId: 35d77a14-243f-4d5d-9f3f-3b3a7d7e9c3a
                    records:
                      - recordId: a1b2c3d4-aaaa-4bbb-9ccc-dddddddd0001
                        systemTime: '2026-04-30T03:14:00'
                        displayTime: '2026-04-29T20:14:00'
                        alertName: low
                        alertState: activeAlarming
                        displayDevice: iOS
                        transmitterGeneration: g7
                        transmitterId: 8GA1JK
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/users/self/devices:
    get:
      tags:
        - Devices
      operationId: getDevicesV3
      summary: Get Device Information
      description: >-
        Retrieve information about the user's Dexcom devices, including G6,
        G7, Dexcom ONE / ONE+ display devices and transmitters.
      responses:
        '200':
          description: Successful device retrieval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicesResponse'
              examples:
                GetDevicesV3200Example:
                  summary: Default getDevicesV3 200 response
                  x-microcks-default: true
                  value:
                    recordType: device
                    recordVersion: '3.0'
                    userId: 35d77a14-243f-4d5d-9f3f-3b3a7d7e9c3a
                    records:
                      - lastUploadDate: '2026-04-30T15:05:00'
                        transmitterId: 8GA1JK
                        transmitterGeneration: g7
                        displayDevice: iOS
                        displayApp: Dexcom G7
                        alertSchedules:
                          - alertScheduleSettings:
                              alertScheduleName: Default
                              isEnabled: true
                              isDefaultSchedule: true
                              startTime: '00:00'
                              endTime: '00:00'
                              daysOfWeek:
                                - sunday
                                - monday
                                - tuesday
                                - wednesday
                                - thursday
                                - friday
                                - saturday
                            alertSettings:
                              - alertName: high
                                value: 240
                                unit: mg/dL
                                snooze: 30
                                enabled: true
                              - alertName: low
                                value: 80
                                unit: mg/dL
                                snooze: 30
                                enabled: true
                              - alertName: urgentLow
                                value: 55
                                unit: mg/dL
                                snooze: 30
                                enabled: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: >-
        Dexcom uses OAuth 2.0 authorization code flow. The only acceptable
        scope value is `offline_access`.
      flows:
        authorizationCode:
          authorizationUrl: https://api.dexcom.com/v2/oauth2/login
          tokenUrl: https://api.dexcom.com/v2/oauth2/token
          refreshUrl: https://api.dexcom.com/v2/oauth2/token
          scopes:
            offline_access: Long-lived access to the user's CGM data via refresh tokens.
  parameters:
    StartDate:
      name: startDate
      in: query
      required: true
      description: ISO 8601 timestamp for the start of the query window (UTC, no offset).
      schema:
        type: string
        format: date-time
        example: '2026-04-01T00:00:00'
    EndDate:
      name: endDate
      in: query
      required: true
      description: ISO 8601 timestamp for the end of the query window (UTC, no offset). Must be no more than 30 days after `startDate`.
      schema:
        type: string
        format: date-time
        example: '2026-04-30T23:59:59'
  schemas:
    TokenRequest:
      type: object
      description: Form-encoded request body for the token endpoint.
      properties:
        client_id:
          type: string
          description: Application's registered client identifier.
        client_secret:
          type: string
          description: Application's client secret.
        code:
          type: string
          description: Single-use authorization code (required when `grant_type=authorization_code`).
        refresh_token:
          type: string
          description: Refresh token (required when `grant_type=refresh_token`).
        grant_type:
          type: string
          enum:
            - authorization_code
            - refresh_token
        redirect_uri:
          type: string
          format: uri
          description: Registered redirect URI (required for `authorization_code`).
      required:
        - client_id
        - client_secret
        - grant_type
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Bearer token used in the `Authorization` header for subsequent requests.
        expires_in:
          type: integer
          description: Lifetime in seconds of the access token.
          example: 7200
        token_type:
          type: string
          example: Bearer
        refresh_token:
          type: string
          description: Refresh token used to obtain a new access token.
    DateTime:
      type: string
      format: date-time
      description: ISO 8601 timestamp.
    DataRangeMoment:
      type: object
      properties:
        systemTime:
          $ref: '#/components/schemas/DateTime'
        displayTime:
          $ref: '#/components/schemas/DateTime'
      required:
        - systemTime
        - displayTime
    DataRangeWindow:
      type: object
      properties:
        start:
          $ref: '#/components/schemas/DataRangeMoment'
        end:
          $ref: '#/components/schemas/DataRangeMoment'
    DataRangeResponse:
      type: object
      properties:
        recordType:
          type: string
          example: dataRange
        recordVersion:
          type: string
          example: '3.0'
        userId:
          type: string
        calibrations:
          $ref: '#/components/schemas/DataRangeWindow'
        egvs:
          $ref: '#/components/schemas/DataRangeWindow'
        events:
          $ref: '#/components/schemas/DataRangeWindow'
    GlucoseUnit:
      type: string
      enum:
        - unknown
        - mg/dL
        - mmol/L
    RateUnit:
      type: string
      enum:
        - unknown
        - mg/dL/min
        - mmol/L/min
    TransmitterGeneration:
      type: string
      enum:
        - unknown
        - g4
        - g5
        - g6
        - g6+
        - dexcomPro
        - g7
    TrendType:
      type: string
      enum:
        - none
        - unknown
        - doubleUp
        - singleUp
        - fortyFiveUp
        - flat
        - fortyFiveDown
        - singleDown
        - doubleDown
        - notComputable
        - rateOutOfRange
    EgvStatus:
      type: string
      enum:
        - unknown
        - high
        - low
        - ok
    EGVRecord:
      type: object
      description: A single estimated glucose value record.
      x-schema-source: documentation
      x-source-url: https://developer.dexcom.com/docs/dexcomv3/endpoint-overview
      properties:
        recordId:
          type: string
        systemTime:
          $ref: '#/components/schemas/DateTime'
        displayTime:
          $ref: '#/components/schemas/DateTime'
        transmitterId:
          type: string
          nullable: true
        transmitterTicks:
          type: integer
          format: int64
        value:
          type: integer
          format: int32
          description: Estimated glucose value, in `unit`.
        status:
          $ref: '#/components/schemas/EgvStatus'
        trend:
          $ref: '#/components/schemas/TrendType'
        trendRate:
          type: number
          format: double
          nullable: true
        unit:
          $ref: '#/components/schemas/GlucoseUnit'
        rateUnit:
          $ref: '#/components/schemas/RateUnit'
        displayDevice:
          type: string
          description: One of `iOS`, `android`, or `receiver`.
        transmitterGeneration:
          $ref: '#/components/schemas/TransmitterGeneration'
    EgvsResponse:
      type: object
      properties:
        recordType:
          type: string
          example: egv
        recordVersion:
          type: string
          example: '3.0'
        userId:
          type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/EGVRecord'
    CalibrationRecord:
      type: object
      properties:
        recordId:
          type: string
        systemTime:
          $ref: '#/components/schemas/DateTime'
        displayTime:
          $ref: '#/components/schemas/DateTime'
        unit:
          $ref: '#/components/schemas/GlucoseUnit'
        value:
          type: integer
          format: int32
        displayDevice:
          type: string
        transmitterId:
          type: string
          nullable: true
        transmitterTicks:
          type: integer
          format: int64
        transmitterGeneration:
          $ref: '#/components/schemas/TransmitterGeneration'
    CalibrationsResponse:
      type: object
      properties:
        recordType:
          type: string
          example: calibration
        recordVersion:
          type: string
          example: '3.0'
        userId:
          type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/CalibrationRecord'
    EventType:
      type: string
      enum:
        - unknown
        - carbs
        - insulin
        - exercise
        - health
        - bloodGlucose
        - notes
    EventStatus:
      type: string
      enum:
        - created
        - updated
        - deleted
    EventRecord:
      type: object
      properties:
        recordId:
          type: string
        systemTime:
          $ref: '#/components/schemas/DateTime'
        displayTime:
          $ref: '#/components/schemas/DateTime'
        eventType:
          $ref: '#/components/schemas/EventType'
        eventSubType:
          type: string
          nullable: true
          description: For example `fastActing` or `longActing` for `insulin`, or `light` / `medium` / `heavy` for `exercise`.
        value:
          type: number
          nullable: true
        unit:
          type: string
          nullable: true
          description: Unit appropriate to `eventType` (e.g. `grams`, `units`, `minutes`).
        eventStatus:
          $ref: '#/components/schemas/EventStatus'
        transmitterId:
          type: string
          nullable: true
        transmitterGeneration:
          $ref: '#/components/schemas/TransmitterGeneration'
        displayDevice:
          type: string
          nullable: true
    EventsResponse:
      type: object
      properties:
        recordType:
          type: string
          example: event
        recordVersion:
          type: string
          example: '3.0'
        userId:
          type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/EventRecord'
    AlertName:
      type: string
      enum:
        - unknown
        - high
        - low
        - rise
        - fall
        - outOfRange
        - urgentLow
        - urgentLowSoon
        - noReadings
        - fixedLow
    AlertState:
      type: string
      enum:
        - unknown
        - inactive
        - activeSnoozed
        - activeAlarming
    AlertRecord:
      type: object
      properties:
        recordId:
          type: string
        systemTime:
          $ref: '#/components/schemas/DateTime'
        displayTime:
          $ref: '#/components/schemas/DateTime'
        alertName:
          $ref: '#/components/schemas/AlertName'
        alertState:
          $ref: '#/components/schemas/AlertState'
        displayDevice:
          type: string
        transmitterGeneration:
          $ref: '#/components/schemas/TransmitterGeneration'
        transmitterId:
          type: string
          nullable: true
    AlertsResponse:
      type: object
      properties:
        recordType:
          type: string
          example: alert
        recordVersion:
          type: string
          example: '3.0'
        userId:
          type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/AlertRecord'
    DeviceRecord:
      type: object
      properties:
        lastUploadDate:
          $ref: '#/components/schemas/DateTime'
        transmitterId:
          type: string
          nullable: true
        transmitterGeneration:
          $ref: '#/components/schemas/TransmitterGeneration'
        displayDevice:
          type: string
          description: For example `iOS`, `android`, or `receiver`.
        displayApp:
          type: string
          nullable: true
        alertSchedules:
          type: array
          items:
            $ref: '#/components/schemas/AlertSchedule'
    AlertSchedule:
      type: object
      properties:
        alertScheduleSettings:
          type: object
          properties:
            alertScheduleName:
              type: string
            isEnabled:
              type: boolean
            isDefaultSchedule:
              type: boolean
            startTime:
              type: string
              description: 'Local time of day in `HH:mm` format.'
            endTime:
              type: string
              description: 'Local time of day in `HH:mm` format.'
            daysOfWeek:
              type: array
              items:
                type: string
                enum:
                  - sunday
                  - monday
                  - tuesday
                  - wednesday
                  - thursday
                  - friday
                  - saturday
        alertSettings:
          type: array
          items:
            $ref: '#/components/schemas/AlertSetting'
    AlertSetting:
      type: object
      properties:
        alertName:
          $ref: '#/components/schemas/AlertName'
        value:
          type: number
        unit:
          $ref: '#/components/schemas/GlucoseUnit'
        snooze:
          type: integer
          description: Snooze interval in minutes.
        enabled:
          type: boolean
    DevicesResponse:
      type: object
      properties:
        recordType:
          type: string
          example: device
        recordVersion:
          type: string
          example: '3.0'
        userId:
          type: string
        records:
          type: array
          items:
            $ref: '#/components/schemas/DeviceRecord'