API.yaml

openapi: 3.0.1
info:
  title: Immuni API
  version: 1.0.0
servers:
- url: /v1
tags:
- name: App Configuration
  description: |-
    The App can be partially customised through the Configuration Settings
    downloaded at the App startup and updated every time the App starts a session,
    whether in the foreground or background. For example, these include information
    such as the weights to be used by the Mobile Client in the calculation of the
    Total Risk Score.
- name: OTP
  description: |-
    The OTP Service provides an API to the National Healthcare Service
    for authorising OTPs that can be used to upload data from the Mobile Client via
    the Exposure Ingestion Service. The OTP is generated by the App and communicated
    by the user to the Healthcare Operator (e.g., during a phone call). The Healthcare
    Operator inserts the OTP into the HIS, which then registers the OTP on the OTP
    Service. The OTP automatically expires after a defined interval. If the data have
    not been uploaded by the time the OTP expires, the user will have to restart the
    process with a new OTP.
- name: Exposure Ingestion
  description: |-
    The Exposure Ingestion Service provides an API for the Mobile Client
    to upload its TEKs for the previous 14 days, in the case that the user tests positive
    for SARS-CoV-2 and decides to share them. Contextually, the Mobile Client uploads
    the Epidemiological Infos from the previous 14 days, if any. If some Epidemiological
    Infos are indeed uploaded, the user's Province of Domicile is uploaded too. The
    upload can only take place with an authorised OTP. The Exposure Ingestion Service
    is also responsible for periodically generating the TEK Chunks to be published
    by the Exposure Reporting Service. The TEK Chunks are assigned a unique incremental
    index and are immutable. They are generated periodically as the Mobile Clients
    upload new TEKs. TEK Chunks older than 14 days are automatically deleted from
    the database by an async cleanup job. Province of Domicile and Epidemiological
    Infos are forwarded to the Analytics Service.
- name: Exposure Reporting
  description: |-
    The Exposure Reporting Service makes the TEK Chunks created by the
    Exposure Ingestion Service available to the Mobile Client. Only TEK Chunks for
    the last 14 days are made available. To avoid downloading the same TEKs multiple
    times, the Mobile Clients fetch the indexes of the TEK Chunks available to download
    first. Then, they only actually download TEK Chunks with indexes for which TEK
    Chunks have not been downloaded before.
- name: Analytics
  description: |-
    The Analytics Service provides an API to the Mobile Clients for uploading
    certain data without identifying users, both during regular operations and especially
    when a match is found between a TEK Chunk and the RPIs in the RPI Database. Collecting
    these data is crucial to spotting anomalies in the system, as well as being able
    to check how many users are being notified. The National Healthcare System needs
    this information to operate Immuni effectively.
paths:
  /settings:
    get:
      tags:
      - App Configuration
      summary: >-
        The Mobile Client fetches the Configuration Settings. Different Configuration
        Settings may be made available for different platforms (i.e., iOS and Android)
        and App build numbers.
      parameters:
      - name: platform
        in: query
        description: The Mobile Client's platform.
        required: true
        schema:
          type: string
          enum:
          - ios
          - android
      - name: build
        in: query
        description: The App's build number.
        required: true
        schema:
          minimum: 1
          type: integer
          format: int32
      responses:
        "200":
          description: A JSON-formatted dictionary. Specifications are being worked
            out.
          headers:
            Cache-Control:
              description: Directives for caching the response. The Configuration
                Settings are cached for 60 minutes.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        "400":
          description: Invalid request.
          content: {}
  /otp:
    post:
      tags:
      - OTP
      summary: >-
        The provided OTP authorises the upload of the Mobile Client's TEKs.
        This API will not be publicly exposed, to prevent unauthorised users from
        reaching it. Authentication for having the OTP Service and the HIS trust each
        other is configured at the infrastructure level. The payload also contains
        the start date of the symptoms, so that the Exposure Ingestion Service can
        compute the Transmission Risk for each uploaded TEK.
      requestBody:
        description: A JSON-formatted dictionary containing the OTP and the start
          date of the symptoms.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OTPUpload'
        required: true
      responses:
        "204":
          description: Operation completed successfully.
          headers:
            Cache-Control:
              description: Directives to prevent caching of 204 responses.
              schema:
                type: string
          content: {}
        "400":
          description: Invalid data. An APIError is returned. Possible error codes
            are 1400 ("Unexpected empty body") and 1401 ("Body not compliant with
            the defined schema").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-codegen-request-body-name: body
  /ingestion/check-otp:
    post:
      tags:
      - Exposure Ingestion
      summary: >-
        The Mobile Client validates the OTP prior to uploading data. The request
        is authenticated with the OTP to be validated. Using the dedicated request
        header, the Mobile Client can indicate to the server that the call it is making
        is a dummy one. The server will ignore the content of such calls.
      parameters:
      - $ref: '#/components/parameters/Immuni-Dummy-Data'
      requestBody:
        description: A JSON-formatted dictionary containing a padding field to emulate
          the upload request payload size.
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/CheckOTP'
        required: true
      responses:
        "204":
          description: Operation completed successfully.
          headers:
            Cache-Control:
              description: Directives to prevent caching of 204 responses.
              schema:
                type: string
          content: {}
        "400":
          description: Invalid data. An APIError is returned. The only possible error
            code is 1100 ("Missing required input parameters").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: 'Unauthorised request: invalid OTP.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'

      security:
      - otp_bearer: []
      x-codegen-request-body-name: body
  /ingestion/upload:
    post:
      tags:
      - Exposure Ingestion
      summary: >-
        Once it has validated the OTP, the Mobile Client uploads its TEKs for
        the past 14 days, together with the user’s Province of Domicile. If any Epidemiological
        Infos from the previous 14 days are available, the Mobile Client uploads those
        too. The timestamp that accompanies each TEK is referred to the Mobile Client’s
        system time. For this reason, the Mobile Client informs the Exposure Ingestion
        Service about its system time so that a skew can be corrected. Using the dedicated
        request header, the Mobile Client can indicate to the server that the call
        it is making is a dummy one. The server will ignore the content of such calls.
      parameters:
      - name: Immuni-Client-Clock
        in: header
        required: true
        schema:
          type: integer
          format: int32
      - $ref: '#/components/parameters/Immuni-Dummy-Data'
      requestBody:
        description: |-
          A JSON-formatted dictionary containing the data to upload. The
          server will ignore transmission_risk_level, which is to be overridden as
          a result of server-side computations.
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/Upload'
        required: true
      responses:
        "204":
          description: Operation completed successfully.
          headers:
            Cache-Control:
              description: Directives to prevent caching of 204 responses.
              schema:
                type: string
          content: {}
        "400":
          description: |-
            Invalid data. An APIError is returned. The only possible error
            code is 1100 ("Missing required input parameters").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: 'Unauthorised request: invalid OTP.'
          content: {}
      security:
      - otp_bearer: []
      x-codegen-request-body-name: body
  /keys/index:
    get:
      tags:
      - Exposure Reporting
      summary: >-
        Return the index of the oldest relevant TEK Chunk (no older than 14
        days) and the index of the newest available TEK Chunk. It is up to the Mobile
        Client not to download the same TEK Chunk more than once.
      responses:
        "200":
          description: Operation completed successfully.
          headers:
            Cache-Control:
              description: Directives for caching the response. The indexes are cached
                for 30 minutes.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TEKChunkIndexes'
        "404":
          description: No TEK Chunks found.
          content: {}
  /keys/{TEKChunkIndex}:
    get:
      tags:
      - Exposure Reporting
      summary: >-
        Given a specific TEK Chunk index, the Mobile Client downloads the associated
        TEK Chunk from the Exposure Reporting Service.
      parameters:
      - name: TEKChunkIndex
        in: path
        description: The TEK Chunk's incremental number.
        required: true
        schema:
          minimum: 1
          type: integer
          format: int32
      responses:
        "200":
          description: Operation completed successfully.
          headers:
            Cache-Control:
              description: Directives for caching the response. TEK Chunks are cached
                for 15 days.
              schema:
                type: string
          content: {}
        "404":
          description: TEK Chunk not found.
          content: {}
  /analytics/apple/operational-info:
    post:
      tags:
      - Analytics
      summary: Save the operational data sent by the iOS device, in compliance with
        the monthly policy, authorized with the provided analytics token.
      parameters:
      - $ref: '#/components/parameters/Immuni-Dummy-Data'
      requestBody:
        description: A JSON-formatted dictionary containing the operational data.
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/OperationalInfo'
        required: true
      responses:
        "204":
          description: Operation completed successfully.
          headers:
            Cache-Control:
              description: Directives to prevent caching of 204 responses.
              schema:
                type: string
          content: {}
        "400":
          description: Invalid data. An APIError is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - analytics_bearer: []
      x-codegen-request-body-name: body
  /analytics/google/operational-info:
    post:
      tags:
      - Analytics
      summary: >-
        Save the operational data sent by the Android device, authorized with
        the provided SafetyNet hardware attestation token.
      parameters:
      - $ref: '#/components/parameters/Immuni-Dummy-Data'
      requestBody:
        description: A JSON-formatted dictionary containing the operational data.
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/GoogleOperationalInfo'
        required: true
      responses:
        "204":
          description: Operation completed successfully.
          headers:
            Cache-Control:
              description: Directives to prevent caching of 204 responses.
              schema:
                type: string
          content: {}
        "400":
          description: Invalid data. An APIError is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-codegen-request-body-name: body
  /analytics/apple/token:
    post:
      tags:
      - Analytics
      summary: >-
        Authorize the provided analytics token with the device authenticity
        SDK offered by the device operating system.
      requestBody:
        description: A JSON-formatted dictionary containing the tokens.
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/AnalyticsToken'
        required: true
      responses:
        "201":
          description: Token is authorized. No response body returned.
          content: {}
        "202":
          description: Token authorization in progress. No response body returned.
          content: {}
        "400":
          description: Invalid data. An APIError is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-codegen-request-body-name: body
components:
  parameters:
    Immuni-Dummy-Data:
      name: Immuni-Dummy-Data
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/Flag'

  schemas:
    Flag:
      maximum: 1
      minimum: 0
      type: integer
      format: int32
      example: 1
    OTPUpload:
      required:
      - otp
      - symptoms_started_on
      type: object
      properties:
        otp:
          pattern: ^[AEFHIJKLQRSUWXYZ1-9]{10}$
          type: string
          example: 9K2RAY8UUQ
        symptoms_started_on:
          type: string
          format: date
    Upload:
      type: object
      properties:
        teks:
          maxItems: 14
          type: array
          items:
            $ref: '#/components/schemas/TEK'
        province:
          pattern: ^[A-Z]{2}$
          type: string
          example: MB
        padding:
          pattern: ^[a-zA-Z0-9]*$
          type: string
        exposure_detection_summaries:
          type: array
          items:
            $ref: '#/components/schemas/ExposureDetectionSummary'
    TEK:
      required:
      - key_data
      - rolling_period
      - rolling_start_number
      type: object
      properties:
        key_data:
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
          example: utdH33iMRTapATp7iK3hdA==
        rolling_start_number:
          minimum: 0
          type: integer
          format: int32
          example: 2648160
        rolling_period:
          minimum: 0
          type: integer
          format: int32
          example: 144
    TEKChunkIndexes:
      required:
      - newest
      - oldest
      type: object
      properties:
        oldest:
          minimum: 1
          type: integer
          format: int32
          example: 1
        newest:
          minimum: 1
          type: integer
          format: int32
          example: 14
    ExposureDetectionSummary:
      required:
      - attenuation_durations
      - date
      - days_since_last_exposure
      - matched_key_count
      - maximum_risk_score
      type: object
      properties:
        date:
          type: string
          format: date
        matched_key_count:
          minimum: 1
          type: integer
          format: int32
          example: 2
        days_since_last_exposure:
          maximum: 14
          type: integer
          format: int32
          example: 1
        attenuation_durations:
          maxItems: 3
          minItems: 3
          type: array
          example:
          - 300
          - 0
          - 0
          items:
            minimum: 0
            type: integer
            format: int32
        maximum_risk_score:
          maximum: 4096
          minimum: 0
          type: integer
          format: int32
          example: 4
        exposure_info:
          type: array
          items:
            $ref: '#/components/schemas/ExposureInfo'
    CheckOTP:
      required:
      - padding
      type: object
      properties:
        padding:
          pattern: ^[a-zA-Z0-9]*$
          type: string
    ExposureInfo:
      required:
      - attenuation_durations
      - attenuation_value
      - date
      - duration
      - total_risk_score
      - transmission_risk_level
      type: object
      properties:
        date:
          type: string
          format: date
        duration:
          maximum: 1.8E+3
          minimum: 0
          type: integer
          format: int32
          example: 5
        attenuation_value:
          maximum: 255
          minimum: 0
          type: integer
          format: int32
          example: 45
        attenuation_durations:
          maxItems: 3
          minItems: 3
          type: array
          example:
          - 300
          - 0
          - 0
          items:
            minimum: 0
            type: integer
            format: int32
        transmission_risk_level:
          maximum: 8
          minimum: 0
          type: integer
          format: int32
          example: 1
        total_risk_score:
          maximum: 4096
          minimum: 0
          type: integer
          format: int32
          example: 4
    OperationalInfo:
      required:
      - bluetooth_active
      - exposure_notification
      - exposure_permission
      - last_risky_exposure_on
      - notification_permission
      - province
      type: object
      properties:
        province:
          pattern: ^[A-Z]{2}$
          type: string
          example: MB
        exposure_permission:
          $ref: '#/components/schemas/Flag'
        bluetooth_active:
          $ref: '#/components/schemas/Flag'
        notification_permission:
          $ref: '#/components/schemas/Flag'
        exposure_notification:
          $ref: '#/components/schemas/Flag'
        last_risky_exposure_on:
          type: string
          format: date
    GoogleOperationalInfo:
      allOf:
      - $ref: '#/components/schemas/OperationalInfo'
      - required:
        - salt
        - signed_attestation
        type: object
        properties:
          salt:
            maxLength: 24
            pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
            type: string
            format: byte
            example: T84OSRnLtbRRtUgYQM5wLw==
          signed_attestation:
            maxLength: 10000
            type: string
    AnalyticsToken:
      required:
      - analytics_token
      - device_token
      type: object
      properties:
        analytics_token:
          pattern: ^[a-f0-9]{128}$
          type: string
        device_token:
          maxLength: 10000
          pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
          type: string
          format: byte
    APIError:
      required:
      - error_code
      - message
      type: object
      properties:
        error_code:
          minimum: 0
          type: integer
          format: int32
          example: 1400
        message:
          pattern: ^[A-Za-z0-9 .]{1,64}$
          type: string
          example: Unexpected empty body.
  securitySchemes:
    otp_bearer:
      type: apiKey
      name: Authorization
      in: header
    analytics_bearer:
      type: apiKey
      name: Authorization
      in: header