Action Items API

All endpoints require authentication and action-centre tool permissions.

Data scoping: executives and heads see all action items. All other access levels see only items assigned to them.

List Action Items

GET /api/action-items

Permission: action-centre:view

Query parameters:

Param	Type	Description
`source_module`	string	Filter by source module (comma-separated)
`source_type`	string	Filter by source type (comma-separated)
`urgency`	string	Filter by urgency: `overdue`, `today`, `this_week`, `normal`
`company_id`	string	Filter by company
`project_id`	string	Filter by project
`assigned_to`	string	Filter by assigned user (exec/head only)
`is_completed`	string	`0` for open (default), `1` for completed
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50, max: 100)

Results are ordered by urgency (overdue first), then due date ascending, then creation date descending.

Response: { action_items } — each item includes assigned_user_name, assigned_user_picture, contact_first_name, and contact_last_name.

Action Item Counts

GET /api/action-items/counts

Permission: action-centre:view

Returns a breakdown of open action items by module and urgency.

Response:

{
  "overdue": 0,
  "today": 0,
  "this_week": 0,
  "total": 0,
  "by_module": {
    "relationships": 5,
    "slack": 3,
    "gmail": 2
  }
}

User Preferences

Get Preferences

GET /api/action-items/preferences

Permission: action-centre:view

Response: { preferences } — array of per-module visibility settings.

Save Preferences

PUT /api/action-items/preferences

Permission: action-centre:update

Body:

{
  "preferences": [
    {
      "source_module": "relationships",
      "is_visible": 1,
      "show_in_feed": 1,
      "show_work_board": 1
    }
  ]
}

Response: { ok: true }

Create Action Item

POST /api/action-items

Permission: action-centre:update

Creates a manual action item with source_module = 'manual'.

Body:

Field	Type	Required	Description
`title`	string	Yes	Action item title
`description`	string	No	Description
`company_id`	string	No	Linked company
`contact_id`	string	No	Linked contact
`deal_id`	string	No	Linked deal
`project_id`	string	No	Linked project
`assigned_to`	string	No	Assigned user ID (defaults to current user)
`due_date`	string	No	Due date (YYYY-MM-DD) — urgency is auto-calculated
`notes`	string	No	Additional notes

Response: { action_item } (201)

Update Action Item

PATCH /api/action-items/:id

Permission: action-centre:update

Body: Any of: title, description, assigned_to, due_date, notes, urgency. If due_date changes and urgency is not explicitly set, urgency is recalculated automatically.

Response: { action_item }

Complete Action Item

POST /api/action-items/:id/complete

Permission: action-centre:update

Marks the action item as completed. Side effects:

If sourced from relationships, marks the corresponding relationship_auto_actions record as done.
If sourced from slack or gmail, notifies the Actions Agent to unstar the item on the source platform.

Response: { ok: true }

Delete Action Item

DELETE /api/action-items/:id

Permission: action-centre:manage

Only manually created action items can be deleted. System-generated items return a 400 error.

Response: { ok: true }

Action Centre (Combined Endpoint)

GET /api/action-items/centre

Permission: action-centre:view

Single page-load endpoint that returns action items, counts, preferences, and current sprint data in parallel.

Query parameters:

Param	Type	Description
`sprint_id`	string	Specific sprint ID (defaults to detecting active sprint for the user)

Response:

{
  "action_items": [],
  "counts": {
    "overdue": 0,
    "today": 0,
    "this_week": 0,
    "total": 0,
    "by_module": {}
  },
  "preferences": [],
  "show_work_board": true,
  "current_sprint": {
    "id": "string",
    "project_id": "string",
    "name": "string",
    "start_date": "string",
    "end_date": "string",
    "project_name": "string",
    "company_name": "string"
  },
  "sprint_tasks": [],
  "backlog_tasks": [],
  "sprint_adjacent": {
    "previous": { "id": "string", "name": "string" },
    "next": { "id": "string", "name": "string" }
  }
}

Sprint detection: finds the most recent active sprint across projects the user owns or is a member of. Sprint tasks include full status/priority/type config labels and colors, assignee info, and project/company names.