---
title: "Pending actions API reference"
canonical_url: https://zentrik.ai/docs/api/huddle-actions
markdown_url: https://zentrik.ai/docs/api/huddle-actions.md
last_reviewed: 2026-10-22
---

# Pending actions API reference

Automate the Huddle Pending actions widget with a workspace API key. Actions belong to a team and carry across days until resolved. Use huddle-actions:read for reads, huddle-actions:write for creation, edits and resolution, and huddle-actions:delete for deletion. These grants cover all teams in the key’s workspace. Writes require the Huddle date to sync; they update live actions even if no daily Huddle exists. Historical snapshots change only when explicitly targeted or refreshed. Unknown fields are rejected. Find team IDs through GET /external/v1/teams. Find owner user IDs through GET /external/v1/teams/:teamId/members with teams:read, then send the selected userId as ownerUserId. Omit ownership to create unassigned actions.

- Human reference: https://zentrik.ai/docs/api/huddle-actions
- Complete Markdown index: https://zentrik.ai/docs/api/index.md
- Base URL: `https://zentrik.ai/api`
- Authentication: `Authorization: Bearer YOUR_API_KEY`
- Shared pagination and rate limits: https://zentrik.ai/docs/api/index.md#shared-conventions

## GET /external/v1/huddle-actions — List pending actions

Operation ID: `list-huddle-actions`

Read the team’s live action records, including actions created in the UI or accepted from a transcript. By default only unresolved actions are returned. The response body is an array; X-Total-Count, X-Limit, X-Offset and X-Has-More headers describe the filtered result. Ordering follows the team action list: resolution time ascending, then due date ascending, then creation time descending, with null resolution times last when status=all. Concurrent changes and tied timestamps can shift offset pages. Reads use Cache-Control: private, no-store.

Required API key scopes: `huddle-actions:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | UUID | Yes | Team in the API key’s workspace (query parameter). Use GET /external/v1/teams to find team IDs. |
| `status` | string | No | open (default), resolved or all. |
| `type` | string | No | Filter by blocker, decision or follow_up. |
| `limit` | integer | No | Page size, 1–100. Default: 20. |
| `offset` | integer | No | Records to skip, 0–1,000,000. Default: 0. |

### Example request

```curl
curl -X GET 'https://zentrik.ai/api/external/v1/huddle-actions?teamId=33333333-3333-4333-8333-333333333333' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Matching actions and pagination headers; no matches returns an empty array. | — |
| 400 | Invalid input | Invalid UUID or calendar date, unsupported field, empty action, invalid type, or owner outside the selected team. | — |
| 401 | Unauthorized | API key is missing, invalid, expired or revoked. | — |
| 403 | Missing scope | The API key does not have this endpoint’s scope. | — |
| 404 | Not found | Team is outside the key’s workspace, or action is outside the selected team. | — |
| 429 | Rate limited | Wait for the Retry-After interval before retrying. | — |

### Example response

```json
[
  {
    "id": "44444444-4444-4444-8444-444444444444",
    "workspaceId": "22222222-2222-4222-8222-222222222222",
    "teamId": "33333333-3333-4333-8333-333333333333",
    "item": "Confirm the rollout owner",
    "type": "follow_up",
    "ownerUserId": null,
    "expectedResolutionDate": "2026-10-23",
    "resolvedAt": null,
    "createdInHuddleId": null,
    "createdAt": "2026-10-21T09:00:00.000Z",
    "updatedAt": "2026-10-21T09:00:00.000Z"
  }
]
```

---

## GET /external/v1/huddle-actions/:id — Get a pending action

Operation ID: `get-huddle-action`

Retrieve a live action in the selected team. Returns ownerUserId, not a joined user profile. createdInHuddleId is nullable and records the Huddle present at creation; it is not the last edited Huddle. Reads use Cache-Control: private, no-store.

Required API key scopes: `huddle-actions:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Pending action ID (path parameter). |
| `teamId` | UUID | Yes | Team in the API key’s workspace (query parameter). Use GET /external/v1/teams to find team IDs. |

### Example request

```curl
curl -X GET 'https://zentrik.ai/api/external/v1/huddle-actions/44444444-4444-4444-8444-444444444444?teamId=33333333-3333-4333-8333-333333333333' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | The action record. | — |
| 400 | Invalid input | Invalid UUID or calendar date, unsupported field, empty action, invalid type, or owner outside the selected team. | — |
| 401 | Unauthorized | API key is missing, invalid, expired or revoked. | — |
| 403 | Missing scope | The API key does not have this endpoint’s scope. | — |
| 404 | Not found | Team is outside the key’s workspace, or action is outside the selected team. | — |
| 429 | Rate limited | Wait for the Retry-After interval before retrying. | — |

### Example response

```json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "workspaceId": "22222222-2222-4222-8222-222222222222",
  "teamId": "33333333-3333-4333-8333-333333333333",
  "item": "Confirm the rollout owner",
  "type": "follow_up",
  "ownerUserId": null,
  "expectedResolutionDate": "2026-10-23",
  "resolvedAt": null,
  "createdInHuddleId": null,
  "createdAt": "2026-10-21T09:00:00.000Z",
  "updatedAt": "2026-10-21T09:00:00.000Z"
}
```

---

## POST /external/v1/huddle-actions — Create a pending action

Operation ID: `create-huddle-action`

Add an unresolved action and sync the selected day’s existing Huddle. This is a direct manual action, with no transcript analysis or review step. POST is not idempotent: each successful call creates a new record. Store the returned ID. After an uncertain timeout, reconcile against the action list before retrying to avoid duplicates. Serialize writes for the same team and date to avoid overlapping snapshot updates.

Required API key scopes: `huddle-actions:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | UUID | Yes | Team in the API key’s workspace (query parameter). Use GET /external/v1/teams to find team IDs. |
| `date` | string | Yes | YYYY-MM-DD (query parameter). Update the pending-action snapshot and comparisons in this day’s existing Huddle. Does not create a Huddle. Use the date currently displayed in the widget; older snapshots are not updated automatically. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `item` | string | Yes | Action text, 1–1,000 characters after trimming. |
| `type` | string | Yes | blocker, decision or follow_up. |
| `ownerUserId` | UUID \| null | No | Use userId from GET /external/v1/teams/:teamId/members (teams:read scope). The owner must still belong to this team when saved. Omit or use null to create an unassigned action; null clears an existing owner on PATCH. |
| `expectedResolutionDate` | string \| null | No | Due date, YYYY-MM-DD. Omit or use null for no due date on create; null clears it on PATCH. |

### Example request

```curl
curl -X POST 'https://zentrik.ai/api/external/v1/huddle-actions?teamId=33333333-3333-4333-8333-333333333333&date=2026-10-21' -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"item":"Confirm the rollout owner","type":"follow_up","expectedResolutionDate":"2026-10-23"}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 201 | Created | The new action. createdInHuddleId is null if no Huddle exists for the date. | — |
| 400 | Invalid input | Invalid UUID or calendar date, unsupported field, empty action, invalid type, or owner outside the selected team. | — |
| 401 | Unauthorized | API key is missing, invalid, expired or revoked. | — |
| 403 | Missing scope | The API key does not have this endpoint’s scope. | — |
| 404 | Not found | Team is outside the key’s workspace, or action is outside the selected team. | — |
| 429 | Rate limited | Wait for the Retry-After interval before retrying. | — |

### Example response

```json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "workspaceId": "22222222-2222-4222-8222-222222222222",
  "teamId": "33333333-3333-4333-8333-333333333333",
  "item": "Confirm the rollout owner",
  "type": "follow_up",
  "ownerUserId": null,
  "expectedResolutionDate": "2026-10-23",
  "resolvedAt": null,
  "createdInHuddleId": null,
  "createdAt": "2026-10-21T09:00:00.000Z",
  "updatedAt": "2026-10-21T09:00:00.000Z"
}
```

---

## PATCH /external/v1/huddle-actions/:id — Update a pending action

Operation ID: `update-huddle-action`

Change only the supplied fields and sync the selected date’s existing Huddle. Send at least one supported field. Omitted fields remain unchanged. item and type cannot be null. Resolution is managed through the resolve and reopen routes.

Required API key scopes: `huddle-actions:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Pending action ID (path parameter). |
| `teamId` | UUID | Yes | Team in the API key’s workspace (query parameter). Use GET /external/v1/teams to find team IDs. |
| `date` | string | Yes | YYYY-MM-DD (query parameter). Update the pending-action snapshot and comparisons in this day’s existing Huddle. Does not create a Huddle. Use the date currently displayed in the widget; older snapshots are not updated automatically. |

### JSON request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `item` | string | No | Action text, 1–1,000 characters after trimming. |
| `type` | string | No | blocker, decision or follow_up. |
| `ownerUserId` | UUID \| null | No | Use userId from GET /external/v1/teams/:teamId/members (teams:read scope). The owner must still belong to this team when saved. Omit or use null to create an unassigned action; null clears an existing owner on PATCH. |
| `expectedResolutionDate` | string \| null | No | Due date, YYYY-MM-DD. Omit or use null for no due date on create; null clears it on PATCH. |

### Example request

```curl
curl -X PATCH 'https://zentrik.ai/api/external/v1/huddle-actions/44444444-4444-4444-8444-444444444444?teamId=33333333-3333-4333-8333-333333333333&date=2026-10-21' -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"expectedResolutionDate":null}'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Updated | The updated action record. | — |
| 400 | Invalid input | Invalid UUID or calendar date, unsupported field, empty action, invalid type, or owner outside the selected team. | — |
| 401 | Unauthorized | API key is missing, invalid, expired or revoked. | — |
| 403 | Missing scope | The API key does not have this endpoint’s scope. | — |
| 404 | Not found | Team is outside the key’s workspace, or action is outside the selected team. | — |
| 429 | Rate limited | Wait for the Retry-After interval before retrying. | — |

### Example response

```json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "workspaceId": "22222222-2222-4222-8222-222222222222",
  "teamId": "33333333-3333-4333-8333-333333333333",
  "item": "Confirm the rollout owner",
  "type": "follow_up",
  "ownerUserId": null,
  "expectedResolutionDate": null,
  "resolvedAt": null,
  "createdInHuddleId": null,
  "createdAt": "2026-10-21T09:00:00.000Z",
  "updatedAt": "2026-10-21T09:00:00.000Z"
}
```

---

## POST /external/v1/huddle-actions/:id/resolve — Resolve a pending action

Operation ID: `resolve-huddle-action`

Resolve an action and sync the selected date’s existing Huddle. No request body is needed; an empty object is accepted. Sequential retries preserve the first resolvedAt timestamp until the action is reopened. You cannot supply your own resolution timestamp.

Required API key scopes: `huddle-actions:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Pending action ID (path parameter). |
| `teamId` | UUID | Yes | Team in the API key’s workspace (query parameter). Use GET /external/v1/teams to find team IDs. |
| `date` | string | Yes | YYYY-MM-DD (query parameter). Update the pending-action snapshot and comparisons in this day’s existing Huddle. Does not create a Huddle. Use the date currently displayed in the widget; older snapshots are not updated automatically. |

### Example request

```curl
curl -X POST 'https://zentrik.ai/api/external/v1/huddle-actions/44444444-4444-4444-8444-444444444444/resolve?teamId=33333333-3333-4333-8333-333333333333&date=2026-10-21' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Resolved | The action with its server-set resolvedAt timestamp. | — |
| 400 | Invalid input | Invalid UUID or calendar date, unsupported field, empty action, invalid type, or owner outside the selected team. | — |
| 401 | Unauthorized | API key is missing, invalid, expired or revoked. | — |
| 403 | Missing scope | The API key does not have this endpoint’s scope. | — |
| 404 | Not found | Team is outside the key’s workspace, or action is outside the selected team. | — |
| 429 | Rate limited | Wait for the Retry-After interval before retrying. | — |

### Example response

```json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "workspaceId": "22222222-2222-4222-8222-222222222222",
  "teamId": "33333333-3333-4333-8333-333333333333",
  "item": "Confirm the rollout owner",
  "type": "follow_up",
  "ownerUserId": null,
  "expectedResolutionDate": "2026-10-23",
  "resolvedAt": "2026-10-21T10:00:00.000Z",
  "createdInHuddleId": null,
  "createdAt": "2026-10-21T09:00:00.000Z",
  "updatedAt": "2026-10-21T09:00:00.000Z"
}
```

---

## POST /external/v1/huddle-actions/:id/reopen — Reopen a pending action

Operation ID: `reopen-huddle-action`

Clear resolvedAt and sync the selected date’s existing Huddle. Reopening an open action leaves it open. No request body is needed; an empty object is accepted.

Required API key scopes: `huddle-actions:write`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Pending action ID (path parameter). |
| `teamId` | UUID | Yes | Team in the API key’s workspace (query parameter). Use GET /external/v1/teams to find team IDs. |
| `date` | string | Yes | YYYY-MM-DD (query parameter). Update the pending-action snapshot and comparisons in this day’s existing Huddle. Does not create a Huddle. Use the date currently displayed in the widget; older snapshots are not updated automatically. |

### Example request

```curl
curl -X POST 'https://zentrik.ai/api/external/v1/huddle-actions/44444444-4444-4444-8444-444444444444/reopen?teamId=33333333-3333-4333-8333-333333333333&date=2026-10-21' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Reopened | The action with resolvedAt: null. | — |
| 400 | Invalid input | Invalid UUID or calendar date, unsupported field, empty action, invalid type, or owner outside the selected team. | — |
| 401 | Unauthorized | API key is missing, invalid, expired or revoked. | — |
| 403 | Missing scope | The API key does not have this endpoint’s scope. | — |
| 404 | Not found | Team is outside the key’s workspace, or action is outside the selected team. | — |
| 429 | Rate limited | Wait for the Retry-After interval before retrying. | — |

### Example response

```json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "workspaceId": "22222222-2222-4222-8222-222222222222",
  "teamId": "33333333-3333-4333-8333-333333333333",
  "item": "Confirm the rollout owner",
  "type": "follow_up",
  "ownerUserId": null,
  "expectedResolutionDate": "2026-10-23",
  "resolvedAt": null,
  "createdInHuddleId": null,
  "createdAt": "2026-10-21T09:00:00.000Z",
  "updatedAt": "2026-10-21T09:00:00.000Z"
}
```

---

## DELETE /external/v1/huddle-actions/:id — Delete a pending action

Operation ID: `delete-huddle-action`

Permanently remove an action and sync the selected date’s existing Huddle. Other saved daily snapshots retain their saved content. Repeating the deletion returns 404. The write scope alone does not allow deletion.

Required API key scopes: `huddle-actions:delete`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Pending action ID (path parameter). |
| `teamId` | UUID | Yes | Team in the API key’s workspace (query parameter). Use GET /external/v1/teams to find team IDs. |
| `date` | string | Yes | YYYY-MM-DD (query parameter). Update the pending-action snapshot and comparisons in this day’s existing Huddle. Does not create a Huddle. Use the date currently displayed in the widget; older snapshots are not updated automatically. |

### Example request

```curl
curl -X DELETE 'https://zentrik.ai/api/external/v1/huddle-actions/44444444-4444-4444-8444-444444444444?teamId=33333333-3333-4333-8333-333333333333&date=2026-10-21' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Deleted | The deleted action ID. | — |
| 400 | Invalid input | Invalid UUID or calendar date, unsupported field, empty action, invalid type, or owner outside the selected team. | — |
| 401 | Unauthorized | API key is missing, invalid, expired or revoked. | — |
| 403 | Missing scope | The API key does not have this endpoint’s scope. | — |
| 404 | Not found | Team is outside the key’s workspace, or action is outside the selected team. | — |
| 429 | Rate limited | Wait for the Retry-After interval before retrying. | — |

### Example response

```json
{
  "id": "44444444-4444-4444-8444-444444444444"
}
```