openapi.yaml

---
info:
  title: Kener API
  version: 3.0.0
  description: |
    # Kener Selfhost node js status page
    ![Kener](https://kener.ing/newbg.png "kener")
    API specification for Kener status page and incident management system. This API spec was created using [Frogment](https://www.frogment.app)
  contact:
    name: Raj Nandan Sharma
    email: rajnandan1@gmail.com
    url: https://github.com/rajnandan1/kener/issues
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
openapi: 3.0.0
servers:
- url: https://{host}
  description: Kener host URL
tags:
- name: Monitors
  description: APIs to interact with monitors
- name: Incidents
  description: APIs to integrate incidents
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: enter your api key here
  schemas:
    MonitorStatus:
      type: object
      description: Monitor Status
      required:
      - status
      - latency
      - tag
      properties:
        status:
          type: string
          example: UP
          enum:
          - UP
          - DOWN
          - DEGRADED
        latency:
          type: number
          description: In seconds
          example: 100
        timestampInSeconds:
          type: integer
          description: UTC timestamp in seconds
          example: 1731251760
        tag:
          type: string
          example: earth
          description: Tag of a monitor
      example:
        status: UP
        timestampInSeconds: 1731251760
        latency: 100
        tag: earth
    StatusResponse:
      type: object
      description: Status of a monitor given a tag
      properties:
        status:
          type: string
          example: UP
          enum:
          - UP
          - DOWN
          - DEGRADED
        uptime:
          type: string
          example: '100'
        last_updated_at:
          type: integer
          example: 1731251760
      example:
        status: UP
        last_updated_at: 1731251760
        uptime: '100'
    Incident:
      type: object
      description: body of an incident
      properties:
        start_date_time:
          type: integer
          description: UTC timestamp in seconds
          example: 1731901920
        end_date_time:
          type: integer
          description: UTC timestamp in seconds
          nullable: true
          example: 1704123938
        title:
          type: string
          example: Outage in mumbai
          description: title of the incident
        created_at:
          type: string
          example: '2025-01-09 04:12:01'
          description: created at time
        updated_at:
          type: string
          example: '2025-01-09 06:10:00'
          description: updated at time
        status:
          type: string
          example: OPEN
          description: delete or not deleted incident
          enum:
          - OPEN
          - CLOSED
        state:
          type: string
          description: the current status of the incident
          example: INVESTIGATING
          enum:
          - INVESTIGATING
          - IDENTIFIED
          - MONITORING
          - RESOLVED
      example:
        start_date_time: 1731901920
        end_date_time: 1704123938
        title: title of the incident
        created_at: '2025-01-09 04:12:01'
        updated_at: '2025-01-09 04:12:01'
        state: INVESTIGATING
        status: OPEN
        id: 4
    IncidentResponse:
      description: Incident response schema
      allOf:
      - "$ref": "#/components/schemas/Incident"
    Comment:
      type: object
      description: Comment of an incident
      properties:
        comment:
          type: string
          example: comment 1
        commented_at:
          type: integer
          example: 1736398336
        state:
          type: string
          example: IDENTIFIED
      example:
        body: comment 2
        commented_at: 1736398336
        state: IDENTIFIED
    CommentResponse:
      type: object
      description: Comment Response
      properties:
        id:
          type: integer
          description: ID of the comment
          example: 60
        comment:
          type: string
          description: The content of the comment
          example: Sometimes, you want all the goodness of moment#from but you don't
            want to have to create two moments, you just want to display a length
            of time.
        incident_id:
          type: integer
          description: ID of the associated incident
          example: 24
        commented_at:
          type: integer
          description: Timestamp when the comment was added
          example: 1736398336
        created_at:
          type: string
          format: date-time
          description: Timestamp when the comment was created in ISO 8601 format
          example: '2025-01-09 04:52:16'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the comment was last updated in ISO 8601 format
          example: '2025-01-09 04:52:16'
        status:
          type: string
          description: Current status of the comment
          example: ACTIVE
        state:
          type: string
          description: the current status of the incident
          example: INVESTIGATING
          enum:
          - INVESTIGATING
          - IDENTIFIED
          - MONITORING
          - RESOLVED
      example:
        id: 60
        comment: Sometimes, you want all the goodness of moment
        incident_id: 24
        commented_at: 1736398336
        created_at: '2025-01-09 04:52:16'
        updated_at: '2025-01-09 04:52:16'
        status: ACTIVE
        state: MONITORING
    IncidentStatus:
      type: object
      description: Status of the incident
      properties:
        isIdentified:
          type: boolean
          description: Has the incident been indetified
          example: true
        isResolved:
          type: boolean
          description: has the incident been resolved
          example: true
        endDatetime:
          type: integer
          description: Incident end time
          example: 1731901920
      example:
        isIdentified: true
        isResolved: true
        endDatetime: 1731901920
    IncidentCreateRequest:
      title: Incident Create Request Body
      type: object
      description: body of an incident
      required:
      - title
      - start_date_time
      properties:
        start_date_time:
          type: integer
          description: UTC timestamp in seconds
          example: 1731901920
        title:
          type: string
          example: Outage in mumbai
          description: title of the incident
      example:
        start_date_time: 1731901920
        title: title of the incident
  responses:
    Response401:
      description: Bad API keys response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Invalid token response
                example: invalid token
          example:
            error: invalid token
    Response400:
      description: bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: bad request while calling kener apis
                example: unknown tags
          example:
            error: unknown tags
  examples:
    GetMonitorStatusExample200:
      summary: response of get status of a monitor
      description: Some Description
      value:
        status: UP
        uptime: '100'
        lastUpdatedAt: 1731901920
    DegradedRequestBody:
      summary: update to degraded
      description: Some Description
      value:
        status: DEGRADED
        timestampInSeconds: 1731251760
        latency: 100
        tag: earth
    CreateIncidentResponse:
      summary: create incident response
      description: create incident response
      value:
        start_date_time: 1731901920
        end_date_time: 1731901920
        id: 4
        created_at: '2025-01-09 04:12:01'
        updated_at: '2025-01-10 04:12:01'
        title: title of the incident
        status: OPEN
        state: INVESTIGATING
    CreateIncidentRequest:
      summary: create incident request body
      description: create incident request body
      value:
        start_date_time: 1731901920
        title: title of the incident
    SearchIncidentsResponse:
      summary: array of incidents
      description: Some Description
      value:
      - id: 2
        title: future wala
        start_date_time: 1736774486
        end_date_time: 1737033787
        created_at: '2025-01-12 13:21:32'
        updated_at: '2025-01-12 13:23:15'
        status: OPEN
        state: RESOLVED
      - id: 1
        title: internatiinal asda
        start_date_time: 1736684329
        end_date_time: 
        created_at: '2025-01-12 12:18:53'
        updated_at: '2025-01-12 13:21:32'
        status: OPEN
        state: INVESTIGATING
    CommentsResponse:
      summary: list of comments
      description: Some Description
      value:
      - id: 58
        comment: idensad
        incident_id: 24
        commented_at: 1736398295
        created_at: '2025-01-09 04:51:37'
        updated_at: '2025-01-09 04:51:37'
        status: ACTIVE
        state: IDENTIFIED
      - id: 57
        comment: Sometimes, you want all the goodness of moment#from but you don't
          want to have to create two moments, you just want to display a length of
          time.
        incident_id: 24
        commented_at: 1736398279
        created_at: '2025-01-09 04:51:19'
        updated_at: '2025-01-09 04:51:19'
        status: ACTIVE
        state: INVESTIGATING
    CommentRequestBody:
      summary: request body for a update
      description: request body for a update to add in an incident
      value:
        comment: This is a comment
        commented_at: 1736398336
        state: IDENTIFIED
    CreateCommentResponse:
      summary: create update response body sample
      description: create update response body sample
      value:
        id: 60
        comment: Sometimes, you want all the goodness of moment
        incident_id: 24
        commented_at: 1736398336
        created_at: '2025-01-09 04:52:16'
        updated_at: '2025-01-09 04:52:16'
        status: ACTIVE
        state: MONITORING
paths:
  "/api/status":
    post:
      operationId: updateMonitorStatus
      summary: Update status of a monitor
      description: Update status of a monitor at a given timestamp UTC
      tags:
      - Monitors
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: request body to update status of a monitor
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/MonitorStatus"
            examples:
              degraded:
                "$ref": "#/components/examples/DegradedRequestBody"
      responses:
        '200':
          description: Status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: success at 1731251760
              example:
                status: 200
                message: success at 1731251760
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
    get:
      operationId: getMonitorStatus
      summary: Get status of a monitor
      description: get status of a monitor at timestamp
      tags:
      - Monitors
      security:
      - bearerAuth: []
      parameters:
      - name: tag
        in: query
        required: true
        description: monitor tag to get status of it
        schema:
          type: string
          example: earth
      responses:
        '200':
          description: Monitor status retrieved successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/StatusResponse"
              examples:
                successExample:
                  "$ref": "#/components/examples/GetMonitorStatusExample200"
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
  "/api/incident":
    post:
      operationId: createIncident
      summary: Create a new incident
      description: API to create incidents
      tags:
      - Incidents
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: request body to manually create an incident
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/IncidentCreateRequest"
            examples:
              sample:
                "$ref": "#/components/examples/CreateIncidentRequest"
      responses:
        '200':
          description: Incident created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/IncidentResponse"
              examples:
                success:
                  "$ref": "#/components/examples/CreateIncidentResponse"
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
    get:
      operationId: searchIncidents
      summary: Search for incidents
      description: API to get incidents
      tags:
      - Incidents
      security:
      - bearerAuth: []
      parameters:
      - name: status
        in: query
        description: status of the incident. Can be open or close. close means deleted
        schema:
          type: string
          description: status of the incident. Can be open or close. close means deleted
          enum:
          - OPEN
          - CLOSED
          default: OPEN
          example: OPEN
      - name: state
        in: query
        description: state of the incident. Can be open or close
        schema:
          type: string
          description: state of the incident. Can be open or close
          enum:
          - INVESTIGATING
          - IDENTIFIED
          - MONITORING
          - RESOLVED
          default: INVESTIGATING
          example: IDENTIFIED
      - name: page
        in: query
        description: page number
        schema:
          type: integer
          description: page number
          default: 1
          minimum: 1
          example: 1
      - name: limit
        in: query
        description: how many per page
        schema:
          type: integer
          default: 10
          description: how many per page
          maximum: 100
          example: 10
      - name: start_date_time
        description: start time
        in: query
        schema:
          type: integer
          description: start time
          example: 1731866475
      - name: end_date_time
        description: end time
        in: query
        schema:
          type: integer
          description: end time
          example: 1731866475
      responses:
        '200':
          description: Search results retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/IncidentResponse"
              examples:
                success:
                  "$ref": "#/components/examples/SearchIncidentsResponse"
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
  "/api/incident/{incident_id}":
    parameters:
    - name: incident_id
      in: path
      required: true
      description: incident id as an integer to get incident by id
      schema:
        type: integer
        example: 4
    get:
      operationId: getIncident
      summary: Get an incident by id
      description: API to get an incident by incident id
      tags:
      - Incidents
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Incident retrieved successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/IncidentResponse"
              examples:
                success:
                  "$ref": "#/components/examples/CreateIncidentResponse"
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
    patch:
      operationId: updateIncident
      summary: Update an incident
      description: API to update an incident by incident id
      tags:
      - Incidents
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: search for an incident
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Incident"
            examples:
              sample:
                "$ref": "#/components/examples/CreateIncidentRequest"
      responses:
        '200':
          description: Incident updated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/IncidentResponse"
              examples:
                success:
                  "$ref": "#/components/examples/CreateIncidentResponse"
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
  "/api/incident/{incident_id}/updates":
    parameters:
    - name: incident_id
      in: path
      required: true
      description: incident id to fetch comment for
      schema:
        type: integer
        example: 4
    post:
      operationId: addIncidentComment
      summary: Add an update to an incident
      description: API to create update for an incident
      tags:
      - Incidents
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: body to add an update
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Comment"
            examples:
              sample:
                "$ref": "#/components/examples/CommentRequestBody"
      responses:
        '200':
          description: Comment added successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CommentResponse"
              examples:
                sample:
                  "$ref": "#/components/examples/CreateCommentResponse"
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
    get:
      operationId: getIncidentComments
      summary: Get updates for an incident
      description: API to get updates for an incident
      tags:
      - Incidents
      security:
      - bearerAuth: []
      responses:
        '200':
          description: updates retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/CommentResponse"
              examples:
                success:
                  "$ref": "#/components/examples/CommentsResponse"
        '400':
          "$ref": "#/components/responses/Response400"
        '401':
          "$ref": "#/components/responses/Response401"
  "/api/incident/{incident_id}/monitors":
    parameters:
    - name: incident_id
      in: path
      required: true
      description: incident id to fetch comment for
      schema:
        type: integer
        example: 4
    get:
      summary: Get monitors for an incident
      operationId: getIncidentMonitors
      tags:
      - Incidents
      parameters:
      - name: incident_id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the incident
      responses:
        '200':
          description: List of monitors for the incident
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    monitor_tag:
                      type: string
                      description: The tag of the monitor
                      example: earth
                    monitor_impact:
                      type: string
                      description: The impact status of the monitor
                      example: DOWN
      security:
      - bearerAuth: []
    post:
      summary: Add a monitor to an incident
      operationId: addIncidentMonitor
      tags:
      - Incidents
      parameters:
      - name: incident_id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the incident
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tag:
                  type: string
                  description: The tag for the monitor
                  example: okbookmarks
                impact:
                  type: string
                  description: The impact status of the monitor
                  example: DEGRADED
      responses:
        '200':
          description: Monitor added successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    monitor_tag:
                      type: string
                      description: The tag of the monitor
                      example: okbookmarks
                    monitor_impact:
                      type: string
                      description: The impact status of the monitor
                      example: DEGRADED
      security:
      - bearerAuth: []
    delete:
      summary: Delete a monitor from an incident
      operationId: deleteIncidentMonitor
      tags:
      - Incidents
      parameters:
      - name: incident_id
        in: path
        required: true
        schema:
          type: integer
        description: The ID of the incident
      - name: tag
        in: query
        required: true
        schema:
          type: string
        description: The tag of the monitor to delete
      responses:
        '200':
          description: Monitor deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Confirmation message
                    example: Monitor deleted successfully
      security:
      - bearerAuth: []