---
title: "Team Huddles API reference"
canonical_url: https://zentrik.ai/docs/api/huddles
markdown_url: https://zentrik.ai/docs/api/huddles.md
last_reviewed: 2026-09-08
---

# Team Huddles API reference

Read daily Team Huddle history with a workspace API key granted huddles:read or initiatives:read. Existing initiative-read keys work without replacement or scope updates. Both grants cover all teams in the workspace; huddles:read lets new keys request only huddle access. Initiative Huddle note sessions are a separate workflow. Each daily record retains its latest saved state, up to ten conversation sources, and up to 100,000 characters per pasted source.

- Human reference: https://zentrik.ai/docs/api/huddles
- 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/huddles — List Team Huddle history

Operation ID: `list-team-huddles`

List saved daily huddles across the API key’s workspace, newest date first, with ID descending as the tie-breaker. Returns identity, timestamps and version metadata only. The body is an array; X-Total-Count, X-Limit, X-Offset and X-Has-More headers describe pagination. Concurrent creation or deletion can shift offset pages. Reads never create or refresh huddles. Existing keys with initiatives:read also authorize this endpoint; either scope is sufficient.

Required API key scopes: `huddles:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `teamId` | UUID | No | Filter to one team. Omit to include all teams in the API key’s workspace. |
| `from` | string | No | Inclusive huddle date, YYYY-MM-DD. Filters the saved calendar date, not generatedAt. |
| `to` | string | No | Inclusive huddle date, YYYY-MM-DD; must be on or after from. Set from and to to the same date for one day. |
| `limit` | integer | No | Page size, 1–100. Default: 20. |
| `offset` | integer | No | Matching records to skip. Default: 0. |

### Example request

```curl
curl 'https://zentrik.ai/api/external/v1/huddles?from=2026-09-03&to=2026-09-03&limit=20&offset=0' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Shallow records and pagination headers. No matches or an exhausted page returns an empty array. | — |
| 400 | Invalid query | Invalid UUID, date, date range, pagination or unsupported parameter. | — |

### Example response

```json
[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "workspaceId": "22222222-2222-4222-8222-222222222222",
    "teamId": "33333333-3333-4333-8333-333333333333",
    "huddleDate": "2026-09-03",
    "schemaVersion": 4,
    "refreshRevision": 1,
    "generatedAt": "2026-09-03T09:00:00.000Z",
    "generatedByUserId": null,
    "createdAt": "2026-09-03T09:00:00.000Z",
    "updatedAt": "2026-09-03T09:15:00.000Z"
  }
]
```

---

## GET /external/v1/huddles/:id — Get a Team Huddle

Operation ID: `get-team-huddle`

Retrieve metadata and all six stored snapshots: goals, customer changes, execution, pending actions, comparisons and conversations. The conversation snapshot includes retained sources, the summary, outstanding items, action candidates and analysis status/error/time. Snapshot fields follow schemaVersion and can be absent in older records. This is the latest saved state, not an end-of-day snapshot or revision archive. Refresh overwrites the daily record; conversation and action edits can update sections without increasing refreshRevision. Pasted text is in sources[].notes. Connected sources retain references with notes: null; fetch their text through the transcript route. This detail route makes no provider requests. Existing keys with initiatives:read also authorize this endpoint; either scope is sufficient.

Required API key scopes: `huddles:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | UUID | Yes | Huddle ID returned by the list endpoint (path parameter). |

### Example request

```curl
curl 'https://zentrik.ai/api/external/v1/huddles/11111111-1111-4111-8111-111111111111' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Metadata and complete saved snapshots. Snapshot objects in this example are abbreviated; the response returns complete stored JSON. | — |
| 400 | Invalid ID | The huddle ID must be a UUID. | — |
| 404 | Not found | The huddle does not exist in the API key’s workspace. | — |

### Example response

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "workspaceId": "22222222-2222-4222-8222-222222222222",
  "teamId": "33333333-3333-4333-8333-333333333333",
  "huddleDate": "2026-09-03",
  "schemaVersion": 4,
  "refreshRevision": 1,
  "generatedAt": "2026-09-03T09:00:00.000Z",
  "generatedByUserId": null,
  "createdAt": "2026-09-03T09:00:00.000Z",
  "updatedAt": "2026-09-03T09:15:00.000Z",
  "goalSnapshot": {
    "globalProgress": 0,
    "progressMethod": "equal_average",
    "goalCount": 0,
    "goals": []
  },
  "customerSnapshot": {},
  "executionSnapshot": {},
  "pendingActionSnapshot": [],
  "comparisonSnapshot": {
    "hasBaseline": false,
    "comparedWithDate": null,
    "requestedPreviousDay": "2026-09-02",
    "usedPreviousDay": false
  },
  "conversationSnapshot": {
    "sources": [
      {
        "id": "44444444-4444-4444-8444-444444444444",
        "provider": "Pasted notes",
        "title": "Daily huddle",
        "type": "transcript",
        "externalId": null,
        "url": null,
        "occurredAt": null,
        "integrationId": null,
        "metadata": {},
        "retention": "stored",
        "notes": "Review the scheduling feedback tomorrow.",
        "addedByUserId": null,
        "createdAt": "2026-09-03T09:15:00.000Z"
      }
    ],
    "analysisStatus": "queued",
    "aggregate": null,
    "analysisError": null,
    "analyzedAt": null
  }
}
```

---

## GET /external/v1/huddles/:huddleId/conversations/:conversationId — Get a huddle transcript

Operation ID: `get-team-huddle-transcript`

Retrieve one attached conversation’s transcript text. Pasted notes come from the saved huddle. Connected transcripts are fetched on demand using the stored provider reference and connected account, without persisting the text. Retrieval depends on source availability and provider permissions. All huddle reads use Cache-Control: private, no-store. Existing keys with initiatives:read also authorize this endpoint; either scope is sufficient.

Required API key scopes: `huddles:read`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `huddleId` | UUID | Yes | Huddle ID (path parameter). |
| `conversationId` | UUID | Yes | Zentrik conversation entry ID from conversationSnapshot.sources[].id (path parameter), not the provider’s meeting ID. |

### Example request

```curl
curl 'https://zentrik.ai/api/external/v1/huddles/11111111-1111-4111-8111-111111111111/conversations/44444444-4444-4444-8444-444444444444' -H 'Authorization: Bearer YOUR_API_KEY'
```

### Responses

| Status | Meaning | Description | Schema |
| --- | --- | --- | --- |
| 200 | Success | Source identity, provider, title, occurrence date, URL and transcript text. | — |
| 400 | Unavailable content | Invalid UUID, empty transcript, incomplete reference or integration requiring reconnection. Provider errors may also be returned. | — |
| 404 | Not found | Huddle, source or connected integration was not found. | — |

### Example response

```json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "provider": "Pasted notes",
  "title": "Daily huddle",
  "occurredAt": null,
  "url": null,
  "text": "Review the scheduling feedback tomorrow."
}
```