--- updatedAt: 2026-07-21T08:40:48.000Z agentTools: projectIndex: https://developers.intandem.tech/llms.txt --- # Create a BusinessRule ## Overview Create a new business rule for the authenticated business. Available for **Staff** tokens. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Ai", "description": "Unified OpenAPI specification for ai domain", "version": "3.0", "x-generated": { "sourceFiles": [ "recommendations.json", "business_rules.json", "business_ai_settings.json", "bizai.json", "ai_smart_reply.json", "generic_ai.json", "staff_ai_settings.json", "ai_generation_feedback.json" ], "pathNormalizations": [], "pathConflicts": [], "componentConflicts": [ { "type": "schema", "name": "ErrorResponse", "resolution": "Renamed to ErrorResponse_business_rules", "files": [ "merged", "business_rules.json" ] }, { "type": "schema", "name": "ErrorResponse", "resolution": "Renamed to ErrorResponse_business_ai_settings", "files": [ "merged", "business_ai_settings.json" ] }, { "type": "schema", "name": "Response", "resolution": "Renamed to Response_ai_smart_reply", "files": [ "merged", "ai_smart_reply.json" ] }, { "type": "schema", "name": "ErrorResponse", "resolution": "Renamed to ErrorResponse_staff_ai_settings", "files": [ "merged", "staff_ai_settings.json" ] } ], "totalPaths": 20, "totalComponents": 33 } }, "servers": [ { "url": "https://api.vcita.biz", "description": "Unified API Gateway server" } ], "paths": { "/v3/ai/business_rules": { "post": { "operationId": "BusinessRulesController_createBusinessRule", "summary": "Create a BusinessRule", "description": "## Overview\nCreate a new business rule for the authenticated business.\n\nAvailable for **Staff** tokens.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessRuleRequestDto" }, "example": { "content": "Always use a friendly and professional tone", "sort_order": 0, "category_code": "tone_of_voice" } } } }, "responses": { "201": { "description": "Business rule created successfully", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the API request was successful (true) or failed (false)." }, "data": { "type": "object", "description": "The response payload. Present on successful responses (success: true)." }, "error": { "type": "string", "description": "Error message for simple error responses. Used in some legacy endpoints." }, "errors": { "type": "array", "description": "Array of error objects for detailed error responses. Present on error responses (success: false).", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code (e.g., 'already_exists', 'invalid', 'not_found')." }, "message": { "type": "string", "description": "Human-readable error message." }, "field": { "type": "string", "description": "The field that caused the error (for validation errors)." } }, "required": [ "code", "message" ] } } }, "required": [ "success" ], "description": "Generic wrapper object for API responses. Success responses contain 'data', while error responses contain 'errors' array or 'error' string." }, { "properties": { "data": { "type": "object", "description": "Represents a business rule that guides AI behavior for a specific business. Rules are organized by category (tone of voice, business policies, things to avoid, FAQ) and can be AI-generated (system) or user-created. For FAQ category rules, the metadata contains structured question and answer fields extracted from the content. Rules can be activated, deactivated, or held in a pending approval state.", "properties": { "uid": { "type": "string", "readOnly": true, "description": "The unique identifier (UID) of the business rule (e.g., \"br-a1b2c3d4-5678-90ef-ghij-klmnopqrstuv\"). Assigned automatically by the system upon creation." }, "business_uid": { "type": "string", "readOnly": true, "description": "The unique identifier (UID) of the business that owns this rule (e.g., \"biz-1234abcd-5678-90ef-ghij-klmnopqrstuv\"). Automatically set based on the authenticated token." }, "content": { "type": "string", "description": "The content or text of the business rule (e.g., \"Always use a friendly and professional tone when communicating with clients\"). For FAQ rules, this typically contains both the question and answer in a combined format." }, "status": { "type": "string", "description": "The current status of the business rule, controlling whether the AI agent actively uses it.\n\n* `active` - The rule is currently in effect and will be used by the AI agent.\n* `pending_approval` - The rule has been suggested (typically by the system) and is awaiting staff review before becoming active.\n* `inactive` - The rule has been deactivated and will not be used by the AI agent.", "enum": [ "active", "pending_approval", "inactive" ] }, "source": { "type": "string", "readOnly": true, "description": "Indicates whether the rule was created by the AI system or by a user (staff member).\n\n* `system` - The rule was generated automatically by the AI based on analysis of business conversations.\n* `user` - The rule was manually created or edited by a staff member.", "enum": [ "system", "user" ] }, "created_by_staff_uid": { "type": "string", "readOnly": true, "description": "The UID of the staff member who created the rule (e.g., \"stf-9876wxyz-5432-10ab-cdef-ghijklmnopqr\"). Will be null for system-generated rules that have not been manually edited.", "nullable": true }, "updated_by_staff_uid": { "type": "string", "readOnly": true, "description": "The UID of the staff member who last updated the rule (e.g., \"stf-9876wxyz-5432-10ab-cdef-ghijklmnopqr\"). Will be null if the rule has never been updated by a staff member.", "nullable": true }, "sort_order": { "type": "integer", "description": "Sort order for displaying rules within a category (e.g., 0). Lower values appear first. Rules within the same category are ordered by this field in ascending order." }, "metadata": { "type": "object", "description": "Additional metadata associated with the rule. For FAQ rules, includes structured `question` and `answer` fields. For system-generated rules, may include `confidence`, `reasoning`, and `evidence` from the AI analysis.", "nullable": true, "properties": { "question": { "type": "string", "description": "The question part of an FAQ rule (e.g., \"What are your business hours?\"). Only present for rules with category `faq`." }, "answer": { "type": "string", "description": "The answer part of an FAQ rule (e.g., \"We are open Monday to Friday, 9 AM to 5 PM.\"). Only present for rules with category `faq`." }, "confidence": { "type": "number", "description": "AI confidence score ranging from 0.0 to 1.0 indicating how confident the system is about this rule (e.g., 0.92). Only present for system-generated rules." }, "reasoning": { "type": "string", "description": "AI-generated reasoning explaining why this rule was created or suggested (e.g., \"Consistent friendly tone observed across 15 client conversations\"). Only present for system-generated rules." }, "evidence": { "type": "array", "description": "Evidence from conversations that supports this rule. Contains quotes and references from actual client-staff interactions.", "items": { "type": "object", "properties": { "client_uid": { "type": "string", "description": "The UID of the client involved in the conversation." }, "message_uid": { "type": "string", "description": "The UID of the specific message used as evidence." }, "quote": { "type": "string", "description": "A direct quote from the conversation used as evidence." }, "speaker": { "type": "string", "enum": [ "staff", "client" ], "description": "Identifies whether the quote is from a staff member or a client.\n\n* `staff` - The quote is from a staff member.\n* `client` - The quote is from a client." } } } } } }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date and time when the business rule was created, in ISO 8601 format (e.g., \"2024-12-15T10:30:00.000Z\")." }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date and time when the business rule was last updated, in ISO 8601 format (e.g., \"2024-12-16T14:00:00.000Z\")." }, "category_code": { "type": "string", "description": "The category of the business rule. Determines how the AI agent uses this rule.\n\n* `tone_of_voice` - Rules about communication style, language, and tone the AI should adopt when interacting with clients.\n* `policies_and_info` - Rules about business operations, pricing, scheduling policies, and other operational guidelines.\n* `things_to_avoid` - Rules about topics, phrases, or actions the AI should not mention or perform.\n* `faq` - Frequently asked questions and their answers. When this category is used, the metadata field should contain structured `question` and `answer` fields.\n* `client_facing_bot_policies` - Rules specifically for client-facing bot interactions, defining bot behavior, limitations, and escalation policies.\n* `lead_handling` - Rules about how incoming leads should be qualified, prioritized, and followed up.", "enum": [ "tone_of_voice", "policies_and_info", "things_to_avoid", "faq", "client_facing_bot_policies", "lead_handling" ] } }, "required": [ "uid", "business_uid", "category_code", "content", "status", "source", "sort_order", "created_at", "updated_at" ], "example": { "uid": "br-a1b2c3d4-5678-90ef-ghij-klmnopqrstuv", "business_uid": "biz-1234abcd-5678-90ef-ghij-klmnopqrstuv", "content": "Always use a friendly and professional tone when communicating with clients", "status": "active", "source": "system", "created_by_staff_uid": "stf-9876wxyz-5432-10ab-cdef-ghijklmnopqr", "updated_by_staff_uid": null, "sort_order": 0, "metadata": { "confidence": 0.92, "reasoning": "Consistent friendly tone observed across 15 client conversations" }, "created_at": "2024-12-15T10:30:00.000Z", "updated_at": "2024-12-15T10:30:00.000Z", "category_code": "tone_of_voice" } } } } ] }, "example": { "success": true, "data": { "business_rule": { "uid": "br-a1b2c3d4-5678-90ef-ghij-klmnopqrstuv", "business_uid": "biz-1234abcd-5678-90ef-ghij-klmnopqrstuv", "content": "Always use a friendly and professional tone", "status": "active", "source": "user", "created_by_staff_uid": "stf-9876wxyz-5432-10ab-cdef-ghijklmnopqr", "updated_by_staff_uid": null, "sort_order": 0, "metadata": null, "created_at": "2024-12-15T10:30:00.000Z", "updated_at": "2024-12-15T10:30:00.000Z", "category_code": "tone_of_voice" } } } } } }, "400": { "description": "Bad request - malformed request or invalid syntax", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "errors": [ { "field": "category_code", "code": "required", "message": "category_code is required" } ] } } } }, "401": { "description": "Unauthorized - invalid or missing bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unprocessable Entity - Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "errors": [ { "field": "category_code", "code": "invalid", "message": "category_code must be one of: tone_of_voice, policies_and_info, things_to_avoid, faq" } ] } } } } }, "tags": [ "BizAI Business Rules" ], "security": [ { "Bearer": [] } ] } } }, "components": { "schemas": { "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The name of the field that caused the error (e.g., \"uid\", \"status\")." }, "code": { "type": "string", "description": "A machine-readable error code (e.g., \"invalid\", \"required\", \"not_found\")." }, "message": { "type": "string", "description": "A human-readable error message describing the issue." } } } } }, "required": [ "success", "errors" ] }, "CreateBusinessRuleRequestDto": { "type": "object", "properties": { "content": { "type": "string", "description": "The content or text of the business rule (e.g., \"Always use a friendly and professional tone\"). For FAQ rules, include both the question and answer.", "example": "Always use a friendly and professional tone" }, "sort_order": { "type": "integer", "description": "Sort order for displaying rules within a category (e.g., 0). Lower values appear first. Defaults to 0 if not provided.", "example": 0 }, "category_code": { "type": "string", "description": "The category code of the business rule. Determines how the AI agent uses this rule.\n\nAvailable values:\n* `tone_of_voice` - Rules about communication style and tone the AI should adopt when interacting with clients.\n* `policies_and_info` - Rules about business operations, pricing, and scheduling policies.\n* `things_to_avoid` - Rules about topics, phrases, or actions the AI should not mention or perform.\n* `faq` - Frequently asked questions and their answers.\n* `client_facing_bot_policies` - Rules specifically for client-facing bot interactions, defining bot behavior, limitations, and escalation policies.\n* `lead_handling` - Rules about how incoming leads should be qualified, prioritized, and followed up.", "enum": [ "tone_of_voice", "policies_and_info", "things_to_avoid", "faq", "client_facing_bot_policies", "lead_handling" ], "example": "tone_of_voice" } }, "required": [ "category_code", "content" ] } }, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Provide a valid bearer token in the Authorization header. Example: 'Authorization: Bearer {app_token}'" } } } } ```