chore: add audit-logs swagger (#12001)

Co-authored-by: Tanmay Sharma <tanmaydeepsharma21@gmail.com>

swagger/definitions/index.yml

@@ -74,6 +74,8 @@ integrations_app:
   $ref: ./resource/integrations/app.yml
 integrations_hook:
   $ref: ./resource/integrations/hook.yml
+audit_log:
+  $ref: ./resource/audit_log.yml
 
 ## public resources
 public_contact:

swagger/definitions/resource/audit_log.yml

@@ -0,0 +1,53 @@
+type: object
+properties:
+  id:
+    type: integer
+    description: Unique identifier for the audit log entry
+  auditable_id:
+    type: integer
+    description: The ID of the audited object
+  auditable_type:
+    type: string
+    description: The type of the audited object (e.g., Conversation, Contact, User)
+  auditable:
+    type: object
+    description: The audited object data
+  associated_id:
+    type: integer
+    description: The ID of the associated object (typically the account ID)
+  associated_type:
+    type: string
+    description: The type of the associated object
+  user_id:
+    type: integer
+    description: The ID of the user who performed the action
+  user_type:
+    type: string
+    description: The type of user who performed the action
+  username:
+    type: string
+    description: The email/username of the user who performed the action
+  action:
+    type: string
+    enum: ['create', 'update', 'destroy']
+    description: The action performed on the object
+  audited_changes:
+    type: object
+    description: JSON object containing the changes made to the audited object
+  version:
+    type: integer
+    description: Version number of the audit log entry
+  comment:
+    type: string
+    nullable: true
+    description: Optional comment associated with the audit log entry
+  request_uuid:
+    type: string
+    description: UUID to identify the request that generated this audit log
+  created_at:
+    type: integer
+    description: Unix timestamp when the audit log entry was created
+  remote_address:
+    type: string
+    nullable: true
+    description: IP address from which the action was performed

swagger/index.yml

@@ -99,7 +99,9 @@ x-tagGroups:
   - name: Application
     tags:
       - Account AgentBots
+      - Account
       - Agents
+      - Audit Logs
       - Canned Responses
       - Contacts
       - Contact Labels

swagger/paths/application/audit_logs/index.yml

@@ -0,0 +1,52 @@
+tags:
+  - Audit Logs
+operationId: get-account-audit-logs
+summary: List Audit Logs in Account
+description: Get Details of Audit Log entries for an Account. This endpoint is only available in Enterprise editions and requires the audit_logs feature to be enabled.
+security:
+  - userApiKey: []
+parameters:
+  - name: page
+    in: query
+    description: Page number for pagination
+    required: false
+    schema:
+      type: integer
+      default: 1
+responses:
+  200:
+    description: Success
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            per_page:
+              type: integer
+              description: Number of items per page
+              example: 15
+            total_entries:
+              type: integer
+              description: Total number of audit log entries
+              example: 150
+            current_page:
+              type: integer
+              description: Current page number
+              example: 1
+            audit_logs:
+              type: array
+              description: Array of audit log entries
+              items:
+                $ref: '#/components/schemas/audit_log'
+  403:
+    description: Access denied
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  422:
+    description: Feature not enabled or not available in current plan
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'

swagger/paths/index.yml

@@ -175,6 +175,13 @@
   patch:
     $ref: ./application/accounts/update.yml
 
+# Audit Logs
+/api/v1/accounts/{account_id}/audit_logs:
+  parameters:
+    - $ref: '#/components/parameters/account_id'
+  get:
+    $ref: ./application/audit_logs/index.yml
+
 # AgentBots
 /api/v1/accounts/{account_id}/agent_bots:
   parameters:

swagger/swagger.json

@@ -1608,6 +1608,94 @@
         }
       }
     },
+    "/api/v1/accounts/{account_id}/audit_logs": {
+      "parameters": [
+        {
+          "$ref": "#/components/parameters/account_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Audit Logs"
+        ],
+        "operationId": "get-account-audit-logs",
+        "summary": "List Audit Logs in Account",
+        "description": "Get Details of Audit Log entries for an Account. This endpoint is only available in Enterprise editions and requires the audit_logs feature to be enabled.",
+        "security": [
+          {
+            "userApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "description": "Page number for pagination",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "per_page": {
+                      "type": "integer",
+                      "description": "Number of items per page",
+                      "example": 15
+                    },
+                    "total_entries": {
+                      "type": "integer",
+                      "description": "Total number of audit log entries",
+                      "example": 150
+                    },
+                    "current_page": {
+                      "type": "integer",
+                      "description": "Current page number",
+                      "example": 1
+                    },
+                    "audit_logs": {
+                      "type": "array",
+                      "description": "Array of audit log entries",
+                      "items": {
+                        "$ref": "#/components/schemas/audit_log"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Access denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Feature not enabled or not available in current plan",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/accounts/{account_id}/agent_bots": {
       "parameters": [
         {
@@ -9177,6 +9265,82 @@
           }
         }
       },
+      "audit_log": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "description": "Unique identifier for the audit log entry"
+          },
+          "auditable_id": {
+            "type": "integer",
+            "description": "The ID of the audited object"
+          },
+          "auditable_type": {
+            "type": "string",
+            "description": "The type of the audited object (e.g., Conversation, Contact, User)"
+          },
+          "auditable": {
+            "type": "object",
+            "description": "The audited object data"
+          },
+          "associated_id": {
+            "type": "integer",
+            "description": "The ID of the associated object (typically the account ID)"
+          },
+          "associated_type": {
+            "type": "string",
+            "description": "The type of the associated object"
+          },
+          "user_id": {
+            "type": "integer",
+            "description": "The ID of the user who performed the action"
+          },
+          "user_type": {
+            "type": "string",
+            "description": "The type of user who performed the action"
+          },
+          "username": {
+            "type": "string",
+            "description": "The email/username of the user who performed the action"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "destroy"
+            ],
+            "description": "The action performed on the object"
+          },
+          "audited_changes": {
+            "type": "object",
+            "description": "JSON object containing the changes made to the audited object"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Version number of the audit log entry"
+          },
+          "comment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Optional comment associated with the audit log entry"
+          },
+          "request_uuid": {
+            "type": "string",
+            "description": "UUID to identify the request that generated this audit log"
+          },
+          "created_at": {
+            "type": "integer",
+            "description": "Unix timestamp when the audit log entry was created"
+          },
+          "remote_address": {
+            "type": "string",
+            "nullable": true,
+            "description": "IP address from which the action was performed"
+          }
+        }
+      },
       "public_contact": {
         "type": "object",
         "properties": {
@@ -12148,7 +12312,9 @@
       "name": "Application",
       "tags": [
         "Account AgentBots",
+        "Account",
         "Agents",
+        "Audit Logs",
         "Canned Responses",
         "Contacts",
         "Contact Labels",

swagger/tag_groups/application_swagger.json

@@ -19,6 +19,226 @@
     }
   ],
   "paths": {
+    "/api/v1/accounts/{id}": {
+      "parameters": [
+        {
+          "$ref": "#/components/parameters/account_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Account"
+        ],
+        "operationId": "get-account-details",
+        "summary": "Get account details",
+        "description": "Get the details of the current account",
+        "security": [
+          {
+            "userApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/account_id"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/account_show_response"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Account not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Account"
+        ],
+        "operationId": "update-account",
+        "summary": "Update account",
+        "description": "Update account details, settings, and custom attributes",
+        "security": [
+          {
+            "userApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/account_id"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/account_update_payload"
+              }
+            },
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "$ref": "#/components/schemas/account_update_payload"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/account_detail"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized (requires administrator role)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Account not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/accounts/{account_id}/audit_logs": {
+      "parameters": [
+        {
+          "$ref": "#/components/parameters/account_id"
+        }
+      ],
+      "get": {
+        "tags": [
+          "Audit Logs"
+        ],
+        "operationId": "get-account-audit-logs",
+        "summary": "List Audit Logs in Account",
+        "description": "Get Details of Audit Log entries for an Account. This endpoint is only available in Enterprise editions and requires the audit_logs feature to be enabled.",
+        "security": [
+          {
+            "userApiKey": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "description": "Page number for pagination",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "default": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "per_page": {
+                      "type": "integer",
+                      "description": "Number of items per page",
+                      "example": 15
+                    },
+                    "total_entries": {
+                      "type": "integer",
+                      "description": "Total number of audit log entries",
+                      "example": 150
+                    },
+                    "current_page": {
+                      "type": "integer",
+                      "description": "Current page number",
+                      "example": 1
+                    },
+                    "audit_logs": {
+                      "type": "array",
+                      "description": "Array of audit log entries",
+                      "items": {
+                        "$ref": "#/components/schemas/audit_log"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Access denied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Feature not enabled or not available in current plan",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/bad_request_error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/v1/accounts/{account_id}/agent_bots": {
       "parameters": [
         {
@@ -7406,6 +7626,82 @@
           }
         }
       },
+      "audit_log": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "description": "Unique identifier for the audit log entry"
+          },
+          "auditable_id": {
+            "type": "integer",
+            "description": "The ID of the audited object"
+          },
+          "auditable_type": {
+            "type": "string",
+            "description": "The type of the audited object (e.g., Conversation, Contact, User)"
+          },
+          "auditable": {
+            "type": "object",
+            "description": "The audited object data"
+          },
+          "associated_id": {
+            "type": "integer",
+            "description": "The ID of the associated object (typically the account ID)"
+          },
+          "associated_type": {
+            "type": "string",
+            "description": "The type of the associated object"
+          },
+          "user_id": {
+            "type": "integer",
+            "description": "The ID of the user who performed the action"
+          },
+          "user_type": {
+            "type": "string",
+            "description": "The type of user who performed the action"
+          },
+          "username": {
+            "type": "string",
+            "description": "The email/username of the user who performed the action"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "destroy"
+            ],
+            "description": "The action performed on the object"
+          },
+          "audited_changes": {
+            "type": "object",
+            "description": "JSON object containing the changes made to the audited object"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Version number of the audit log entry"
+          },
+          "comment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Optional comment associated with the audit log entry"
+          },
+          "request_uuid": {
+            "type": "string",
+            "description": "UUID to identify the request that generated this audit log"
+          },
+          "created_at": {
+            "type": "integer",
+            "description": "Unix timestamp when the audit log entry was created"
+          },
+          "remote_address": {
+            "type": "string",
+            "nullable": true,
+            "description": "IP address from which the action was performed"
+          }
+        }
+      },
       "public_contact": {
         "type": "object",
         "properties": {
@@ -10345,7 +10641,9 @@
       "name": "Application",
       "tags": [
         "Account AgentBots",
+        "Account",
         "Agents",
+        "Audit Logs",
         "Canned Responses",
         "Contacts",
         "Contact Labels",

swagger/tag_groups/client_swagger.json

@@ -2249,6 +2249,82 @@
           }
         }
       },
+      "audit_log": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "description": "Unique identifier for the audit log entry"
+          },
+          "auditable_id": {
+            "type": "integer",
+            "description": "The ID of the audited object"
+          },
+          "auditable_type": {
+            "type": "string",
+            "description": "The type of the audited object (e.g., Conversation, Contact, User)"
+          },
+          "auditable": {
+            "type": "object",
+            "description": "The audited object data"
+          },
+          "associated_id": {
+            "type": "integer",
+            "description": "The ID of the associated object (typically the account ID)"
+          },
+          "associated_type": {
+            "type": "string",
+            "description": "The type of the associated object"
+          },
+          "user_id": {
+            "type": "integer",
+            "description": "The ID of the user who performed the action"
+          },
+          "user_type": {
+            "type": "string",
+            "description": "The type of user who performed the action"
+          },
+          "username": {
+            "type": "string",
+            "description": "The email/username of the user who performed the action"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "destroy"
+            ],
+            "description": "The action performed on the object"
+          },
+          "audited_changes": {
+            "type": "object",
+            "description": "JSON object containing the changes made to the audited object"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Version number of the audit log entry"
+          },
+          "comment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Optional comment associated with the audit log entry"
+          },
+          "request_uuid": {
+            "type": "string",
+            "description": "UUID to identify the request that generated this audit log"
+          },
+          "created_at": {
+            "type": "integer",
+            "description": "Unix timestamp when the audit log entry was created"
+          },
+          "remote_address": {
+            "type": "string",
+            "nullable": true,
+            "description": "IP address from which the action was performed"
+          }
+        }
+      },
       "public_contact": {
         "type": "object",
         "properties": {
@@ -5124,7 +5200,9 @@
       "name": "Application",
       "tags": [
         "Account AgentBots",
+        "Account",
         "Agents",
+        "Audit Logs",
         "Canned Responses",
         "Contacts",
         "Contact Labels",

swagger/tag_groups/other_swagger.json

@@ -1664,6 +1664,82 @@
           }
         }
       },
+      "audit_log": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "description": "Unique identifier for the audit log entry"
+          },
+          "auditable_id": {
+            "type": "integer",
+            "description": "The ID of the audited object"
+          },
+          "auditable_type": {
+            "type": "string",
+            "description": "The type of the audited object (e.g., Conversation, Contact, User)"
+          },
+          "auditable": {
+            "type": "object",
+            "description": "The audited object data"
+          },
+          "associated_id": {
+            "type": "integer",
+            "description": "The ID of the associated object (typically the account ID)"
+          },
+          "associated_type": {
+            "type": "string",
+            "description": "The type of the associated object"
+          },
+          "user_id": {
+            "type": "integer",
+            "description": "The ID of the user who performed the action"
+          },
+          "user_type": {
+            "type": "string",
+            "description": "The type of user who performed the action"
+          },
+          "username": {
+            "type": "string",
+            "description": "The email/username of the user who performed the action"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "destroy"
+            ],
+            "description": "The action performed on the object"
+          },
+          "audited_changes": {
+            "type": "object",
+            "description": "JSON object containing the changes made to the audited object"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Version number of the audit log entry"
+          },
+          "comment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Optional comment associated with the audit log entry"
+          },
+          "request_uuid": {
+            "type": "string",
+            "description": "UUID to identify the request that generated this audit log"
+          },
+          "created_at": {
+            "type": "integer",
+            "description": "Unix timestamp when the audit log entry was created"
+          },
+          "remote_address": {
+            "type": "string",
+            "nullable": true,
+            "description": "IP address from which the action was performed"
+          }
+        }
+      },
       "public_contact": {
         "type": "object",
         "properties": {
@@ -4531,7 +4607,9 @@
       "name": "Application",
       "tags": [
         "Account AgentBots",
+        "Account",
         "Agents",
+        "Audit Logs",
         "Canned Responses",
         "Contacts",
         "Contact Labels",

swagger/tag_groups/platform_swagger.json

@@ -2425,6 +2425,82 @@
           }
         }
       },
+      "audit_log": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "description": "Unique identifier for the audit log entry"
+          },
+          "auditable_id": {
+            "type": "integer",
+            "description": "The ID of the audited object"
+          },
+          "auditable_type": {
+            "type": "string",
+            "description": "The type of the audited object (e.g., Conversation, Contact, User)"
+          },
+          "auditable": {
+            "type": "object",
+            "description": "The audited object data"
+          },
+          "associated_id": {
+            "type": "integer",
+            "description": "The ID of the associated object (typically the account ID)"
+          },
+          "associated_type": {
+            "type": "string",
+            "description": "The type of the associated object"
+          },
+          "user_id": {
+            "type": "integer",
+            "description": "The ID of the user who performed the action"
+          },
+          "user_type": {
+            "type": "string",
+            "description": "The type of user who performed the action"
+          },
+          "username": {
+            "type": "string",
+            "description": "The email/username of the user who performed the action"
+          },
+          "action": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "destroy"
+            ],
+            "description": "The action performed on the object"
+          },
+          "audited_changes": {
+            "type": "object",
+            "description": "JSON object containing the changes made to the audited object"
+          },
+          "version": {
+            "type": "integer",
+            "description": "Version number of the audit log entry"
+          },
+          "comment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Optional comment associated with the audit log entry"
+          },
+          "request_uuid": {
+            "type": "string",
+            "description": "UUID to identify the request that generated this audit log"
+          },
+          "created_at": {
+            "type": "integer",
+            "description": "Unix timestamp when the audit log entry was created"
+          },
+          "remote_address": {
+            "type": "string",
+            "nullable": true,
+            "description": "IP address from which the action was performed"
+          }
+        }
+      },
       "public_contact": {
         "type": "object",
         "properties": {
@@ -5304,7 +5380,9 @@
       "name": "Application",
       "tags": [
         "Account AgentBots",
+        "Account",
         "Agents",
+        "Audit Logs",
         "Canned Responses",
         "Contacts",
         "Contact Labels",