Projects API

Create and manage AV system design projects with rooms and equipment.

GET /api/v1/projects

Returns a paginated list of projects for your organization.

Query Parameters

Response (200 - Success)

{
    "success": true,
    "data": {
        "projects": [
            {
                "id": 1,
                "projectName": "Corporate HQ Upgrade",
                "jobNumber": "2024-001",
                "createdBy": "user@example.com",
                "salesEngineer": "John Smith",
                "projectManager": "Jane Doe",
                "accountManager": "Bob Wilson",
                "opportunityOwner": "Alice Johnson",
                "laborRate": 85.00,
                "equipmentMarkup": 1.25,
                "roomCount": 5
            }
        ],
        "pagination": { ... }
    }
}

GET /api/v1/projects/{id}

Returns a single project by ID, including summary statistics for its rooms.

Response (200 - Success)

{
    "success": true,
    "data": {
        "project": {
            "id": 1,
            "projectName": "Corporate HQ Upgrade",
            "jobNumber": "2024-001",
            "createdBy": "user@example.com",
            "salesEngineer": "John Smith",
            "projectManager": "Jane Doe",
            "accountManager": "Bob Wilson",
            "opportunityOwner": "Alice Johnson",
            "laborRate": 85.00,
            "equipmentMarkup": 1.25,
            "roomCount": 5,
            "rooms": [
                {
                    "id": 1,
                    "roomName": "Conference Room A",
                    "quantity": 1,
                    "isAddAlt": false,
                    "laborHours": 8.5,
                    "programmerHours": 4.0,
                    "replacesRoomId": null,
                    "replacesRoomName": null,
                    "linkState": "None"
                },
                {
                    "id": 2,
                    "roomName": "Conference Room A (Alt)",
                    "quantity": 1,
                    "isAddAlt": true,
                    "laborHours": 8.5,
                    "programmerHours": 4.0,
                    "replacesRoomId": 1,
                    "replacesRoomName": "Conference Room A",
                    "linkState": "Resolved"
                }
            ]
        }
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

Each room reports the base room it replaces. replacesRoomId is the stored id of that base room, or null. linkState says whether the link is live: None (the room has no link), Resolved, or the reason it is not, which is BaseMissing, BaseArchived or BaseIsOptional. replacesRoomName carries the base room's name only when linkState is Resolved. GET /api/v1/projects/{id}/rooms returns the same three fields.

Error Responses

POST /api/v1/projects

Creates a new project in your organization.

Request Body

Response (201 - Created)

{
    "success": true,
    "data": {
        "projectId": 42
    },
    "message": "Project created successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

PUT /api/v1/projects/{id}

Updates any field on a project in one call — name, job number, personnel, pipeline stage, workflow status, customer link, and the contact, billing (Bill To), shipping (Ship To), and job-site addresses. PATCH is also accepted. Updates are partial: only the fields you include are changed; everything else is left as-is.

Request Body

Example Request

{
    "projectName": "Downtown Office Buildout",
    "stage": "Ordered",
    "status": "Complete",
    "statusNote": "Signed off by client",
    "billToCompany": "Acme Corporation",
    "customerId": 17
}

Response (200 - Success)

{
    "success": true,
    "data": {
        "success": true,
        "projectId": 42,
        "message": "Project updated successfully. Changed: projectName, stage, billToCompany, customerId, status",
        "timestamp": "2024-12-25T12:00:00Z"
    },
    "message": null,
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

DELETE /api/v1/projects/{id}

Permanently deletes a project and all its associated rooms.

PATCH /api/v1/projects/{id}/configuration

Updates project configuration settings including rates, markups, and percentages. Only provided fields will be updated.

Request Body

Example Request

{
    "laborRate": 45.00,
    "laborSell": 125.00,
    "equipmentMarkup": 35,
    "taxRate": 8.25
}

Response (200 - Success)

{
    "success": true,
    "projectId": 42,
    "message": "Project configuration updated successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

POST /api/v1/projects/{id}/estimate

Generates an estimate/proposal document for a project. Returns HTML that can be rendered or converted to PDF.

Request Body

Example Request

{
    "estimateNumber": "EST-2026-001",
    "estimateDate": "2026-02-20",
    "validDays": 30
}

Response (200 - Success)

{
    "success": true,
    "html": "<!DOCTYPE html>...",
    "totalAmount": 45250.00,
    "totalEquipment": 38500.00,
    "totalServices": 5250.00,
    "totalShipping": 1500.00,
    "totalTax": 3733.13,
    "totalWithTax": 48983.13,
    "taxRate": 8.25,
    "estimateNumber": "EST-2026-001",
    "estimateDate": "2026-02-20T00:00:00Z",
    "validUntil": "2026-03-22T00:00:00Z",
    "message": "Estimate generated successfully",
    "timestamp": "2026-02-20T12:00:00Z"
}

POST /api/v1/projects/{id}/duplicate

Creates a complete copy of a project including all rooms and equipment.

Request Body

{
    "newProjectName": "Corporate HQ Upgrade - Copy"
}

GET /api/v1/projects/{id}/rooms

Returns all rooms belonging to the specified project.

POST /api/v1/projects/{id}/rooms

Creates a new room within a project.

Request Body

Example Request

{
    "roomName": "Conference Room A",
    "quantity": 2,
    "isAddAlt": false,
    "laborHours": 8.5,
    "programmerHours": 4.0
}

Response (201 - Created)

{
    "success": true,
    "data": {
        "roomId": 123,
        "projectId": 456
    },
    "message": "Room created successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

PUT /api/v1/projects/{id}/rooms/{roomId}

Updates an existing room within a project.

Request Body

Example Request

{
    "roomName": "Conference Room A (Updated)",
    "quantity": 3,
    "laborHours": 12.0,
    "programmerHours": 6.0
}

Response (200 - Success)

{
    "success": true,
    "roomId": 123,
    "projectId": 456,
    "message": "Room updated successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

POST /api/v1/projects/{projectId}/rooms/{roomId}/duplicate-as-alternate

Duplicates a base room as an optional room that replaces it, so the proposal prices the copy as a difference from the base room. The request has no body.

The new room is named "<room> (Alt)", or "(Alt 2)", "(Alt 3)" and so on when that name is taken. It goes at the end of the room's version, copies the base room's equipment, dividers and room settings (quantity, hours, travel and shipping), is linked to the base room, and joins no Add/Alt group.

Response (201 - Created)

data is the new room, in the same shape the room lists return.

{
    "success": true,
    "data": {
        "id": 131,
        "roomName": "Executive Boardroom (Alt)",
        "laborHours": 12.0,
        "programmerHours": 6.0,
        "quantity": 1,
        "isAddAlt": true,
        "includeTravel": false,
        "travelAmount": null,
        "shippingFlat": null,
        "replacesRoomId": 123,
        "replacesRoomName": "Executive Boardroom",
        "linkState": "Resolved"
    },
    "message": "Room duplicated as alternate \"Executive Boardroom (Alt)\"",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

DELETE /api/v1/projects/{id}/rooms/{roomId}

Permanently deletes a room and all its associated line items.

Response (200 - Success)

{
    "success": true,
    "roomId": 123,
    "projectId": 456,
    "message": "Room deleted successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

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

Returns all equipment line items and section dividers in a room. Each line item carries cadSystemId, the ID of the system the line belongs to (from GET /api/v1/cad-systems), or null when it is unassigned.

productCostEach is null for a line whose 0.00 cost nobody has confirmed, such as a $0.00 saved before Accept $0 cost existed. Sending productCostEach: 0 does not confirm a zero: the line is saved with a 0.00 nobody has confirmed, reads back as null, and counts as unpriced until someone accepts it in the app. Sending 0 for a line whose accepted $0.00 is already stored leaves that acceptance in place. A line item has no separate field that says whether its zero was confirmed.

Response (200 - Success)

{
    "success": true,
    "data": {
        "lineItems": [
            {
                "id": 1,
                "productId": 456,
                "make": "Crestron",
                "model": "TSW-1060",
                "part": "6510483",
                "description": "10.1 in. Touch Screen",
                "quantity": 1,
                "order": 1,
                "productCostEach": 1500.00,
                "laborHours": 2.0,
                "cadSystemId": 3
            }
        ],
        "dividers": [
            {
                "id": 5,
                "categoryName": "Head End",
                "order": 2
            }
        ]
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

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

Adds a new equipment line item to a room.

Request Body

Example Request (by Product ID)

{
    "productId": 456,
    "quantity": 2
}

Example Request (by Make/Model)

{
    "make": "Crestron",
    "model": "TSW-1060",
    "quantity": 1
}

Response (201 - Created)

{
    "success": true,
    "lineItemId": 789,
    "roomId": 123,
    "productId": 456,
    "message": "Line item added successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

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

Reorders a room's line items and section dividers in one call. Line items and dividers share one position space, so the request body carries the room's COMPLETE new row order and the server renumbers it 1..N.

Request Body

{
    "entries": [
        { "type": "divider", "id": 5 },
        { "type": "item", "id": 90 },
        { "type": "item", "id": 91 }
    ],
    "allowEmptySections": false
}

allowEmptySections is optional and defaults to false. It only guards headings that currently have items under them. Left false or omitted, an order that would empty one of those headings is refused with STRANDED_SECTION and nothing changes. Set it to true to deliberately submit such an order. A heading that is already empty is not affected either way — it reorders freely.

Response (200 - Success)

{
    "success": true,
    "data": {
        "itemsReordered": 2,
        "dividersReordered": 1,
        "sequence": [
            { "type": "divider", "id": 5, "order": 1, "label": "Head End" },
            { "type": "item", "id": 90, "order": 2, "label": "Crestron TSW-1060" },
            { "type": "item", "id": 91, "order": 3, "label": "QM75C" }
        ],
        "sections": [
            { "dividerId": 5, "name": "Head End", "itemCount": 2 }
        ],
        "emptySections": [],
        "unlabelledItemCount": 0
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

POST /api/v1/projects/{projectId}/rooms/{roomId}/sections/{dividerId}/move

Moves one whole section, a heading and every row under it, in a single call.

PUT .../order above demands the room's complete new sequence. Building that permutation by hand to shift one section is arithmetic a caller can get wrong. A mistake there can strand a heading or drop a row.

Here the caller states the destination. The server does the slicing, then runs the result through the same reorder engine. The version lock, the exact-cover check and the renumbering all stay unchanged.

The section that moves is named by the route's {dividerId}. The request body only carries where it goes. To move only the heading, leaving its items behind under whatever heading now sits above them, use the divider update endpoint above instead.

Request Body

{
    "placement": "above",
    "targetDividerId": 5
}

Response (200 - Success)

{
    "success": true,
    "data": {
        "dividerId": 12,
        "categoryName": "Video Conferencing",
        "rowsMoved": 2,
        "sequence": [
            { "type": "divider", "id": 12, "order": 1, "label": "Video Conferencing" },
            { "type": "item", "id": 90, "order": 2, "label": "Crestron TSW-1060" },
            { "type": "divider", "id": 5, "order": 3, "label": "Head End" }
        ],
        "sections": [
            { "dividerId": 12, "name": "Video Conferencing", "itemCount": 1 },
            { "dividerId": 5, "name": "Head End", "itemCount": 0 }
        ],
        "emptySections": [
            { "dividerId": 5, "name": "Head End", "itemCount": 0 }
        ],
        "unlabelledItemCount": 0
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

Head End already had no items before this move. A section travels as one block — its heading and its rows together — so a move can never leave a heading newly empty. It is listed in emptySections exactly as it would have been before the call.

Error Responses

{
    "success": false,
    "error": {
        "code": "ROOM_CHANGED",
        "message": "The room changed while the move was being computed — re-read and retry.",
        "details": null
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

POST /api/v1/projects/{projectId}/rooms/{roomId}/dividers

Adds a section divider — a labeled heading that groups the line items beneath it — to a room. Name a target and every row at or below it shifts down one. Anchoring above the first line of an existing section empties that section: it stays a bare heading row on estimates and never becomes a band on proposals, so rename or delete it if you meant to relabel.

Request Body

Omit both aboveLineItemId and order to append the heading past the room's last row.

Response (200 - Success)

{
    "success": true,
    "data": {
        "dividerId": 5,
        "categoryName": "Head End",
        "order": 1,
        "sequence": [
            { "type": "divider", "id": 5, "order": 1, "label": "Head End" },
            { "type": "item", "id": 90, "order": 2, "label": "Crestron TSW-1060" }
        ],
        "sections": [
            { "dividerId": 5, "name": "Head End", "itemCount": 1 }
        ],
        "emptySections": [],
        "unlabelledItemCount": 0
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

PUT /api/v1/projects/{projectId}/rooms/{roomId}/dividers/{dividerId}

Renames and/or repositions a section divider. This moves ONLY the heading row — the items it labeled stay exactly where they are and pick up whatever heading now sits above them. To move a whole section, heading and items together, use POST .../sections/{dividerId}/move above instead. Moving the heading directly above the first line of another section empties that one: it still renders as a bare heading row on estimates, and never becomes a band on proposals.

Request Body

Omit both aboveLineItemId and order to rename the heading without moving it.

Response (200 - Success)

Same shape as the add endpoint above: { dividerId, categoryName, order, sequence, sections, emptySections, unlabelledItemCount }. Same null contract too — sections, emptySections and unlabelledItemCount are null exactly when sequence is null.

Error Responses

DELETE /api/v1/projects/{projectId}/rooms/{roomId}/dividers/{dividerId}

Removes a section divider. The line items it labeled are not deleted — they stay where they are and regroup under whichever heading now sits above them, or lose their heading entirely if there was none.

Response (200 - Success)

{
    "success": true,
    "data": {
        "dividerId": 5,
        "deleted": true
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

No sequence here: a delete removes one row and renumbers nothing, so the rows you already know about keep the orders they had.

Error Responses

Deleting a divider does not touch line-item rows, so it is not blocked by a locked project version.

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

Updates an existing line item in a room.

Request Body

Cable Object Shape

Each entry in the cables array describes one cable assignment. Pricing snapshots are resolved server-side from the current cable type catalog at write time — callers do NOT supply prices.

Example Request

{
    "quantity": 3,
    "productCostEach": 1450.00,
    "laborHours": 2.5,
    "notes": "Mount on east wall, customer providing cable",
    "cables": [
        { "cableTypeId": 7, "pricingMode": "per_foot", "runs": 2, "length": 50 },
        { "cableTypeId": 12, "pricingMode": "per_run", "runs": 1 }
    ]
}

Response (200 - Success)

{
    "success": true,
    "lineItemId": 789,
    "roomId": 123,
    "productId": 456,
    "message": "Line item updated successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

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

Sets or clears the system of one line. The system is part of the line's device tag when the tag pattern uses {System}. Changing it never changes a tag already assigned. A line on a contracted version is locked, as for any other line field.

Path Parameters

Request Body

Example Request

{
    "cadSystemId": 3
}

Response (200 - Success)

{
    "success": true,
    "data": {
        "success": true,
        "lineItemId": 789,
        "roomId": 123,
        "productId": null,
        "make": null,
        "model": null,
        "part": null,
        "description": null,
        "cadSystemId": 3,
        "message": "Line item system set",
        "timestamp": "2026-10-11T15:30:00Z"
    },
    "message": null,
    "timestamp": "2026-10-11T15:30:00Z"
}

When the system is cleared, cadSystemId is null and the inner message is Line item system cleared.

Error Responses

POST /api/v1/projects/{projectId}/items/set-system

Sets one system on many lines of a project in one save, or clears it from all of them. The lines may be in any room. IDs that are not lines of this project are skipped. Every room involved is checked first, so a line in a contracted version refuses the whole request and nothing changes.

Path Parameters

Request Body

Example Request

{
    "itemIds": [789, 790, 815],
    "cadSystemId": 5
}

Response (200 - Success)

{
    "success": true,
    "data": {
        "updated": 3
    },
    "message": "System set on 3 line item(s)",
    "timestamp": "2026-10-11T15:30:00Z"
}

updated is how many of the listed IDs are lines of this project. All of them now carry the system.

Error Responses

DELETE /api/v1/projects/{projectId}/rooms/{roomId}/items/{itemId}

Removes a line item from a room.

Response (200 - Success)

{
    "success": true,
    "lineItemId": 789,
    "roomId": 123,
    "productId": 456,
    "message": "Line item deleted successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

POST /api/v1/projects/{projectId}/device-tags/assign

Creates the units of every equipment line in the project's active version and gives each untagged unit its device tag, the same as Assign Device Tags in the project's Actions menu. A unit is tagged only when every part of the tag pattern can be filled in: a unit whose product has no device category, or whose line has no system while the pattern uses {System}, stays untagged. Existing tags never change, so running it twice assigns nothing the second time. To read the tags, list a line's units; see the Line Item Attributes API.

Path Parameters

Example Request

POST /api/v1/projects/42/device-tags/assign
Authorization: Bearer YOUR_JWT_TOKEN

The request has no body.

Response (200 - Success)

{
    "success": true,
    "data": {
        "unitsSeen": 42,
        "tagsAssigned": 40
    },
    "message": "Units seen 42, tags assigned 40",
    "timestamp": "2026-10-11T15:30:00Z"
}

Error Responses

POST /api/v1/projects/{id}/invoice

Generates an invoice document (HTML) for a project.

Request Body

Example Request

{
    "invoiceNumber": "INV-2024-001",
    "purchaseOrderNumber": "PO-12345",
    "invoiceDate": "2024-12-25",
    "dueDate": "2024-12-25",
    "paymentTerms": "Due on Receipt",
    "showNonEquipment": true,
    "includeTaxes": false,
    "billToCompany": "Acme Corporation",
    "billToAddress": "123 Main St",
    "billToCity": "New York",
    "billToState": "NY",
    "billToZip": "10001"
}

Response (200 - Success)

{
    "success": true,
    "html": "<!DOCTYPE html><html>...</html>",
    "totalAmount": 45750.00,
    "invoiceNumber": "INV-2024-001",
    "message": "Invoice generated successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

Excel Export

Mint a 7-day signed URL to download a project's Excel workbook.

GET /api/v1/projects/{id}/export/excel

Auth: standard API token (Authorization: Bearer avs_...) or JWT.

The endpoint does not return the workbook directly — it returns JSON with a signed URL. GET the URL in a second request to download the .xlsx. The signed download URL does not require an Authorization header (the signature is the authorization), so simple tools like curl or a browser can fetch it.

Query Parameters

All parameters are optional — omit any to fall back to the project's saved default, then the system default. API consumers use the PascalCase names; the MCP-equivalent snake_case names are listed for cross-reference.

Example Request

curl -H "Authorization: Bearer avs_..." \
  "https://yourdomain.com/api/v1/projects/42/export/excel?mode=FullProject&HideNotesColumn=true"

Response (200 - Success)

{
    "url": "https://yourdomain.com/project-excel/<token>?mode=FullProject&HideNotesColumn=true",
    "expires_at": "2026-05-26T14:32:08Z",
    "filename": "Acme HQ - 2026-05-19.xlsx"
}

The signed URL is valid for 7 days. After that the token expires and the URL returns 410 Gone. Cache the URL if you'll download repeatedly within the window; re-mint via the same endpoint once expired.

For the user-workflow guide (what the workbook contains, how saved defaults work, etc.), see Excel Export.