Products API

Create, read, update, and delete products in your organization's catalog.

GET /api/v1/products

Returns a paginated list of products from your organization's catalog. Use query parameters to filter and search.

Query Parameters

Example Request

GET /api/v1/products?page=1&pageSize=10&search=microphone
Authorization: Bearer YOUR_JWT_TOKEN

Response (200 - Success)

{
    "success": true,
    "data": {
        "products": [
            {
                "id": 123,
                "make": "Shure",
                "model": "MXA910",
                "description": "Ceiling array microphone",
                "price": 2999.00,
                "productType": "Microphone",
                "part": "MXA910-60CM",
                "category": "Audio",
                "isActive": true
            }
        ],
        "pagination": {
            "currentPage": 1,
            "pageSize": 10,
            "totalCount": 150,
            "totalPages": 15,
            "hasPrevious": false,
            "hasNext": true
        }
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

GET /api/v1/products/{id}

Returns a single product by its unique identifier.

Response (200 - Success)

{
    "success": true,
    "data": {
        "product": {
            "id": 123,
            "make": "Shure",
            "model": "MXA910",
            "description": "Ceiling array microphone",
            "longDescription": "Professional ceiling array microphone with 60cm pickup pattern...",
            "enrichedDescription": "AI-generated detailed description...",
            "price": 2999.00,
            "vendor": "TD SYNNEX",
            "imageUrl": "https://example.com/mxa910.jpg",
            "productType": "Microphone",
            "part": "MXA910-60CM",
            "category": "Audio",
            "roomType": "Conference Room",
            "tags": "microphone,ceiling,array,beamforming",
            "specifications": "60cm pickup pattern, 8 lobes, PoE+",
            "isActive": true,
            "dateUpdated": "2024-12-20T10:30:00Z",
            "hasEmbedding": true
        }
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

POST /api/v1/products

Creates a new product in your organization's catalog.

Request Body

Response (201 - Created)

{
    "success": true,
    "productId": 124,
    "message": "Product created successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

PUT /api/v1/products/{id}

Updates an existing product. All fields from the POST request body are accepted.

DELETE /api/v1/products/{id}

Permanently removes a product from your catalog.

Response (200 - Success)

{
    "success": true,
    "productId": 123,
    "message": "Product deleted successfully"
}

PUT /api/v1/products/{id}/metadata

Replace a product's connection metadata — input/output ports, device type, category, and power requirements. Used to configure products for schematic wiring.

Request Body

Send a full ConnectionMetadata JSON object. Port types are validated against the port type registry — use GET /api/v1/products/port-types to see valid options; an invalid one fails the whole request (see Error Responses below).

A port states its PoE with two fields, and it carries at most one of them:

• poeSource — the tier this jack supplies to whatever plugs into it: "PoE", "PoE+", "PoE++", or "none" to state that it supplies nothing. Omit it, or send null, when the jack was never described.
• poeDraw — the tier this jack draws from the far end. This jack is the one being powered.

Neither field fails the request. Both are checked against the port type registry and saved as null when the connector cannot carry PoE — only rj45 and ethercon can. A port that arrives with both set keeps poeDraw and has its poeSource cleared: a jack being powered is what decides which way the watts run.

The device-level power is derived from the jacks on save. When any port draws, power becomes the strongest tier drawn, whatever you sent. When no port draws, the power you sent is kept as-is — and a PoE tier sent with no drawing jack behind it raises a notice on the wiring report, because nothing says which jack is fed. In the example below, the AVB/Ctrl jack is what backs the "power": "PoE+".

{
  "category": "Processing",
  "deviceType": "Digital Signal Processor",
  "power": "PoE+",
  "inputPorts": [
    { "portType": "rj45", "innerLabel": "AVB/Ctrl", "poeDraw": "PoE+" },
    { "portType": "dante_rj45", "innerLabel": "DANTE IN 1" },
    { "portType": "xlr_3pin_female", "innerLabel": "MIC 1" }
  ],
  "outputPorts": [
    { "portType": "dante_rj45", "innerLabel": "DANTE OUT 1" },
    { "portType": "speakon_nl4", "innerLabel": "AMP OUT" }
  ]
}

Response (200 — Success)

{
  "success": true,
  "data": {
    "success": true,
    "productId": 157,
    "message": "Product metadata updated"
  }
}

Error Responses

GET /api/v1/products/port-types

Returns all valid port types grouped by category (Video, Audio, Data, Fiber, Power, Control). Use these IDs in the portType field when setting connection metadata.

Response (200 — Success)

{
  "success": true,
  "data": {
    "port_types": {
      "Video": [
        { "id": "hdmi_a", "name": "HDMI Type A" },
        { "id": "displayport", "name": "DisplayPort" }
      ],
      "Audio": [
        { "id": "xlr_3pin_male", "name": "XLR 3-Pin Male" },
        { "id": "speakon_nl4", "name": "Speakon NL4" }
      ],
      "Data": [
        { "id": "rj45", "name": "RJ-45 (Ethernet)" },
        { "id": "usb_c", "name": "USB Type-C" }
      ]
    }
  }
}