AI Features API

Access AI-powered features including semantic search, embeddings, and product enhancements.

Credits Required

Most AI endpoints consume credits. Check your balance before making requests.

POST /api/v1/ai/semantic-search

Search products using natural language. Requires embeddings to be generated first.

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural language search query (e.g., "wireless ceiling microphone for conference rooms")
`limit`	integer	No	Maximum number of results to return (default: 10, max: 50)
`threshold`	decimal	No	Minimum similarity score 0-1 (default: 0.7). Higher values return more relevant results.
`includeBundles`	boolean	No	Include bundles in search results (default: true)

Example Request

{
    "query": "wireless ceiling microphone for conference rooms",
    "limit": 10,
    "threshold": 0.7,
    "includeBundles": true
}

Response

{
    "success": true,
    "data": {
        "query": "wireless ceiling microphone for conference rooms",
        "results": [
            {
                "id": 456,
                "isBundle": false,
                "name": "Shure MXA920",
                "description": "Ceiling array microphone",
                "similarity": 0.92,
                "make": "Shure",
                "model": "MXA920",
                "price": 2899.00,
                "productType": "Microphone"
            }
        ],
        "totalResults": 8,
        "embeddingStats": {
            "totalProducts": 1500,
            "productsWithEmbeddings": 1450,
            "percentageComplete": 96.7
        }
    }
}

POST /api/v1/ai/embeddings/generate

Generate embeddings for products and bundles. Runs in batches. Call repeatedly until all products are processed.

Request Body

Field	Type	Required	Description
`batchSize`	integer	No	Number of items to process per call (default: 50, max: 100)

Example Request

{
    "batchSize": 50
}

Response

{
    "success": true,
    "data": {
        "productsProcessed": 50,
        "bundlesProcessed": 10,
        "totalProcessed": 60,
        "stats": {
            "totalProducts": 1500,
            "productsWithEmbeddings": 1450,
            "totalBundles": 25,
            "bundlesWithEmbeddings": 25,
            "percentageComplete": 96.7
        },
        "message": "Generated embeddings for 50 products and 10 bundles"
    }
}

GET /api/v1/ai/embeddings/status

Get embedding generation status for products and bundles.

Response

{
    "success": true,
    "data": {
        "products": {
            "total": 1500,
            "withEmbeddings": 1450,
            "withoutEmbeddings": 50,
            "percentageComplete": 96.7
        },
        "bundles": {
            "total": 25,
            "withEmbeddings": 25,
            "withoutEmbeddings": 0,
            "percentageComplete": 100.0
        },
        "overall": {
            "total": 1525,
            "withEmbeddings": 1475,
            "withoutEmbeddings": 50,
            "percentageComplete": 96.7
        },
        "isReady": true
    }
}

POST /api/v1/ai/product/enhance-metadata

Enhance product metadata using AI. Returns suggestions without modifying the product. Consumes 1 AI credit.

Request Body

Field	Type	Required	Description
`productId`	integer	Yes	ID of the product to enhance

Example Request

{
    "productId": 456
}

Response

{
    "success": true,
    "data": {
        "productId": 456,
        "originalData": {
            "make": "Shure",
            "model": "MXA920",
            "description": null
        },
        "enhancedData": {
            "recommendedMake": "Shure",
            "recommendedModel": "MXA920",
            "description": "Ceiling array microphone with IntelliMix DSP",
            "longDescription": "The Shure MXA920 is a premium ceiling array microphone..."
        },
        "creditsUsed": 1.0,
        "message": "Product metadata enhanced successfully. Review and apply changes as needed."
    }
}

POST /api/v1/ai/product/generate-description

Generate a product description from make/model without needing an existing product. Consumes 1 AI credit.

Request Body

Field	Type	Required	Description
`make`	string	Yes	Manufacturer name (e.g., "Crestron", "Shure")
`model`	string	Yes	Model number or name
`part`	string	No	Part number (if different from model)

Example Request

{
    "make": "Crestron",
    "model": "CP4-R",
    "part": "CP4-R"
}

Response

{
    "success": true,
    "data": {
        "input": {
            "make": "Crestron",
            "model": "CP4-R"
        },
        "generatedData": {
            "recommendedMake": "Crestron",
            "recommendedModel": "CP4-R",
            "description": "4-Series Control System",
            "longDescription": "The Crestron CP4-R is a rack-mountable 4-Series control processor..."
        },
        "creditsUsed": 1.0
    }
}

POST /api/v1/ai/room/suggest-equipment

Get AI-powered equipment suggestions based on room type and requirements. Uses semantic search to find relevant products from your catalog.

Request Body

Field	Type	Required	Description
`roomType`	string	Yes	Type of room (e.g., "Large Conference Room", "Huddle Space", "Training Room", "Boardroom")
`capacity`	integer	No	Room seating capacity (helps refine suggestions)
`additionalRequirements`	string	No	Additional requirements in natural language (e.g., "Video conferencing capability", "Multiple displays")
`maxSuggestionsPerCategory`	integer	No	Max suggestions per equipment category (default: 5)
`maxTotalSuggestions`	integer	No	Max total suggestions across all categories (default: 20)

Example Request

{
    "roomType": "Large Conference Room",
    "capacity": 20,
    "additionalRequirements": "Video conferencing capability",
    "maxSuggestionsPerCategory": 5,
    "maxTotalSuggestions": 20
}

Response

{
    "success": true,
    "data": {
        "roomType": "Large Conference Room",
        "capacity": 20,
        "suggestions": [
            {
                "productId": 456,
                "make": "Shure",
                "model": "MXA920",
                "description": "Ceiling array microphone",
                "price": 2899.00,
                "category": "Microphone",
                "relevanceScore": 0.95,
                "rationale": "Recommended for Large Conference Room: Microphone"
            }
        ],
        "totalSuggestions": 18,
        "categories": ["Display", "Camera", "Microphone", "Video Conferencing", "DSP"]
    }
}

Embeddings Required

Equipment suggestions use semantic search, which requires embeddings to be generated first.

POST /api/v1/ai/project/executive-summary

Generate an executive summary for a project using AI. Processes each room and creates a consolidated summary. Consumes 10 AI credits (or free for users with remaining free AI uses).

Request Body

Field	Type	Required	Description
`projectId`	integer	Yes	ID of the project to generate a summary for
`roomIds`	integer[]	Yes	Room IDs to include in the summary. Must be non-empty. Every ID must belong to the project — calls with any invalid ID are rejected. Use `GET /api/v1/projects/{projectId}/rooms` to discover valid IDs.

Example Request

{
    "projectId": 123,
    "roomIds": [45, 46, 47]
}

Response

{
    "success": true,
    "data": {
        "projectId": 123,
        "projectName": "Acme Corporate HQ",
        "summary": "This project covers 3 conference spaces with modern AV systems...",
        "roomSummaries": [
            {
                "roomId": 45,
                "roomName": "Executive Boardroom",
                "summary": "A premium boardroom featuring a 98-inch display, ceiling microphone array, and video conferencing system designed for executive meetings and presentations.",
                "itemCount": 12,
                "categoryCount": 5
            },
            {
                "roomId": 46,
                "roomName": "Large Conference Room",
                "summary": "A versatile conference space with dual displays, PTZ camera, and integrated audio system for hybrid meetings.",
                "itemCount": 8,
                "categoryCount": 4
            }
        ],
        "roomsProcessed": 3,
        "creditsUsed": 10.0,
        "wasFreeUse": false,
        "timestamp": "2024-12-26T15:30:00Z"
    }
}

Error Codes

Code	Description
`PROJECT_NOT_FOUND`	The specified project does not exist or belongs to another tenant
`MISSING_ROOM_IDS`	The `roomIds` field was missing or empty (also raised by the validation layer as `VALIDATION_ERROR`)
`INVALID_ROOM_IDS`	One or more provided `roomIds` do not belong to the specified project. The error message lists the offending IDs. The whole call is rejected — no partial summary is generated and no credits are deducted.
`INSUFFICIENT_CREDITS`	Not enough credits to perform this operation (requires 10 credits)
`AI_GENERATION_FAILED`	AI service failed to generate the summary

Use Cases

Executive summaries are ideal for proposals, client presentations, and project documentation. Each room is analyzed individually, then combined into a cohesive project overview.