Connected Workers Departments

The Connected Workers Departments API lets you manage the organizational units — departments — that work requests and work are assigned to. A department is a lightweight record: it has a Name and belongs to the workspace.

• Departments table — a table. Has a name, a key, and rows.
• Column — a field definition on the table (name, key, data type, ordering, display behavior). A Departments table needs only a Name text column marked isTitle.
• Item — a row: an object mapping each column's key to its value ({ "name": "Maintenance" }). A department is that row, identified by its Name.

Workspace 7
└── Departments table 16 "Departments"  (key: departments)
    ├── Columns:  Name (key: name, text, title)
    └── Items (rows):
          { "id": 2001, "name": "Maintenance" }
          { "id": 2002, "name": "Operations" }

Departments are record-native, like locations: there is effectively one Departments table per workspace, and a department is a record identified by its Name (its isTitle column) — no separate primary-key code column is required. Work Requests and work can be filed against a department. See the Users guide, the Locations guide, the Assets guide, and the Lists guide for the other CW table entities.

Base URL & auth

Every endpoint is scoped to a workspace and served under:

https://api.treedis.com/v2/api/workspaces/{workspaceId}/cw/departments

All endpoints require authentication (OAuth2 Bearer token or API key), and the caller must have access to the workspace. workspaceId is always a numeric ID. An API key is bound to a single workspace and can only address its own.

Keys — address tables and columns by id or slug

Tables and columns each have a key — a URL‑safe slug (lowercase, no spaces), generated automatically from the name on create (or passed). Keys are unique within their scope and never all‑numeric.

• Anywhere a path takes {columnId}, pass either the numeric id or the key (e.g. …/cw/departments/columns/name). A purely numeric value is an id; anything else is a key. The Departments table itself is not addressed by id — it is the single per-workspace table reached directly under …/cw/departments.
• Rows reference columns by key — the property names in a row object are column keys.
• Items (rows) have no key — address them by their numeric id.

Endpoints

Departments is a single per-workspace table. Like locations (and unlike assets and lists, where you manage many tables), every workspace has one Departments table — it is record-native. There is no table-id segment: GET on the collection returns that one table with its columns and items nested, and every sub-resource hangs directly off …/cw/departments (no {tableId}). There is no GET/PUT/DELETE /{tableId} and no /{tableId}/bulk; create and upsert departments through the collection POST and POST /bulk.

GET on the collection returns the table with its columns and items nested. The /columns and /items sub-resources return those slices on their own.

Creating & upserting departments

The one-shot call is POST /cw/departments/bulk — it defines the columns and pushes the department rows in a single request. The envelope key is departments. A Departments table needs only a Name text column marked isTitle: true; each item carries that title.

curl -X POST "https://api.treedis.com/v2/api/workspaces/7/cw/departments/bulk" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "departments": [
      {
        "name": "Departments", "key": "departments", "status": "active",
        "columns": [ { "name": "Name", "type": "text", "isTitle": true } ],
        "items": [
          { "name": "Maintenance" },
          { "name": "Operations" }
        ]
      }
    ]
  }'

Each surface uses its own batch envelope key — departments here, locations for the Locations surface, assets for the Assets surface, lists for the Lists surface.

Batch insert by type

One endpoint for every surface: POST /v2/api/workspaces/{workspaceId}/cw/bulk takes a tables array where each table carries its own type — location, asset, list, department, or user — alongside its columns and rows. Use type: department to create departments through the unified call; it is equivalent to posting to /cw/departments/bulk.

curl -X POST "https://api.treedis.com/v2/api/workspaces/7/cw/bulk" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": [
      {
        "type": "department",
        "name": "Departments", "key": "departments", "status": "active",
        "columns": [ { "name": "Name", "type": "text", "isTitle": true } ],
        "items": [
          { "name": "Maintenance" },
          { "name": "Operations" }
        ]
      }
    ]
  }'

Columns

Define the fields of the table. Create takes no column id; the key is derived from the name (or pass your own, unique within the table). A Departments table typically has just the Name title column.

• GET / POST /v2/api/workspaces/{workspaceId}/cw/departments/columns
• GET / PUT / DELETE …/columns/{columnId}

Column types (type): text · number · date · checkbox · hierarchyParent (links a row to a parent row) · reference (links to another table/entity) · locationTag (ties the value to a tour location/tag) · space (a space/environment) · tagStatus (a status tag).

curl -X POST "https://api.treedis.com/v2/api/workspaces/7/cw/departments/columns" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Name", "type": "text", "isTitle": true, "isRequired": true, "status": "active", "isVisible": true }'

Items (rows)

An item is a row — an object mapping each column's key to its value. A department row is identified by its name. Responses add the row id.

• GET / POST /v2/api/workspaces/{workspaceId}/cw/departments/items
• GET / PUT / DELETE …/items/{itemId}

# insert a department row
curl -X POST "https://api.treedis.com/v2/api/workspaces/7/cw/departments/items" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Maintenance" }'

{
  "success": true,
  "code": 200,
  "message": "Item created successfully",
  "data": { "id": 2001, "name": "Maintenance" }
}

A PUT on …/items/{itemId} updates the row's values; send only the columns you want to change. List rows with ?filter[name]=Maintenance, ?page / ?limit, and ?sortBy / ?sortOrder.

Filing work requests against a department

Work Requests can be anchored to a department. Create a work request at the workspace and address the department by department — the department's title (its Name). Treedis finds that department record and files the work request against it. department can be combined with a location and/or an asset (assetKey + asset) on the same work request.

curl -X POST "https://api.treedis.com/v2/api/workspaces/7/work-requests" \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "R400-20-FL-1001",
    "department": "Maintenance",
    "title": "Pump leak",
    "status": "open",
    "priority": "high"
  }'

See the Work Requests guide for the full workflow, and Work Orders for turning a request into planned work.

Delete & truncate

• Delete a single record — DELETE …/departments/columns/{columnId} or …/departments/items/{itemId}.
• Truncate items — POST …/departments/items/truncate removes all rows, keeping the table and its columns.

curl -X POST "https://api.treedis.com/v2/api/workspaces/7/cw/departments/items/truncate" \
  -H "Authorization: Bearer your-access-token"

Truncate responses report how many rows were removed (data.deleted).

Errors

Errors use the same envelope with success: false and an optional details object:

{
  "success": false,
  "code": 404,
  "message": "Department not found",
  "details": {
    "error": "No department matches the given id or key"
  }
}

See the Connected Workers Departments tag in the API Reference for the full request and response schemas.