contentstack Voice Profiles API

openapi: 3.2.0
info:
  title: Contentstack Brand Kit Management Voice Profiles API
  description: The Contentstack Brand Kit Management API provides programmatic control over Brand Kit resources within a Contentstack organization. Brand Kits serve as centralized hubs for an organization's brand identity, encompassing detailed brand information, writing guidelines, and persona configurations. The API supports full CRUD operations for Brand Kits, Voice Profiles, and custom LLM configuration, enabling developers to manage brand identity data programmatically and integrate it with AI content generation workflows.
  version: v1
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://brand-kits-api.contentstack.com
  description: AWS North America Production Server
- url: https://eu-brand-kits-api.contentstack.com
  description: AWS Europe Production Server
- url: https://au-na-brand-kits-api.contentstack.com
  description: AWS Australia Production Server
- url: https://azure-na-brand-kits-api.contentstack.com
  description: Azure North America Production Server
- url: https://azure-eu-brand-kits-api.contentstack.com
  description: Azure Europe Production Server
- url: https://gcp-na-brand-kits-api.contentstack.com
  description: GCP North America Production Server
- url: https://gcp-eu-brand-kits-api.contentstack.com
  description: GCP Europe Production Server
security:
- bearerAuth: []
- authtokenAuth: []
tags:
- name: Voice Profiles
  description: Voice Profiles define the writing style, tone, and persona characteristics for AI content generation within a Brand Kit. Multiple voice profiles can be created to support different content contexts or audiences.
paths:
  /v1/brand-kits/{brand_kit_uid}/voice-profiles:
    get:
      operationId: getAllVoiceProfiles
      summary: Get all Voice Profiles
      description: Retrieves all Voice Profiles associated with a specific Brand Kit. Voice Profiles define the writing style and tone used in AI content generation for that Brand Kit.
      tags:
      - Voice Profiles
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/BrandKitUid'
      responses:
        '200':
          description: A list of Voice Profiles in the Brand Kit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceProfileList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createVoiceProfile
      summary: Create a Voice Profile
      description: Creates a new Voice Profile within a Brand Kit defining the writing style, tone characteristics, persona guidelines, and example content for AI generation.
      tags:
      - Voice Profiles
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/BrandKitUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVoiceProfileRequest'
      responses:
        '201':
          description: The newly created Voice Profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/brand-kits/{brand_kit_uid}/voice-profiles/{profile_uid}:
    get:
      operationId: getVoiceProfile
      summary: Get a Voice Profile
      description: Retrieves the full configuration of a specific Voice Profile including style guidelines, tone settings, and example content.
      tags:
      - Voice Profiles
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/BrandKitUid'
      - $ref: '#/components/parameters/ProfileUid'
      responses:
        '200':
          description: The requested Voice Profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateVoiceProfile
      summary: Update a Voice Profile
      description: Updates the configuration of an existing Voice Profile including style guidelines and tone characteristics.
      tags:
      - Voice Profiles
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/BrandKitUid'
      - $ref: '#/components/parameters/ProfileUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVoiceProfileRequest'
      responses:
        '200':
          description: The updated Voice Profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteVoiceProfile
      summary: Delete a Voice Profile
      description: Permanently removes a Voice Profile from the Brand Kit. This action cannot be undone.
      tags:
      - Voice Profiles
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/BrandKitUid'
      - $ref: '#/components/parameters/ProfileUid'
      responses:
        '200':
          description: Voice Profile deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    ProfileUid:
      name: profile_uid
      in: path
      required: true
      description: The unique identifier of the Voice Profile.
      schema:
        type: string
    OrganizationUid:
      name: organization_uid
      in: header
      required: true
      description: The unique identifier of the organization.
      schema:
        type: string
    BrandKitUid:
      name: brand_kit_uid
      in: path
      required: true
      description: The unique identifier of the Brand Kit.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    VoiceProfile:
      type: object
      description: A Voice Profile defining writing style and tone for AI content generation.
      properties:
        uid:
          type: string
          description: Unique identifier of the Voice Profile.
        name:
          type: string
          description: Display name of the Voice Profile.
        description:
          type: string
          description: Description of the voice profile's intended use case.
        tone:
          type: string
          description: The tonal characteristics of the voice profile such as formal, conversational, or authoritative.
        style_guidelines:
          type: string
          description: Writing style guidelines that define how content should be structured.
        brand_kit_uid:
          type: string
          description: UID of the Brand Kit this Voice Profile belongs to.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the Voice Profile was created.
    VoiceProfileList:
      type: object
      description: A list of Voice Profiles for a Brand Kit.
      properties:
        data:
          type: array
          description: Array of Voice Profile objects.
          items:
            $ref: '#/components/schemas/VoiceProfile'
    Error:
      type: object
      description: Standard error response.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
        error_code:
          type: integer
          description: Numeric error code.
    CreateVoiceProfileRequest:
      type: object
      description: Parameters for creating or updating a Voice Profile.
      required:
      - name
      properties:
        name:
          type: string
          description: Display name for the Voice Profile.
        description:
          type: string
          description: Description of the voice profile's purpose.
        tone:
          type: string
          description: Tonal characteristics for the voice profile.
        style_guidelines:
          type: string
          description: Writing style guidelines for AI content generation.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token with brand-kits:manage scope.
    authtokenAuth:
      type: apiKey
      in: header
      name: authtoken
      description: Contentstack user authtoken for session-based authentication.
externalDocs:
  description: Contentstack Brand Kit Management API Documentation
  url: https://www.contentstack.com/docs/developers/apis/brand-kit-management-api