Actions API

Actions are structured work items that follow a lifecycle state machine and support tier-based escalation. They are the backbone of ProBeya’s visual management system — used for corrective actions, CAPAs, improvement tasks, and escalations across AIC/TIER meetings in pharma environments.

Quick Start: Creating a CAPA from a LIMS Deviation

# Create a critical quality action from a LIMS OOS event
curl -X POST https://acme.probeya.com/api/v1/actions \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "boardId": "clx9bd001",
    "title": "CAPA-2026-0194: Investigate root cause of Batch BX-4471 OOS",
    "description": "pH reading 7.8 — upper spec limit 7.4. LIMS ref OOS-2026-0194. Batch held pending investigation.",
    "type": "action",
    "priority": "critical",
    "category": "quality",
    "tierLevel": 1,
    "source": "meeting",
    "responsibleId": "clx9us003",
    "dueDate": "2026-04-20"
  }'

Lifecycle State Machine

Actions follow a controlled lifecycle with validated transitions. The verified state is terminal — once verified, the action is permanently closed.

open ──> assigned ──> in_progress ──> done ──> verified (terminal)
  |          |              |                     ^
  v          v              v                     |
blocked <───+──── blocked  blocked         pending_approval

From	Valid Transitions
`open`	`assigned`, `in_progress`, `blocked`, `done`, `pending_approval`
`assigned`	`in_progress`, `blocked`, `done`, `open`, `pending_approval`
`in_progress`	`blocked`, `done`, `assigned`, `pending_approval`
`blocked`	`in_progress`, `assigned`, `open`
`done`	`verified`, `open`, `pending_approval`
`pending_approval`	`open`, `assigned`, `in_progress`, `done`, `verified`
`verified`	(terminal — no further transitions allowed)

Invalid transitions return a 400 BAD_REQUEST error with the list of valid target statuses.

Endpoints

`GET /api/v1/actions`

List actions with filtering, search, and pagination. Supports cross-board listing when boardId is omitted (returns all actions in the organization).

tRPC: actions.list | Scope: read:actions | Org context: Required

Parameters:

Name	Type	Required	Description
`boardId`	string (query)	No	Filter by board (omit for org-wide)
`status`	string (query)	No	Filter by lifecycle status
`tierLevel`	number (query)	No	Filter by escalation tier (1-4)
`category`	string (query)	No	Filter by SQCDP category
`overdue`	boolean (query)	No	If true, only return actions past due date that are not done/verified
`limit`	number (query)	No	Results per page (default: 50, max: 200)
`offset`	number (query)	No	Pagination offset (default: 0)

# Get all overdue Tier 1 quality actions
curl -H "Authorization: Bearer probeya_sk_live_7f3a..." \
     "https://acme.probeya.com/api/v1/actions?boardId=clx9bd001&category=quality&tierLevel=1&overdue=true"

Response:

{
  "data": [
    {
      "id": "clx9ac001",
      "title": "CAPA-2026-0187: Replace worn conveyor belt section 3",
      "description": "Belt showing visible wear at 40m mark. Risk of particle contamination.",
      "status": "in_progress",
      "priority": "high",
      "type": "action",
      "category": "safety",
      "tierLevel": 1,
      "source": "gemba",
      "boardId": "clx9bd001",
      "responsibleId": "clx9us003",
      "responsibleName": "Dr. Marie Chen",
      "createdById": "clx9us001",
      "dueDate": "2026-04-05T00:00:00.000Z",
      "createdAt": "2026-03-28T09:00:00.000Z",
      "updatedAt": "2026-04-02T16:30:00.000Z"
    },
    {
      "id": "clx9ac002",
      "title": "CAPA-2026-0194: Investigate Batch BX-4471 OOS",
      "description": "pH reading 7.8 — upper spec limit 7.4",
      "status": "assigned",
      "priority": "critical",
      "type": "action",
      "category": "quality",
      "tierLevel": 1,
      "source": "meeting",
      "boardId": "clx9bd001",
      "responsibleId": "clx9us003",
      "responsibleName": "Dr. Marie Chen",
      "createdById": "clx9us001",
      "dueDate": "2026-04-20T00:00:00.000Z",
      "createdAt": "2026-04-13T14:30:00.000Z",
      "updatedAt": "2026-04-13T14:30:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Errors:

Code	Description	Cause	Fix
401	`UNAUTHORIZED`	Missing or invalid authentication	Check your Bearer token
403	`FORBIDDEN`	Insufficient scope	API key needs `read:actions` scope

`POST /api/v1/actions`

Create a new action item. If responsibleId is provided, the status is automatically set to assigned instead of open.

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

Parameters:

Name	Type	Required	Description
`boardId`	string	Yes	The board to create the action on
`title`	string	Yes	Action title
`description`	string	No	Detailed description
`type`	string	No	`action`, `decision`, `issue`, `risk` (default: `action`)
`priority`	string	No	`critical`, `high`, `medium`, `low` (default: `medium`)
`category`	string	No	SQCDP category: `safety`, `quality`, `cost`, `delivery`, `people`, or `custom`
`tierLevel`	number	No	Escalation tier 1-4 (default: 1)
`source`	string	No	Origin: `gemba`, `kaizen`, `meeting`, `other`
`responsibleId`	string	No	User ID for the responsible person
`dueDate`	string	No	ISO 8601 date string

Response:

{
  "data": {
    "id": "clx9ac003",
    "title": "CAPA-2026-0194: Investigate root cause of Batch BX-4471 OOS",
    "status": "assigned",
    "priority": "critical",
    "type": "action",
    "category": "quality",
    "tierLevel": 1,
    "boardId": "clx9bd001",
    "responsibleId": "clx9us003",
    "createdById": "clx9us001",
    "dueDate": "2026-04-20T00:00:00.000Z",
    "createdAt": "2026-04-13T14:30:00.000Z"
  }
}

Side effects:

Logs activity event for audit trail
Sends action_assigned notification to the responsible person
Fires action.created webhook
Triggers board automations
Checks approval workflow trigger conditions (may set status to pending_approval)
Dispatches integration events to connected systems

Errors:

Code	Description	Cause	Fix
400	`BAD_REQUEST`	Invalid type, priority, or category value	Use one of the allowed enum values
401	`UNAUTHORIZED`	Missing or invalid authentication	Check your Bearer token
403	`FORBIDDEN`	Insufficient scope	API key needs `write:actions` scope
404	`NOT_FOUND`	Board not found in this organization	Verify the boardId and org context

Tier-Based Escalation

Actions support a 4-tier escalation model aligned with AIC/TIER meeting structures. Escalation moves the action to a higher tier; de-escalation returns it to a lower tier.

Tier	Scope	Meeting Cadence	Example
1	Team (shop floor)	Daily standup	“Calibrate pH meter #7”
2	Department	Weekly review	“Recurring temperature excursions on Line 2”
3	Site	Bi-weekly	“Capital request for new filling line”
4	Enterprise	Monthly	“Cross-site API supply chain risk”

# Escalate an action from Tier 1 to Tier 2
curl -X POST https://acme.probeya.com/api/v1/actions/clx9ac001/escalate \
  -H "Authorization: Bearer probeya_sk_live_7f3a..." \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Root cause spans multiple areas. Needs department-level coordination."
  }'

Response:

{
  "data": {
    "id": "clx9ac001",
    "tierLevel": 2,
    "previousTierLevel": 1,
    "escalationReason": "Root cause spans multiple areas. Needs department-level coordination.",
    "escalatedAt": "2026-04-13T15:00:00.000Z"
  }
}

Approval Workflows

When approval workflows are configured on a board, certain status transitions trigger an approval process. The action enters pending_approval status and requires designated approvers to accept or reject the change before it takes effect.

Trigger conditions include: critical priority actions, tier escalations, and status transitions to done or verified.

Pharma Integration Scenarios

Connect your LIMS to ProBeya’s Actions API to automatically create CAPA action items when deviations are detected:

// lims-webhook-handler.ts
async function onLimsDeviation(event: LimsDeviationEvent) {
  const action = await fetch("https://acme.probeya.com/api/v1/actions", {
    method: "POST",
    headers: {
      "Authorization": "Bearer probeya_sk_live_7f3a...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      boardId: CAPA_BOARD_ID,
      title: `CAPA-${event.deviationId}: ${event.description}`,
      description: [
        `LIMS Ref: ${event.deviationId}`,
        `Test: ${event.testName}`,
        `Result: ${event.actualValue} ${event.unit}`,
        `Spec: ${event.specMin}-${event.specMax} ${event.unit}`,
        `Batch: ${event.batchId}`,
        `Product: ${event.productName}`,
      ].join("\n"),
      type: "action",
      priority: event.severity === "major" ? "critical" : "high",
      category: "quality",
      tierLevel: 1,
      source: "other",
      dueDate: new Date(Date.now() + 7 * 86400000).toISOString().slice(0, 10),
    }),
  });

  return action.json();
}

Set up a daily check that auto-escalates actions overdue by more than 48 hours:

// cron-escalation.ts — runs daily at 09:00
const overdueActions = await trpc.actions.getOverdue.query({
  boardId: MAIN_BOARD_ID,
});

for (const action of overdueActions) {
  const hoursOverdue = (Date.now() - new Date(action.dueDate).getTime()) / 3600000;

  if (hoursOverdue > 48 && action.tierLevel < 3) {
    await trpc.actions.escalate.mutate({
      id: action.id,
      reason: `Auto-escalated: ${Math.round(hoursOverdue)}h overdue.`,
    });
  }
}

tRPC-Only Action Procedures

Procedure	Description
`actions.update`	Partial update with lifecycle state validation
`actions.delete`	Delete an action item
`actions.getById`	Get a single action with full details
`actions.escalate`	Move an action to a higher tier (with reason for audit trail)
`actions.deescalate`	Return an action to a lower tier
`actions.getEscalated`	Get actions escalated to a given tier
`actions.verify`	Mark an action as verified by a reviewer (terminal state)
`actions.getOverdue`	Get actions past due date that are not done/verified
`actions.getStats`	Aggregate statistics (counts by status, tier, category)

Rate Limiting

Plan	Requests/min	Max results per page
Free	60	50
Starter	120	100
Pro	300	200
Enterprise	600	200

API Reference

REST API

MCP Server

Actions API

Actions API

Quick Start: Creating a CAPA from a LIMS Deviation

Lifecycle State Machine

Endpoints

`GET /api/v1/actions`

`POST /api/v1/actions`

Tier-Based Escalation

Approval Workflows

Pharma Integration Scenarios

tRPC-Only Action Procedures

Rate Limiting

API Reference

REST API

MCP Server

​Actions API

​Quick Start: Creating a CAPA from a LIMS Deviation

​Lifecycle State Machine

​Endpoints

​GET /api/v1/actions

​POST /api/v1/actions

​Tier-Based Escalation

​Approval Workflows

​Pharma Integration Scenarios

​tRPC-Only Action Procedures

​Rate Limiting

Actions API

Quick Start: Creating a CAPA from a LIMS Deviation

Lifecycle State Machine

Endpoints

`GET /api/v1/actions`

`POST /api/v1/actions`

Tier-Based Escalation

Approval Workflows

Pharma Integration Scenarios

tRPC-Only Action Procedures

Rate Limiting