> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heify.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Transcription Group
> Assign or clear the review workflow group of a transcription.
`group` is the **only updatable field** on a transcription. All other fields are set during processing and are immutable.
For valid group values and their meaning in the review workflow, see [Transcription — group](/core/transcription#group).
Pass `""` (empty string) as `group` to clear it (sets the field to `null`).
Returns `404` if the transcription is not found.
The response includes the **full updated transcription** — same structure as [Get Transcription](/api-reference/transcription/details).
## OpenAPI
````yaml api-reference/openapi-transcriptions.json POST /update-transcription-group
openapi: 3.1.0
info:
title: Heify API — Transcriptions
description: Endpoints for submitting, retrieving, and managing Transcriptions.
version: 1.0.0
servers:
- url: https://api.heify.com
security:
- apiKeyAuth: []
paths:
/update-transcription-group:
post:
summary: Update Transcription Group
description: >-
Updates the `group` field of a transcription to manage its review
workflow status. Pass an empty string `""` to clear the group.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTranscriptionGroupRequest'
examples:
SetGroup:
summary: Set a transcription's group
value:
transcription_id: 1a2b3c4d-e5f6-7890-1234-567890abcdef
group: PENDING_REVIEW
ClearGroup:
summary: Clear a transcription's group
value:
transcription_id: 1a2b3c4d-e5f6-7890-1234-567890abcdef
group: ''
responses:
'200':
description: >-
Group updated successfully. Returns the full, updated transcription
object.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateTranscriptionGroupResponse'
examples:
SuccessResponse:
summary: Group updated successfully
value:
data:
message: Transcription group updated successfully.
transcription:
transcription_id: be340280-2618-43f7-9632-ef51fe91906e
status: COMPLETED
configuration_id: 3b8006ad-b1a2-464b-9a6b-79dcd45c9433
configuration_tag: Pitch Analysis DEMO
duration: 542.82
group: PENDING_REVIEW
name: null
participant_id: null
evaluator_id: null
participant_tag: null
evaluator_tag: null
details:
language: en
num_speakers: 4
created_at: '2026-03-21T12:51:39.990670+00:00'
completed_at: '2026-03-21T12:52:00.274673+00:00'
conversation: null
summary: null
fields: null
evaluation: null
components:
schemas:
UpdateTranscriptionGroupRequest:
type: object
properties:
transcription_id:
type: string
format: uuid
description: The unique identifier of the transcription to update.
group:
type: string
description: >-
New group value. Valid values: `PENDING_REVIEW`, `UNDER_REVIEW`,
`ARCHIVED`. Pass `""` (empty string) to clear the group.
required:
- transcription_id
- group
UpdateTranscriptionGroupResponse:
type: object
properties:
data:
type: object
properties:
message:
type: string
transcription:
$ref: '#/components/schemas/TranscriptionDetailObject'
TranscriptionDetailObject:
oneOf:
- title: COMPLETED
type: object
description: A completed transcription with full details.
properties:
transcription_id:
type: string
format: uuid
status:
type: string
enum:
- COMPLETED
configuration_id:
type: string
format: uuid
nullable: true
configuration_tag:
type: string
nullable: true
duration:
type: number
nullable: true
description: Duration in seconds.
group:
type: string
nullable: true
enum:
- PENDING_REVIEW
- UNDER_REVIEW
- ARCHIVED
- null
description: Review workflow group.
name:
type: string
nullable: true
participant_id:
type: string
nullable: true
evaluator_id:
type: string
nullable: true
participant_tag:
type: string
nullable: true
evaluator_tag:
type: string
nullable: true
details:
$ref: '#/components/schemas/TranscriptionFullSuccessDetails'
required:
- transcription_id
- status
- details
- title: FAILED
type: object
description: A failed transcription.
properties:
transcription_id:
type: string
format: uuid
status:
type: string
enum:
- FAILED
details:
$ref: '#/components/schemas/TranscriptionErrorDetails'
required:
- transcription_id
- status
- details
- title: IN_PROGRESS
type: object
description: >-
An in-progress transcription. Same structure as COMPLETED but all
`details` fields are `null` while processing is ongoing.
properties:
transcription_id:
type: string
format: uuid
status:
type: string
enum:
- IN_PROGRESS
configuration_id:
type: string
format: uuid
nullable: true
configuration_tag:
type: string
nullable: true
duration:
type: number
nullable: true
group:
type: string
nullable: true
name:
type: string
nullable: true
participant_id:
type: string
format: uuid
nullable: true
evaluator_id:
type: string
format: uuid
nullable: true
participant_tag:
type: string
nullable: true
evaluator_tag:
type: string
nullable: true
details:
$ref: '#/components/schemas/TranscriptionFullSuccessDetails'
required:
- transcription_id
- status
- details
TranscriptionFullSuccessDetails:
type: object
description: Full details for a completed transcription.
properties:
language:
type: string
nullable: true
description: Detected language code.
num_speakers:
type: number
nullable: true
description: Number of unique speakers identified.
created_at:
type: string
format: date-time
description: Submission timestamp (ISO 8601).
completed_at:
type: string
format: date-time
nullable: true
description: Completion timestamp (ISO 8601).
summary:
$ref: '#/components/schemas/SummaryContent'
nullable: true
description: >-
AI-generated summary. `null` if `summary` was not enabled in the
configuration.
conversation:
$ref: '#/components/schemas/ConversationContent'
nullable: true
description: Speaker-separated transcript segments.
fields:
$ref: '#/components/schemas/FieldsContent'
nullable: true
description: >-
Extracted structured data. `null` if no extraction fields were
configured.
evaluation:
$ref: '#/components/schemas/EvaluationSummary'
nullable: true
description: QA evaluation result. `null` if no evaluator was used.
required:
- created_at
TranscriptionErrorDetails:
type: object
description: Details for a failed transcription.
properties:
message:
type: string
description: Human-readable error description.
code:
type: integer
description: Internal error code.
failed_at:
type: string
format: date-time
nullable: true
description: Timestamp when the failure occurred.
required:
- message
- code
SummaryContent:
type: object
properties:
summary:
type: string
description: AI-generated summary text.
required:
- summary
ConversationContent:
type: object
properties:
segments:
type: array
items:
$ref: '#/components/schemas/ConversationSegment'
required:
- segments
FieldsContent:
type: object
properties:
fields:
type: array
items:
$ref: '#/components/schemas/ExtractedFieldItem'
required:
- fields
EvaluationSummary:
type: object
properties:
score:
type: number
nullable: true
description: Overall quality score (0–100).
critical_fail:
type: boolean
description: Whether a `strict` criterion was triggered.
status:
type: string
nullable: true
enum:
- PENDING
- COMPLETED
- FAILED
breakdown:
$ref: '#/components/schemas/EvaluationBreakdown'
nullable: true
description: >-
Full per-criterion evaluation. Only present when `status` is
`COMPLETED`.
ConversationSegment:
type: object
properties:
text:
type: string
description: Transcribed text for this segment.
speaker:
type: string
description: Speaker label (e.g. `SPEAKER_00`, `SPEAKER_01`).
required:
- text
- speaker
ExtractedFieldItem:
type: object
properties:
name:
type: string
description: Field name matching the configured extraction field.
value:
description: >-
Extracted value. Type matches the configured field type (`string`,
`number`, `boolean`, `array`).
required:
- name
- value
EvaluationBreakdown:
type: object
description: Full evaluation breakdown generated by the evaluator.
properties:
evaluator_id:
type: string
format: uuid
description: ID of the evaluator used.
evaluator_tag:
type: string
description: Name of the evaluator.
generated_at:
type: string
format: date-time
description: Timestamp when the evaluation was generated.
language_used:
type: string
description: Language used for the AI-generated feedback (e.g. `es`, `en`).
final_score:
type: number
description: Final score (0–100), identical to `evaluation.score`.
critical_fail_triggered:
type: boolean
description: Whether a `strict` criterion was triggered.
summary_feedback:
type: string
description: >-
AI-generated Markdown summary of the evaluation with overall
feedback and action plan.
results:
type: array
description: Per-criterion evaluation results.
items:
$ref: '#/components/schemas/CriterionResult'
CriterionResult:
type: object
description: Evaluation result for a single criterion.
properties:
criteria_id:
type: string
format: uuid
description: Unique ID of the criterion.
name:
type: string
description: Criterion name.
type:
type: string
enum:
- boolean
- scale
- strict
description: Criterion type. See [Evaluator](/core/evaluator#criterion-types).
max_weight:
type: number
description: Maximum score contribution of this criterion.
score_raw_ai:
type: number
description: Raw score returned by the AI model.
score_obtained:
type: number
description: Final weighted score obtained.
status:
type: string
enum:
- PASS
- FAIL
description: '`PASS` or `FAIL`.'
reasoning:
type: string
nullable: true
description: AI explanation for the score.
quote:
type: string
nullable: true
description: Relevant quote from the transcript that informed the evaluation.
feedback:
type: string
nullable: true
description: Actionable improvement suggestion for this criterion.
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````