Replace Equipment

Send the equipment list you want a room to hold. AVstackr compares your list to the room, then adds, updates and deletes lines until the room matches it. A second endpoint does the same for several rooms at once. It touches only the rooms you name.

Use these endpoints when the real equipment list lives outside AVstackr, in an ERP, a spreadsheet or a design tool, and AVstackr has to follow it.

These are not CRUD endpoints. You are not telling us to add, update or delete anything. You send the list you want the room to end up with, and we work out which of those three to do for each line.

AVstackr does have CRUD endpoints for line items, in the Projects API: POST, PATCH and DELETE on a single line. Reach for those when you know exactly which line changed. Reach for these two when your own system owns the whole list and wants ours to match it.

The difference shows up in the work. Under CRUD your integration has to compare its list against ours, decide what changed, then fire one request per change, each able to fail on its own and leave the room half done. Here you send one list in one request. We do the rest:

• Send a line the room already holds, and we update it.
• Send a line the room does not hold, and we add it.
• Leave out a line the room holds, and we delete it.

We do all of it in one write. If any part of your request is bad, we save none of it. Working out that difference between your list and the stored one is called a reconcile.

Auth: Api-Key header, the same as every other line item endpoint. See Authentication. Both endpoints write, so we turn down a read-only key with 403 and the code READ_ONLY_ACCESS.

PUT /api/v1/projects/{projectId}/rooms/{roomId}/items

Replace one room's equipment list.

Request Body

Send a flat items list to set the equipment and nothing else. That is the common case:

{
    "items": [
        { "productId": 39022, "quantity": 2 },
        { "productId": 33155, "quantity": 1 }
    ]
}

Send sections instead when you also want to set the headings that group the room's equipment. A divider is a named heading row inside a room's equipment list: "Head End", "Field Devices", "Audio". It prints as a section heading with its own subtotal on estimates, proposals and exports. See Bundles & Dividers for what they look like in the app.

Each section name in your payload becomes one divider, in the order you send them, and that section's items sit beneath it. We delete every divider the room had before and rebuild them from your payload, so the new dividers get new IDs. Re-read the room after a sections push if you store divider IDs:

{
    "sections": [
        { "name": "Head End",      "items": [ { "productId": 39022, "quantity": 1 } ] },
        { "name": "Field Devices", "items": [ { "productId": 33155, "quantity": 3 } ] }
    ]
}

Item Fields

Every field except quantity is optional. What we do with a field you leave out depends on whether the line already exists:

• On a line that matches one already in the room, we keep the stored value. Leaving out notes does not erase the notes.
• On a new line, we leave the field empty, because there is nothing stored to keep. productCostEach is the one exception. Leave it out on a new line and we snapshot the catalog price for you, at the project's currency rate.

Leaving a field out will not erase a value on a matched line. Use clearFields, described in the table below.

Every money and hours field is per unit, not per line. A line with "quantity": 4 and "laborHours": 2 carries 8 hours in total, and its extended price is the unit price times 4.

Response (200 OK)

{
    "success": true,
    "data": {
        "success": true,
        "rooms": [
            {
                "roomId": 1738,
                "roomName": "Layout Demo Room",
                "added": 1,
                "updated": 0,
                "removed": 0,
                "lineItems": [
                    {
                        "id": 16399,
                        "productId": 39022,
                        "make": "AJA",
                        "model": "Ki Pro Ultra Plus",
                        "part": "Ki Pro Ultra Plus",
                        "description": "File-based 4K/HD recorder and player for SDI workflows",
                        "quantity": 2,
                        "productCostEach": null,
                        "productMarkup": null,
                        "laborHours": null,
                        "configurationHours": null,
                        "programmerHours": null,
                        "notes": null,
                        "equipmentSource": null,
                        "order": 1,
                        "price": null,
                        "poNumber": null,
                        "quoteReference": null,
                        "isOwnerFurnished": false
                    }
                ]
            }
        ],
        "orphanedCanvasDevices": [],
        "timestamp": "2026-08-27T18:13:21.1135959Z"
    },
    "message": null,
    "timestamp": "2026-08-27T18:13:21.1534529Z"
}

We wrap the reply twice. The outer success, message and timestamp are the standard wrapper every AVstackr endpoint returns. data holds the result of the push itself, which carries its own success and timestamp.

added, updated and removed count what the push changed in that room. lineItems is the room's whole list after the push, not just the lines that changed, so you can store it as your new picture of the room. order on each line is its top-to-bottom position in the room. It follows the order you sent the items in, and you do not set it yourself.

orphanedCanvasDevices lists the schematic drawing blocks left with no equipment behind them. We Never Delete Canvas Devices below explains it. It sits at the top of data, not inside a room, and covers every room in the request.

Success is 200, not 201, even when the push adds lines. One request can add, update and delete at once, so there is no single new thing to point at.

PUT /api/v1/projects/{projectId}/items

Replace the equipment lists of several rooms in one write. Each entry under rooms takes the same body as the single-room endpoint above: either items or sections, never both. Two rooms in the same request can use different forms, as the example below does.

Request Body

{
    "rooms": [
        {
            "roomId": 1741,
            "items": [
                { "productId": 39022, "quantity": 2 },
                { "productId": 33155, "quantity": 1 }
            ]
        },
        {
            "roomId": 1742,
            "sections": [
                { "name": "Head End",      "items": [ { "productId": 39022, "quantity": 1 } ] },
                { "name": "Field Devices", "items": [ { "productId": 33155, "quantity": 3 } ] }
            ]
        }
    ]
}

Response (200 OK)

The same reply shape as the single-room endpoint, with one entry in rooms for each room you sent. Each entry carries its own added, updated and removed counts and its own full lineItems list. orphanedCanvasDevices stays a single list covering every room in the request.

Read the Room Before You Write It

Your list wins. Anything the room holds that you left out, we delete, with no warning and no confirmation step.

That makes a partial list dangerous. Send one item to a room that holds twenty, and you have just deleted nineteen lines. The response calls that a success, because it is one. We did exactly what you asked.

The safe pattern is always three steps:

1. Read the room with GET /api/v1/projects/{projectId}/rooms/{roomId}/items. See the Projects API.
2. Apply your changes to that list, in your own code.
3. Send the whole edited list back with a PUT.

Never build the payload from just the lines you know changed.

400 UNKNOWN_FIELDS — room 1741.items[0]: unknown field(s) [id, order]

Example

Read room 1738, change one quantity, then push the whole room back. The read returns two lines:

GET /api/v1/projects/812/rooms/1738/items
Api-Key: YOUR_API_KEY

{
    "success": true,
    "data": {
        "items": [
            { "id": 16399, "productId": 39022, "make": "AJA",  "model": "Ki Pro Ultra Plus", "quantity": 2 },
            { "id": 16400, "productId": 33155, "make": "Shure", "model": "MXA910",            "quantity": 1 }
        ]
    }
}

To raise the second line to 3, send both lines back, rebuilt from the documented fields:

PUT /api/v1/projects/812/rooms/1738/items
Api-Key: YOUR_API_KEY
Content-Type: application/json

{
    "items": [
        { "productId": 39022, "quantity": 2 },
        { "productId": 33155, "quantity": 3 }
    ]
}

The response reports added: 0, updated: 2, removed: 0. Both lines keep their IDs. Leaving the first item out instead would have deleted it.

We Edit Matching Lines in Place

When a line in your list matches a line already in the room, we edit that line where it stands. We do not replace it. It keeps its database id, and everything hanging off that id survives the push:

• Notes, labor hours, configuration hours, programming hours, PO number and quote reference, unless your item sends new values for them.
• Cable assignments, unless your item sends a cables list.
• Line item attributes, the key/value entries described in the Line Item Attributes API.

This matters because the alternative would destroy all of it. If a push deleted every line and added them back, each new line would get a new id, and the attributes recorded against the old ids would be gone. Push the same list twice and you would wipe the room's history both times.

We add the lines in your list that match nothing. We delete the lines in the room that match nothing in your list, and a delete takes that line's cable assignments and its line item attribute entries with it. Per-unit attributes are the exception. A unit hangs off the project, room, make and model rather than off a line item id, so we keep the serial numbers and MAC addresses recorded against individual units when the line goes.

How We Match a Line

We match in two steps.

First, we look inside the room. An item carrying a productId claims a room line with that same productId. An item carrying no productId claims a room line whose make, model and part all match its own. That comparison ignores capitalization and surrounding spaces, so "Shure" and "shure " are the same manufacturer. It does not ignore punctuation, so MXA-910 and MXA910 are two different lines here. An item can only claim a line in its own room, never one from another room in the same request.

Then, for anything left over, we look in the catalog. We reject a productId that is not in your catalog with PRODUCT_NOT_FOUND. We look up a name like this:

• make must match a catalog product's manufacturer. An item with no make matches nothing.
• You must also send model or part, or both. make on its own matches nothing.
• Either value you send can hit either value on the catalog product. Many catalogs store the manufacturer's SKU in the model column, and many store it in the part column. So make plus part, with no model, is a legal way to name a product.
• Catalog matching is looser than room matching. It ignores capitalization, spaces, hyphens, underscores and accents. Here MXA-910 and MXA910 are the same product.
• Because either value can hit either column, adding part alongside model can only find the same products or more of them. It never narrows a catalog lookup, and it can turn a single match into AMBIGUOUS_PRODUCT.

Three more rules worth knowing:

• We keep duplicate lines. We never merge them. Two lines of the same product in one room are legitimate, with different notes and different PO numbers. Send the same productId twice in one payload and you get two lines, not one line with the quantities added together. Send it once and we delete the second existing line.
• A line whose catalog product was deleted still round-trips. Say a room holds a line for a product someone has since removed from your catalog. Read the room, push it back, and it still works. The line matches inside the room and never reaches the catalog lookup.
• These endpoints cannot invent a product. We reject a name that matches nothing in the room and nothing in the catalog with PRODUCT_NOT_FOUND. Add the product to your catalog first. See Products API.

We Never Delete Canvas Devices

Equipment lines and schematic drawings are two separate things in AVstackr. An engineer draws a project's signal flow on the schematics canvas, placing each device block by hand and wiring it to the other blocks by hand. The blocks stand for the room's equipment, but they are not the same records.

A replace only ever touches the equipment list. It never deletes, moves or unwires a device block. Drop a product off a room's list and the block drawn for it stays where the engineer put it, wiring intact. We do not throw away hours of layout work because an outside system changed a line.

That leaves the drawing showing a device the room no longer buys, and someone has to decide what to do about it. So the response lists every one of them under orphanedCanvasDevices:

{
    "deviceId": "dev-DE0F2658",
    "roomId": 1741,
    "roomName": "Test Room A",
    "manufacturer": "APC",
    "partNumber": "SCL500RM1UC",
    "page": 1
}

The list covers every room in the request, and only the rooms in the request. We report a block only when the room has no equipment line left at all for that device's manufacturer and model. Cut a line's quantity from three to one and we report nothing. Delete one of two lines for the same product and we report nothing.

An empty array normally means the push left nothing behind. It can also mean the check itself could not run. We run the check after we have saved the write, and if the check fails we log it and carry on rather than turn a good write into an error. Read an empty array as "nothing to report", not as proof the canvas is clean.

All or Nothing

We save the whole request or we save none of it. There is no partial success.

We write nothing until we have checked every item in every room: the shape of the payload, the limits, and every product name landing on exactly one catalog product. One bad item in room five kills the whole push, and rooms one through four keep exactly what they had. The same goes for a conflict we find part-way through. A 409 also means we wrote nothing.

A rejected request never leaves a project half-updated, so you can always fix the payload and send the whole thing again.

Limits

• 500 items per room. With sections, this counts every item across all of that room's sections, not each section on its own.
• 100 rooms per request.
• 5,000 items in total across all rooms.
• quantity between 1 and 10,000.

Break any of the first three and you get LIMIT_EXCEEDED. A quantity outside its range gets INVALID_SHAPE. Either way we write nothing, so split the work across several requests and send them again.

Errors

A failure returns the standard error envelope, the reply shape every AVstackr endpoint uses when something goes wrong:

{
    "success": false,
    "error": {
        "code": "...",
        "message": "...",
        "details": null
    },
    "timestamp": "..."
}

The message points at the exact item at fault, so a rejected push tells you which line to fix. We count positions from zero, matching the payload you sent, so you can walk straight to the line.

The two endpoints address that line differently, because they know the room differently. The project-wide endpoint counts your rooms, since you listed them:

rooms[1].items[0].quantity is required — send the line's quantity on every item, there is no default.

The single-room endpoint names the room outright, since it sits in the URL:

room 1741.sections[1].items[0].quantity must be between 1 and 10000 (0).

{
    "errorCode": "LOCKED_VERSION",
    "userFacingMessage": "This project version is locked. Create a Change Order to modify it.",
    "suggestedAction": "create_change_order",
    "versionId": 17,
    "contractId": 88
}