​

Items API

Items are the core work units in ProBeya — cards on a Kanban board. Each item belongs to a board and a group (swimlane), and stores custom field data through the EAV (Entity-Attribute-Value) pattern via item values. In pharma contexts, items represent deviations, batch records, calibration tasks, CAPAs, or any trackable work unit.

All item mutations trigger automations (fire-and-forget), log activity events for the audit trail, and fire webhooks when configured.

​

Quick Start

Create a deviation item, set its priority and status, then move it to the “In Progress” column:

# 1. Create the item
curl -X POST https://acme.probeya.com/api/v1/items \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "boardId": "clx9bd001",
    "groupId": "clx9gr001",
    "name": "DEV-2026-0847: pH excursion on Batch BX-4471"
  }'

# 2. Set priority to Critical and due date
curl -X PUT https://acme.probeya.com/api/v1/items/clx9it010/values \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      { "columnId": "clx9co004", "value": "{\"label\":\"Critical\",\"color\":\"#e2445c\"}" },
      { "columnId": "clx9co003", "value": "2026-04-18" }
    ]
  }'

# 3. Move to "In Progress" group
curl -X POST https://acme.probeya.com/api/v1/items/clx9it010/move \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{ "groupId": "clx9gr002", "sortOrder": 0 }'

​

Endpoints

​

POST /api/v1/items

Create a new item on a board within a specific group.

tRPC: items.create | Scope: write:items | Org context: Required

Parameters:

Response:

{
  "data": {
    "id": "clx9it010",
    "boardId": "clx9bd001",
    "groupId": "clx9gr001",
    "name": "DEV-2026-0847: pH excursion on Batch BX-4471",
    "sortOrder": 5,
    "assigneeId": null,
    "createdById": "clx9us001",
    "organizationId": "clx9abc123def",
    "createdAt": "2026-04-13T08:15:00.000Z",
    "updatedAt": "2026-04-13T08:15:00.000Z"
  }
}

Side effects:

• Triggers item_created automations on the board (fire-and-forget)
• Logs activity event for audit trail
• Fires item.created webhook
• Dispatches integration events to connected systems

Errors:

​

PATCH /api/v1/items/:id

Update an existing item. Partial updates are supported — only include the fields you want to change.

tRPC: items.update | Scope: write:items | Org context: Required

Parameters:

curl -X PATCH https://acme.probeya.com/api/v1/items/clx9it010 \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DEV-2026-0847: pH excursion on Batch BX-4471 (CAPA required)",
    "assigneeId": "clx9us003"
  }'

Response:

{
  "data": {
    "id": "clx9it010",
    "name": "DEV-2026-0847: pH excursion on Batch BX-4471 (CAPA required)",
    "assigneeId": "clx9us003",
    "updatedAt": "2026-04-13T08:20:00.000Z"
  }
}

Side effects:

• Notifies the new assignee (unless self-assignment)
• Sends assignment email notification
• Triggers value_changed automations
• Fires item.updated webhook with changed fields

Errors:

​

DELETE /api/v1/items/:id

Permanently delete an item and all its associated values and comments (cascade). This cannot be undone.

tRPC: items.delete | Scope: write:items | Org context: Required

curl -X DELETE https://acme.probeya.com/api/v1/items/clx9it010 \
  -H "Authorization: Bearer probeya_sk_live_7f3a..."

Response:

{
  "data": {
    "id": "clx9it010",
    "name": "DEV-2026-0847: pH excursion on Batch BX-4471 (CAPA required)"
  }
}

Side effects:

• Cascades deletion to item_values and comments
• Logs activity event with item name for audit trail
• Fires item.deleted webhook

​

PUT /api/v1/items/:id/values

Set multiple custom field values on an item in a single call. Uses upsert semantics — existing values are overwritten, new values are created.

tRPC: items.setValues | Scope: write:items | Org context: Required

Parameters:

Value formats by column type:

curl -X PUT https://acme.probeya.com/api/v1/items/clx9it010/values \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "values": [
      { "columnId": "clx9co001", "value": "{\"label\":\"In Review\",\"color\":\"#fdab3d\"}" },
      { "columnId": "clx9co003", "value": "2026-04-18" },
      { "columnId": "clx9co004", "value": "{\"label\":\"Critical\",\"color\":\"#e2445c\"}" },
      { "columnId": "clx9co005", "value": "Batch BX-4471 — pH 7.8 vs spec 7.0-7.4" }
    ]
  }'

Response:

{
  "data": [
    { "id": "clx9iv040", "itemId": "clx9it010", "columnId": "clx9co001", "value": {"label": "In Review", "color": "#fdab3d"} },
    { "id": "clx9iv041", "itemId": "clx9it010", "columnId": "clx9co003", "value": "2026-04-18" },
    { "id": "clx9iv042", "itemId": "clx9it010", "columnId": "clx9co004", "value": {"label": "Critical", "color": "#e2445c"} },
    { "id": "clx9iv043", "itemId": "clx9it010", "columnId": "clx9co005", "value": "Batch BX-4471 — pH 7.8 vs spec 7.0-7.4" }
  ]
}

​

POST /api/v1/items/:id/move

Move an item to a different group and/or position. Triggers item_moved automations with old and new group context.

tRPC: items.move | Scope: write:items | Org context: Required

curl -X POST https://acme.probeya.com/api/v1/items/clx9it010/move \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{ "groupId": "clx9gr003", "sortOrder": 0 }'

Response:

{
  "data": {
    "id": "clx9it010",
    "groupId": "clx9gr003",
    "sortOrder": 0,
    "updatedAt": "2026-04-13T09:00:00.000Z"
  }
}

​

Pharma Integration Scenarios

# Webhook handler receives LIMS event, creates item in ProBeya
curl -X POST https://acme.probeya.com/api/v1/items \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "boardId": "clx9bd_deviations",
    "groupId": "clx9gr_new",
    "name": "LIMS-OOS-2026-0194: Assay result 103.2% (spec: 95-102%)"
  }'

// MES webhook handler
async function onBatchStarted(batchId: string, product: string) {
  const item = await trpc.items.create.mutate({
    boardId: BATCH_BOARD_ID,
    groupId: IN_PROGRESS_GROUP_ID,
    name: `Batch ${batchId} — ${product}`,
  });

  await trpc.items.setValues.mutate({
    id: item.id,
    values: [
      { columnId: BATCH_ID_COL, value: batchId },
      { columnId: PRODUCT_COL, value: product },
      { columnId: START_DATE_COL, value: new Date().toISOString().slice(0, 10) },
    ],
  });
}

​

Item Visibility Filtering

When a board has an active visibility rule, non-admin users only see items where the person column includes their userId. This is useful for boards where items contain sensitive data (e.g., HR actions, individual performance items). The visibility filter is applied server-side and cannot be bypassed via the API.

​

tRPC-Only Item Procedures

​

Rate Limiting