openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts LLM Configuration 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: LLM Configuration
  description: LLM Configuration endpoints allow organizations to register custom API credentials for large language model providers, enabling content generation through their own LLM subscriptions.
paths:
  /v1/brand-kits/{brand_kit_uid}/llm-config:
    get:
      operationId: getLlmConfig
      summary: Get LLM configuration
      description: Retrieves the custom LLM provider credentials configured for a Brand Kit. This allows organizations to use their own LLM API subscriptions for content generation within the Brand Kit.
      tags:
      - LLM Configuration
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/BrandKitUid'
      responses:
        '200':
          description: The LLM configuration for the Brand Kit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: configureLlm
      summary: Configure custom LLM credentials
      description: Registers custom API credentials for an LLM provider to enable content generation through the organization's own LLM subscription rather than Contentstack's default AI infrastructure.
      tags:
      - LLM Configuration
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/BrandKitUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLlmConfigRequest'
      responses:
        '200':
          description: LLM configuration saved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreateLlmConfigRequest:
      type: object
      description: Parameters for configuring custom LLM credentials.
      required:
      - provider
      - api_key
      properties:
        provider:
          type: string
          description: Name of the LLM provider.
          enum:
          - openai
          - anthropic
          - azure_openai
        model:
          type: string
          description: The LLM model identifier to use.
        api_key:
          type: string
          description: API key for authenticating with the LLM provider.
        endpoint:
          type: string
          format: uri
          description: Custom endpoint URL for Azure OpenAI or self-hosted deployments.
    LlmConfig:
      type: object
      description: Custom LLM provider configuration for a Brand Kit.
      properties:
        provider:
          type: string
          description: Name of the LLM provider (e.g., openai, anthropic, azure_openai).
        model:
          type: string
          description: The specific LLM model to use for content generation.
        api_key_configured:
          type: boolean
          description: Indicates whether a valid API key has been configured.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the LLM configuration was set.
    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.
  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'
  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
  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