> ## 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.

# Add an item

> One thing to extract, inside a group.

```json theme={"dark"}
{ "category_id": "…",
  "name": "Lead Temperature",
  "description": "How ready the caller is to buy, from what they said.",
  "result_format": "string",
  "constraints": { "enum": ["hot", "warm", "cold"] } }
```

<Note>
  **`description` is the instruction, not a label.** It is what the model is told to look for, so
  write it as a direction rather than a title.
</Note>

| `result_format`      | For                                                 |
| -------------------- | --------------------------------------------------- |
| `string`             | Free text — or a fixed set, with `constraints.enum` |
| `number` · `integer` | Quantities, with `minimum` / `maximum`              |
| `boolean`            | Yes or no                                           |
| `array` · `object`   | Lists and records, shaped by `constraints`          |

Set `extraction_method: "regex"` with `constraints.pattern` to pull a value out by pattern instead of
by model. Regex items cost nothing, and a group made only of them makes no model call at all.

The extracted values arrive on the call: `custom_analysis["Lead QA"]["Lead Temperature"]`.


## OpenAPI

````yaml developers/openapi.json POST /v1/custom-analysis/items
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/items:
    post:
      tags:
        - custom-analysis
      summary: Create Custom Analysis Item
      description: >-
        Add a value to a group. Its `description` is the instruction the model
        reads.
      operationId: create_custom_analysis_item_v1_custom_analysis_items_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicAnalysisItemCreate'
            example:
              category_id: 1f7a2c3e-9b40-4d2a-8c11-5e6f7a8b9c0d
              name: Lead Temperature
              description: How ready the caller is to buy, from what they said.
              result_format: string
              constraints:
                enum:
                  - hot
                  - warm
                  - cold
      responses:
        '201':
          description: The created item.
          content:
            application/json:
              schema:
                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
              example:
                name: Lead Temperature
                description: How ready the caller is to buy.
                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.238748Z'
        '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:
    PublicAnalysisItemCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: >-
            What to call this value. **Part of the key it arrives under** —
            `custom_analysis["Lead QA"]["Lead Temperature"]`.
        description:
          type: string
          minLength: 1
          title: Description
          description: >-
            **The instruction the model reads, not a label.** Write it as a
            direction — what to look for — rather than a title.
        extraction_method:
          type: string
          maxLength: 8
          title: Extraction Method
          description: >-
            `regex` pulls the value out by pattern using `constraints.pattern`
            and costs nothing; anything else asks the model. A group made only
            of regex items makes no model call at all.
          default: ai
        result_format:
          type: string
          maxLength: 16
          title: Result Format
          description: >-
            The shape of the value: `string`, `number`, `integer`, `boolean`,
            `array` or `object`.
        required:
          type: boolean
          title: Required
          description: Whether the model must produce a value rather than leaving it out.
          default: false
        constraints:
          $ref: '#/components/schemas/CustomAnalysisConstraints'
          description: >-
            Limits on the value — a fixed set with `enum`, a range, a regex, a
            length.
        fields:
          items:
            $ref: '#/components/schemas/CustomAnalysisFieldSpec'
          type: array
          title: Fields
          description: The inner fields, when `result_format` is `object` or `array`.
        enabled:
          type: boolean
          title: Enabled
          description: Turn it off without deleting it.
          default: true
        category_id:
          type: string
          title: Category Id
          description: Which group this value belongs to, from `GET /v1/custom-analysis`.
      additionalProperties: false
      type: object
      required:
        - name
        - description
        - result_format
        - category_id
      title: PublicAnalysisItemCreate
    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.
    CustomAnalysisConstraints:
      properties:
        enum:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Enum
          description: >-
            The allowed values. Use this rather than describing a fixed set in
            prose.
        min_length:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Min Length
          description: Shortest acceptable string.
        max_length:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          title: Max Length
          description: Longest acceptable string.
        format:
          anyOf:
            - type: string
            - type: 'null'
          title: Format
          description: A named string format, e.g. `email` or `date`.
        pattern:
          anyOf:
            - type: string
            - type: 'null'
          title: Pattern
          description: >-
            A regular expression the value must match. **Required when
            `extraction_method` is `regex`** — it is what does the extracting.
        minimum:
          anyOf:
            - type: number
            - type: 'null'
          title: Minimum
          description: Smallest acceptable number, inclusive.
        maximum:
          anyOf:
            - type: number
            - type: 'null'
          title: Maximum
          description: Largest acceptable number, inclusive.
        exclusive_minimum:
          anyOf:
            - type: number
            - type: 'null'
          title: Exclusive Minimum
          description: The value must be strictly greater than this.
        exclusive_maximum:
          anyOf:
            - type: number
            - type: 'null'
          title: Exclusive Maximum
          description: The value must be strictly less than this.
        multiple_of:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Multiple Of
          description: The value must be a multiple of this.
        item_shape:
          anyOf:
            - type: string
            - type: 'null'
          title: Item Shape
          description: The shape of each element, for an array value.
        item_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Item Type
          description: The JSON type of each element, for an array value.
      additionalProperties: false
      type: object
      title: CustomAnalysisConstraints
      description: >-
        Every constraint any format can carry. Which ones are legal depends on
        the format.
    CustomAnalysisFieldSpec:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: The inner field's name.
        description:
          type: string
          minLength: 1
          title: Description
          description: The instruction the model reads for this inner field.
        type:
          type: string
          maxLength: 16
          title: Type
          description: The inner field's JSON type.
        required:
          type: boolean
          title: Required
          description: Whether it must be produced.
          default: false
        constraints:
          $ref: '#/components/schemas/CustomAnalysisConstraints'
          description: Limits on the inner field's value.
      type: object
      required:
        - name
        - description
        - type
      title: CustomAnalysisFieldSpec
      description: >-
        One property of an `object` item, or of each record in an `array` of
        fields.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.'

````