Skip to documentation
Markdown version →

Team Huddles

Upload transcripts with huddles:write and read daily Team Huddle history with huddles:read or initiatives:read. Read and write grants are separate. Existing initiative-read keys continue to authorize reads. Each grant covers all teams in the workspace; huddles:read lets new keys request only Huddle reads. Initiative Huddle note sessions are a separate workflow. Each daily record retains its latest saved state, up to ten conversation sources, up to 100,000 characters per uploaded source, and up to 120,000 characters of combined transcript text for analysis.

4 endpoints

GET

List Team Huddle history

GET /external/v1/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.

Requirements

API scopes required:
huddles:read

Request

Parameters

NameTypeDescription
teamId UUIDFilter to one team. Omit to include all teams in the API key’s workspace.
from stringInclusive huddle date, YYYY-MM-DD. Filters the saved calendar date, not generatedAt.
to stringInclusive huddle date, YYYY-MM-DD; must be on or after from. Set from and to to the same date for one day.
limit integerPage size, 1–100. Default: 20.
offset integerMatching records to skip. Default: 0.

Responses

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 Request

GET
/external/v1/huddles
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'

Example Response

200 OK
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

Get a Team Huddle

GET /external/v1/huddles/:id

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. A connected source names its provider in type, the provider’s meeting or transcript ID in externalId, and the provider link saved when the transcript was chosen in url, such as the Fireflies transcript page. If the same call was also imported as a signal, GET /external/v1/signals?externalId={externalId}&integrationId={integrationId} returns it. This detail route makes no provider requests. Existing keys with initiatives:read also authorize this endpoint; either scope is sufficient.

Requirements

API scopes required:
huddles:read

Request

Parameters

NameTypeDescription
id *UUIDHuddle ID returned by the list endpoint (path parameter).

Responses

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 Request

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

Example Response

200 OK
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": "55555555-5555-4555-8555-555555555555",
        "provider": "Fireflies",
        "title": "Customer interview",
        "type": "fireflies",
        "externalId": "fireflies-transcript-id",
        "url": "https://app.fireflies.ai/view/fireflies-transcript-id",
        "occurredAt": "2026-09-02T16:00:00.000Z",
        "integrationId": "66666666-6666-4666-8666-666666666666",
        "metadata": {},
        "retention": "reference",
        "notes": null,
        "addedByUserId": "77777777-7777-4777-8777-777777777777",
        "createdAt": "2026-09-03T09:10:00.000Z"
      },
      {
        "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

Get a huddle transcript

GET /external/v1/huddles/:huddleId/conversations/:conversationId

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.

Requirements

API scopes required:
huddles:read

Request

Parameters

NameTypeDescription
huddleId *UUIDHuddle ID (path parameter).
conversationId *UUIDZentrik conversation entry ID from conversationSnapshot.sources[].id (path parameter), not the provider’s meeting ID.

Responses

200
Success

Source identity, provider, title, occurrence date, saved provider link and transcript text. Pasted notes return url: null.

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 Request

GET
/external/v1/huddles/:huddleId/conversations/:conversationId
curl
curl 'https://zentrik.ai/api/external/v1/huddles/11111111-1111-4111-8111-111111111111/conversations/55555555-5555-4555-8555-555555555555' -H 'Authorization: Bearer YOUR_API_KEY'

Example Response

200 OK
json
{
  "id": "55555555-5555-4555-8555-555555555555",
  "provider": "Fireflies",
  "title": "Customer interview",
  "occurredAt": "2026-09-02T16:00:00.000Z",
  "url": "https://app.fireflies.ai/view/fireflies-transcript-id",
  "text": "Scheduling takes our team two hours every Monday."
}
POST

Add a Huddle transcript

POST /external/v1/huddles/conversations

Upload meeting text to a team’s daily Huddle. Requires huddles:write; read scopes do not allow uploads. Supply teamId and an explicit date to select the destination; Zentrik creates the daily Huddle if needed. Text is stored as an API-uploaded transcript, and analysis is queued. Suggested actions and decisions remain subject to review in Huddle. The latest ten conversation sources are retained. Their combined transcript text is limited to 120,000 characters, excluding source labels; each upload is also limited to 100,000 characters. A request exceeding the known retained-text budget returns 400 without adding the upload or changing the existing analysis. Shorten notes before retrying; splitting the same text across uploads does not avoid the combined limit. Connected source lengths are checked again when fetched. Each successful POST appends a new source: sourceExternalId is descriptive metadata, not a deduplication key. After a timeout, inspect the Huddle sources before retrying; serialize uploads to the same team/date. Connected-provider references and audio files are not accepted by this endpoint.

Requirements

API scopes required:
huddles:write

Request

Parameters

NameTypeDescription
teamId *UUIDDestination team in the API key workspace (query parameter). Find IDs with GET /external/v1/teams using initiatives:read.
date *stringHuddle calendar date as YYYY-MM-DD (body).
notes *stringNonblank transcript text, at most 100,000 characters (body).
sourceTitle stringMeeting title, at most 200 characters (body).
sourceExternalId stringSource-system meeting ID, at most 500 characters; does not deduplicate uploads (body).
sourceUrl stringHTTP(S) source link, at most 2,000 characters; not fetched (body).
sourceOccurredAt stringISO 8601 occurrence time including Z or an offset (body).

Responses

201
Saved

Returns the Huddle and conversation IDs. Poll GET /external/v1/huddles/:id with huddles:read or initiatives:read; conversationSnapshot reports analysisStatus, analysisError and the resulting aggregate; decisionStatus and decisionError separately report decision extraction. Wait for both to finish. A saved upload does not mean analysis has finished. If existing or fetched provider text exceeds the combined limit, both statuses become failed with an explicit size error; no partial analysis runs. Existing sources remain retrievable. Contact support to reduce oversized retained sources, then retry analysis in Huddle.

400
Invalid input

Missing team/date/text, invalid date or URL, oversized text, or an unsupported field. Combined-size errors include code: HUDDLE_TRANSCRIPT_LIMIT_EXCEEDED, maxCharacters: 120000 and totalCharacters. The rejected upload is not saved; shorten notes and retry. Send JSON text, not a file or provider credentials.

401
Unauthorized

Missing, invalid, expired or disabled API key.

403
Missing scope

Grant huddles:write to the API key.

404
Team not found

The destination team does not belong to the key’s workspace.

429
Rate limited

Wait for Retry-After before another request.

Example Request

POST
/external/v1/huddles/conversations
curl
curl -X POST 'https://zentrik.ai/api/external/v1/huddles/conversations?teamId=33333333-3333-4333-8333-333333333333'   -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json'   -d '{"date":"2026-10-21","notes":"We agreed to follow up with the customer on Friday.","sourceTitle":"Weekly team sync","sourceExternalId":"meeting-2026-10-21"}'

Example Response

201 Created
json
{
  "huddleId": "11111111-1111-4111-8111-111111111111",
  "teamId": "33333333-3333-4333-8333-333333333333",
  "date": "2026-10-21",
  "conversationId": "44444444-4444-4444-8444-444444444444",
  "analysisStatus": "queued"
}