From 94b715492697d7c71090e584b94d81682c2c005b Mon Sep 17 00:00:00 2001 From: Shivam Mishra Date: Tue, 22 Jul 2025 15:12:31 +0530 Subject: [PATCH] chore: add audit-logs swagger (#12001) Co-authored-by: Tanmay Sharma --- swagger/definitions/index.yml | 2 + swagger/definitions/resource/audit_log.yml | 53 ++++ swagger/index.yml | 2 + .../paths/application/audit_logs/index.yml | 52 +++ swagger/paths/index.yml | 7 + swagger/swagger.json | 166 ++++++++++ swagger/tag_groups/application_swagger.json | 298 ++++++++++++++++++ swagger/tag_groups/client_swagger.json | 78 +++++ swagger/tag_groups/other_swagger.json | 78 +++++ swagger/tag_groups/platform_swagger.json | 78 +++++ 10 files changed, 814 insertions(+) create mode 100644 swagger/definitions/resource/audit_log.yml create mode 100644 swagger/paths/application/audit_logs/index.yml diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index faf947217..b244deb7f 100644 --- a/swagger/definitions/index.yml +++ b/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: diff --git a/swagger/definitions/resource/audit_log.yml b/swagger/definitions/resource/audit_log.yml new file mode 100644 index 000000000..9dfa63263 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/swagger/index.yml b/swagger/index.yml index e27425d41..dd460d111 100644 --- a/swagger/index.yml +++ b/swagger/index.yml @@ -99,7 +99,9 @@ x-tagGroups: - name: Application tags: - Account AgentBots + - Account - Agents + - Audit Logs - Canned Responses - Contacts - Contact Labels diff --git a/swagger/paths/application/audit_logs/index.yml b/swagger/paths/application/audit_logs/index.yml new file mode 100644 index 000000000..8fcd22256 --- /dev/null +++ b/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' \ No newline at end of file diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index a70800b89..b2fcb4594 100644 --- a/swagger/paths/index.yml +++ b/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: diff --git a/swagger/swagger.json b/swagger/swagger.json index b9ecbcf27..e849f8119 100644 --- a/swagger/swagger.json +++ b/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", diff --git a/swagger/tag_groups/application_swagger.json b/swagger/tag_groups/application_swagger.json index 2a8162358..f06819d1d 100644 --- a/swagger/tag_groups/application_swagger.json +++ b/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", diff --git a/swagger/tag_groups/client_swagger.json b/swagger/tag_groups/client_swagger.json index cefc39324..c6a3ba408 100644 --- a/swagger/tag_groups/client_swagger.json +++ b/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", diff --git a/swagger/tag_groups/other_swagger.json b/swagger/tag_groups/other_swagger.json index 2cc045747..e2a16245b 100644 --- a/swagger/tag_groups/other_swagger.json +++ b/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", diff --git a/swagger/tag_groups/platform_swagger.json b/swagger/tag_groups/platform_swagger.json index 085e969ab..b4feb0024 100644 --- a/swagger/tag_groups/platform_swagger.json +++ b/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",