Device Tags API

Read and replace the device category list and the system list that device tags are built from.

Every physical unit on a project can carry a device tag such as DISP-003, built from your company's tag pattern. The pattern draws on two lists: device categories, which classify catalog products (Display / DISP), and systems, which equipment lines belong to (Audio Visual / AV). This page covers the two lists. For how tags work in the app, see Device Tags.

Where the Other Device Tag Endpoints Are

The tag pattern, sequence digits and numbering mode are set on the Device Tags card in Global Config; they have no endpoint. The CAD block library, the CAD tag catalog and a project's CAD units are in the CAD Blocks API.

Rules for Both Lists

• A name is trimmed, required, at most 60 characters, and unique in its list ignoring letter case.
• An abbreviation is trimmed and upper-cased, then must be 1 to 8 letters or digits (A-Z, 0-9). It is unique in its list.
• order is the row's 1-based position. A PUT sets it from the order of the items you send.
• A PUT replaces the whole list in one save: an item with an id updates that row, an item without one creates a row, and every row you leave out is deleted. Nothing is saved when any item is refused.
• Changing a name or an abbreviation affects only tags assigned afterwards. Existing tags never change.
• The first read of a list that has no rows fills it with the default list. A PUT with an empty array therefore deletes every row, and the next GET returns the defaults.

GET /api/v1/cad-categories

Returns the device category list, in order.

Example Request

GET /api/v1/cad-categories
Authorization: Bearer YOUR_JWT_TOKEN

Response (200 - Success)

{
    "success": true,
    "data": [
        {
            "id": 7,
            "name": "Display",
            "abbreviation": "DISP",
            "isDrawable": true,
            "expectedOn": ["plan", "elevation"],
            "order": 1,
            "updatedAt": "2026-10-11T15:30:00Z",
            "cadBlocks": [
                { "view": "plan", "blockId": 9, "visibilityState": "TOP" }
            ]
        },
        {
            "id": 34,
            "name": "Cable",
            "abbreviation": "CBL",
            "isDrawable": false,
            "expectedOn": [],
            "order": 28,
            "updatedAt": "2026-10-11T15:30:00Z",
            "cadBlocks": []
        }
    ],
    "message": null,
    "timestamp": "2026-10-11T15:30:00Z"
}

PUT /api/v1/cad-categories

Replaces the whole device category list and returns the list as saved. A category you leave out is deleted, and the products that had it become unclassified; their existing device tags stay.

Request Body

Category Item

Example Request

{
    "categories": [
        { "id": 7, "name": "Display", "abbreviation": "DISP", "expectedOn": ["plan", "elevation"], "cadBlocks": [ { "view": "plan", "blockId": 9, "visibilityState": "TOP" } ] },
        { "id": 34, "name": "Cable", "abbreviation": "CBL", "isDrawable": false },
        { "name": "Lectern", "abbreviation": "LECT" }
    ]
}

Response (200 - Success)

{
    "success": true,
    "data": [
        { "id": 7, "name": "Display", "abbreviation": "DISP", "isDrawable": true, "expectedOn": ["plan", "elevation"], "order": 1, "updatedAt": "2026-10-11T15:30:00Z", "cadBlocks": [ { "view": "plan", "blockId": 9, "visibilityState": "TOP" } ] },
        { "id": 34, "name": "Cable", "abbreviation": "CBL", "isDrawable": false, "expectedOn": [], "order": 2, "updatedAt": "2026-10-11T15:42:00Z", "cadBlocks": [] },
        { "id": 61, "name": "Lectern", "abbreviation": "LECT", "isDrawable": true, "expectedOn": [], "order": 3, "updatedAt": "2026-10-11T15:42:00Z", "cadBlocks": [] }
    ],
    "message": "Device categories saved",
    "timestamp": "2026-10-11T15:42:00Z"
}

Error Responses

GET /api/v1/cad-systems

Returns the system list, in order. The default list is Audio Visual / AV, Information Technology / IT and Security / SEC.

Example Request

GET /api/v1/cad-systems
Authorization: Bearer YOUR_JWT_TOKEN

Response (200 - Success)

{
    "success": true,
    "data": [
        { "id": 3, "name": "Audio Visual", "abbreviation": "AV", "order": 1, "updatedAt": "2026-10-11T15:30:00Z" },
        { "id": 4, "name": "Information Technology", "abbreviation": "IT", "order": 2, "updatedAt": "2026-10-11T15:30:00Z" },
        { "id": 5, "name": "Security", "abbreviation": "SEC", "order": 3, "updatedAt": "2026-10-11T15:30:00Z" }
    ],
    "message": null,
    "timestamp": "2026-10-11T15:30:00Z"
}

The fields are those of a category without isDrawable and expectedOn. Equipment lines carry the system's id as cadSystemId.

PUT /api/v1/cad-systems

Replaces the whole system list and returns the list as saved. A system you leave out is deleted, and every line that had it, in every version of every project, becomes unassigned; existing device tags stay.

Request Body

Example Request

{
    "systems": [
        { "id": 3, "name": "Audio Visual", "abbreviation": "AV" },
        { "id": 5, "name": "Security", "abbreviation": "SEC" },
        { "name": "Lighting", "abbreviation": "LTG" }
    ]
}

Response (200 - Success)

{
    "success": true,
    "data": [
        { "id": 3, "name": "Audio Visual", "abbreviation": "AV", "order": 1, "updatedAt": "2026-10-11T15:30:00Z" },
        { "id": 5, "name": "Security", "abbreviation": "SEC", "order": 2, "updatedAt": "2026-10-11T15:42:00Z" },
        { "id": 9, "name": "Lighting", "abbreviation": "LTG", "order": 3, "updatedAt": "2026-10-11T15:42:00Z" }
    ],
    "message": "Systems saved",
    "timestamp": "2026-10-11T15:42:00Z"
}

Error Responses

MCP clients reach the same lists with list_cad_categories and list_cad_systems; see the MCP Server page.