openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Voice Profiles API
  description: The Contentstack Analytics API provides access to usage and performance metrics for CMS, Launch, and Automate products within a Contentstack organization. Developers can retrieve analytics data programmatically to build custom dashboards, monitor content delivery performance, and track platform usage against plan limits. The API returns structured data suitable for aggregation with external analytics and business intelligence tools. Access is restricted to organization Owners and Admins. Requests use async job-based processing where initial POST calls queue the job and a subsequent GET call retrieves the results.
  version: v2
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://api.contentstack.io
  description: AWS North America Production Server
- url: https://eu-api.contentstack.com
  description: AWS Europe Production Server
- url: https://au-api.contentstack.com
  description: AWS Australia 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:
  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.
    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.
    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.
  parameters:
    BrandKitUid:
      name: brand_kit_uid
      in: path
      required: true
      description: The unique identifier of the Brand Kit.
      schema:
        type: string
    OrganizationUid:
      name: organization_uid
      in: header
      required: true
      description: The unique identifier of the organization.
      schema:
        type: string
    ProfileUid:
      name: profile_uid
      in: path
      required: true
      description: The unique identifier of the Voice Profile.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (M2M) with analytics access.
    authtokenAuth:
      type: apiKey
      in: header
      name: authtoken
      description: Contentstack user authtoken. Only organization Owners and Admins can access analytics.
externalDocs:
  description: Contentstack Analytics API Documentation
  url: https://www.contentstack.com/docs/developers/apis/analytics-api