> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Rename a group
> Change an analysis group's name.
```json theme={"dark"}
{ "name": "Lead QA (v2)" }
```
**The group name is part of the key extracted values arrive under.** Values land as
`custom_analysis["Lead QA"]["Lead Temperature"]`, so renaming a group changes the shape of every
future call payload while leaving past calls under the old name.
If anything downstream reads that key — a warehouse column, a CRM mapping, a dashboard — rename
on both sides together, or create a new group instead.
**Vocily's built-in "Default Analysis" group cannot be renamed or deleted** — `409`. Its name is
an address other readers depend on, and its model deliberately follows the agent's own. What you
*can* do is edit each value's extraction description, switch values off, add your own values to
it, or detach the whole group from an agent.
Renaming does not re-run analysis. Calls already analysed keep the values and the names they were
analysed under.
## OpenAPI
````yaml developers/openapi.json PUT /v1/custom-analysis/groups/{group_id}
openapi: 3.1.0
info:
title: Vocily API
description: >-
Public REST API for Vocily. Build and configure an agent, publish a version
and put it live, place outbound calls, and read back calls, chats and what
the agent remembered. Authenticate with a workspace API key as a Bearer
token.
Some things stay in the dashboard, by design: creating an API key, buying or
connecting a phone number, setting an agent's webhook URL, connecting
WhatsApp and its templates, building HTTP tools, and running batch
campaigns.
version: v1
servers:
- url: https://api.vocily.ai
description: Production
security: []
paths:
/v1/custom-analysis/groups/{group_id}:
put:
tags:
- custom-analysis
summary: Update Custom Analysis Category
description: >-
Change a group. Renaming changes the key future calls arrive under; past
calls keep the
old name.
operationId: update_custom_analysis_category_v1_custom_analysis_groups__group_id__put
parameters:
- name: group_id
in: path
required: true
schema:
type: string
title: Group Id
description: The analysis group's id, from `GET /v1/custom-analysis`.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublicAnalysisGroupUpdate'
example:
name: Lead QA (v2)
responses:
'200':
description: The updated group.
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
model:
type: string
nullable: true
temperature:
type: number
nullable: true
max_tokens:
type: integer
nullable: true
conditions:
type: object
is_default:
type: boolean
items:
type: array
items:
type: object
properties:
id:
type: string
category_id:
type: string
name:
type: string
description:
type: string
result_format:
type: string
enum:
- string
- number
- integer
- boolean
- array
- object
extraction_method:
type: string
enum:
- ai
- regex
required:
type: boolean
constraints:
type: object
fields:
type: array
items:
type: object
enabled:
type: boolean
is_system:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
example:
name: Lead quality (v2)
description: What we ask the model to pull out of every call.
model: null
temperature: null
max_tokens: null
conditions: {}
id: 0000000f-0000-4000-8000-00000000000f
items:
- name: Lead Temperature
description: >-
How ready the caller is to buy, judged from what they said
— not from tone.
extraction_method: ai
result_format: string
required: false
constraints:
enum:
- hot
- warm
fields: []
enabled: true
id: 00000010-0000-4000-8000-000000000010
category_id: 0000000f-0000-4000-8000-00000000000f
is_system: false
created_at: '2026-09-16T19:38:04.238748Z'
updated_at: '2026-09-16T19:38:04.251020Z'
is_default: false
created_at: '2026-09-16T19:38:04.226829Z'
updated_at: '2026-09-16T19:38:04.260569Z'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
detail: Invalid API key
code: UNAUTHORIZED
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded — honor `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: rate_limited
security:
- bearerAuth: []
components:
schemas:
PublicAnalysisGroupUpdate:
properties:
name:
anyOf:
- maxLength: 255
minLength: 1
type: string
- type: 'null'
title: Name
description: >-
What to call this group. Renaming changes the key values arrive
under on every future call, while past calls keep the old name.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Your own note about what the group is for.
model:
anyOf:
- type: string
maxLength: 128
minLength: 1
- type: 'null'
title: Model
description: Which LLM runs the extraction.
temperature:
anyOf:
- maximum: 2
minimum: 0
type: number
- type: 'null'
title: Temperature
description: Randomness for the extraction.
max_tokens:
anyOf:
- type: integer
maximum: 10000
minimum: 50
- type: 'null'
title: Max Tokens
description: Cap on the extraction response.
conditions:
anyOf:
- $ref: '#/components/schemas/CustomAnalysisConditions'
- type: 'null'
description: When this group runs at all.
additionalProperties: false
type: object
title: PublicAnalysisGroupUpdate
ApiError:
type: object
description: >-
Error envelope. `code` is derived from the HTTP status, so branch on it
for the CLASS of failure; the specific reason is `detail.code`. Every
public refusal carries both.
properties:
detail:
type: object
description: >-
The reason. `code` is the domain reason (e.g. `call_not_found`) and
`message` is a sentence safe to log. On a `422` it also carries
`errors[]`, one entry per rejected field — see
`HTTPValidationError`.
properties:
code:
type: string
example: call_not_found
message:
type: string
example: Call not found
required:
- code
- message
code:
type: string
description: Derived from the HTTP status, not the domain reason.
example: NOT_FOUND
HTTPValidationError:
type: object
title: HTTPValidationError
description: >-
A request the API could not read: a field of the wrong type, out of
range, missing, or one we do not accept. Same envelope as every other
error.
properties:
detail:
type: object
description: >-
What was wrong, as `code`, a one-line `message`, and every offending
field in `errors`.
required:
- code
- message
- errors
properties:
code:
type: string
enum:
- validation_error
message:
type: string
description: >-
The first problem in one line, with a count of the rest — e.g.
`model.temperature: Input should be less than or equal to 2 (and
1 more)`.
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: >-
One entry per offending field. **Every problem is reported at
once**, not just the first, so a malformed body needs one round
trip to fix rather than one per field.
code:
type: string
enum:
- VALIDATION_ERROR
description: Derived from the HTTP status, as on every error.
CustomAnalysisConditions:
properties:
min_messages:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Min Messages
description: >-
Skip the group unless the conversation ran at least this many
messages.
min_duration_seconds:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Min Duration Seconds
description: Skip it unless the call lasted at least this long.
ended_reason:
anyOf:
- $ref: '#/components/schemas/CustomAnalysisEndedReasonCondition'
- type: 'null'
description: Run it only for calls that ended a particular way.
additionalProperties: false
type: object
title: CustomAnalysisConditions
description: >-
Run a category only on the calls it applies to. Leave it empty and the
category runs on every call.
The fields are fixed rather than free-form, so a misspelled condition is
a `422` instead of one that silently never matches.
ValidationError:
type: object
title: ValidationError
required:
- field
- message
- type
properties:
field:
type: string
description: >-
The offending field as a path from the root of your request —
`voice.speed`, `variables[0].key`, or `query.limit` for a query
parameter. **This is the field to read.**
message:
type: string
description: What is wrong with it, in plain language.
type:
type: string
description: >-
A stable machine code for the kind of failure, e.g.
`extra_forbidden` for a field we do not accept, `missing` for a
required one, or `less_than_equal` for a number out of range. Switch
on this rather than on `message`, which may be reworded.
CustomAnalysisEndedReasonCondition:
properties:
operator:
type: string
title: Operator
description: >-
`one_of` to run the group only for these outcomes, `not_one_of` to
run it for everything except them.
values:
items:
type: string
type: array
title: Values
description: >-
How the call ended — one or more of `completed`, `voicemail`,
`no_answer`, `busy`, `declined`, `failed`, `transfer_completed`,
`transfer_failed`. These are the outcomes a *finished* call can
hold, which is why the mid-call states are not offered: a condition
on one would never match. Anything else is refused.
additionalProperties: false
type: object
required:
- operator
title: CustomAnalysisEndedReasonCondition
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.'
````