> ## 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 Configuration
> Partially update an existing configuration. Only fields included in the request body are modified.
For full details on all Configuration fields, see [Configuration](/core/configuration).
This endpoint uses **PATCH semantics** — omitted fields are not touched. Only `configuration_id` is required; include only the fields you want to change.
**`extraction_fields` is not a simple replacement — it uses a merge-by-name strategy.** Any existing field **not included** in your request will be **removed**. Always send the complete desired list of fields, not just the ones you're changing.
The `type` of an existing extraction field **cannot be changed**. Attempting to do so returns a `400` error. To change a field type, delete and recreate the configuration.
`tag` cannot be updated — it is immutable after creation. See [Configuration](/core/configuration#tag).
`vocabulary` and `webhooks` are **fully replaced** by whatever you send. To remove webhooks entirely, pass `"webhooks": null`.
Returns `404` if the configuration is not found.
## OpenAPI
````yaml api-reference/openapi-configurations.json POST /update-configuration
openapi: 3.1.0
info:
title: Heify API — Configurations
description: Endpoints for creating, retrieving, and deleting Configurations.
version: 1.0.0
servers:
- url: https://api.heify.com
security:
- apiKeyAuth: []
paths:
/update-configuration:
post:
summary: Update a Configuration
description: >-
Partially updates an existing configuration using PATCH semantics — only
fields included in the request body are modified. `extraction_fields`
uses a merge-by-name strategy: fields not included in the request are
removed.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateConfigurationRequest'
examples:
UpdateExample:
summary: Update summary settings and extraction fields
value:
configuration_id: a1b2c3d4-e5f6-7890-1234-567890abcdef
summary: true
summary_language: en
custom_summary: Focus on key decisions and action items.
vocabulary:
- Heify
- NLP
extraction_fields:
- name: sentiment_analysis
type: string
description: >-
Classify the sentiment as POSITIVE, NEGATIVE, or
NEUTRAL.
responses:
'200':
description: >-
Configuration updated successfully. Returns the full updated
configuration object.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateConfigurationResponse'
examples:
UpdateSuccess:
value:
data:
message: Configuration updated successfully.
configuration:
client_id: client-12345
configuration_id: a1b2c3d4-e5f6-7890-1234-567890abcdef
tag: Customer Support - Technical Issues
vocabulary:
- Heify
- NLP
extraction_fields:
- name: sentiment_analysis
type: string
description: >-
Classify the sentiment as POSITIVE, NEGATIVE, or
NEUTRAL.
webhooks: null
summary: true
custom_summary: Focus on key decisions and action items.
summary_language: en
analytics_language: df
created_at: '2025-01-15T10:00:00.000000+00:00'
components:
schemas:
UpdateConfigurationRequest:
type: object
properties:
configuration_id:
type: string
format: uuid
description: The unique identifier of the configuration to update.
vocabulary:
type: array
items:
type: string
description: >-
**Full replacement.** Replaces the entire existing vocabulary list.
Example: `["Heify", "NLP", "SLA"]`.
extraction_fields:
type: array
description: >-
**Merge-by-name strategy.** Existing fields can have their
`description` updated but their `type` is immutable. New fields
(name not already present) must include `type` and `description`.
Fields not included in this list are **removed**. Maximum 10 fields
total.
maxItems: 10
items:
$ref: '#/components/schemas/ExtractionField'
webhooks:
oneOf:
- $ref: '#/components/schemas/Webhooks'
- type: 'null'
description: '**Full replacement.** Pass `null` to remove webhooks entirely.'
summary:
type: boolean
description: Enable or disable automatic AI summary generation.
custom_summary:
type: string
nullable: true
maxLength: 300
description: >-
Custom prompt guiding the AI summary. Pass `null` to clear. Only
applies when `summary` is `true`.
summary_language:
type: string
description: >-
Language for the generated summary. Use `"df"` for auto-detect. See
[Supported Languages](/core/transcription#supported-languages).
analytics_language:
type: string
description: >-
Language for analytics reports. Use `"df"` for auto-detect. See
[Supported Languages](/core/transcription#supported-languages).
required:
- configuration_id
UpdateConfigurationResponse:
type: object
properties:
data:
type: object
properties:
message:
type: string
description: Confirmation message.
configuration:
$ref: '#/components/schemas/Configuration'
description: The full updated configuration object.
ExtractionField:
type: object
properties:
name:
type: string
description: >-
Field identifier. Auto-normalized on creation: lowercased, accents
removed, special characters replaced with `_`. Example: `"Customer
ID"` → `"customer_id"`.
maxLength: 50
type:
type: string
description: >-
Expected data type of the extracted value. **Immutable after
creation.**
enum:
- string
- number
- boolean
- array
description:
type: string
description: >-
Instructions for the AI on what to extract. The more specific, the
better the accuracy. Example: `"Classify the overall sentiment. Must
be one of: POSITIVE, NEGATIVE, or NEUTRAL."`
maxLength: 1000
additionalProperties: false
required:
- name
- type
- description
Webhooks:
type: object
description: URLs for receiving completion/failure notifications via POST requests.
properties:
success_url:
type: string
format: uri
description: >-
Receives a POST request with the full transcription result on
success.
error_url:
type: string
format: uri
description: Receives a POST request with error details on failure.
additionalProperties: false
Configuration:
type: object
properties:
client_id:
type: string
description: The client identifier associated with the configuration.
configuration_id:
type: string
format: uuid
description: The unique identifier for the configuration.
tag:
type: string
description: >-
A descriptive name for the configuration. Permanent — cannot be
changed after creation.
maxLength: 255
vocabulary:
type: array
items:
type: string
description: >-
Custom terms (brand names, acronyms, technical words) that improve
transcription accuracy.
extraction_fields:
type: array
items:
$ref: '#/components/schemas/ExtractionField'
description: AI extraction field definitions (max 10).
webhooks:
oneOf:
- $ref: '#/components/schemas/Webhooks'
- type: 'null'
summary:
type: boolean
description: Whether to generate an AI summary.
custom_summary:
type: string
nullable: true
maxLength: 300
description: >-
Custom prompt guiding the AI summary. Only applies when `summary` is
`true`.
summary_language:
type: string
description: Language for the summary. `"df"` = auto-detect.
analytics_language:
type: string
description: Language for analytics reports. `"df"` = auto-detect.
created_at:
type: string
format: date-time
description: Timestamp of when the configuration was created (UTC).
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
````