Contentstack Generative AI API

openapi: 3.1.0
info:
  title: Contentstack Generative AI API
  description: >-
    The Contentstack Generative AI API provides an endpoint for generating
    AI-powered content using a Brand Kit's knowledge vault and voice profiles.
    It acts as a communication channel between the vector database and large
    language models, processing prompts with retrieval augmented generation
    (RAG) to produce brand-aligned content. The API supports optional knowledge
    vault retrieval and voice profile application to ensure generated content
    adheres to the organization's brand guidelines and writing style.
  version: 'v1'
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
externalDocs:
  description: Contentstack Generative AI API Documentation
  url: https://www.contentstack.com/docs/developers/apis/generative-ai-api
servers:
  - url: https://ai.contentstack.com/brand-kits
    description: AWS North America Production Server
  - url: https://eu-ai.contentstack.com/brand-kits
    description: AWS Europe Production Server
  - url: https://au-ai.contentstack.com/brand-kits
    description: AWS Australia Production Server
  - url: https://azure-na-ai.contentstack.com/brand-kits
    description: Azure North America Production Server
  - url: https://azure-eu-ai.contentstack.com/brand-kits
    description: Azure Europe Production Server
  - url: https://gcp-na-ai.contentstack.com/brand-kits
    description: GCP North America Production Server
  - url: https://gcp-eu-ai.contentstack.com/brand-kits
    description: GCP Europe Production Server
tags:
  - name: Generative AI
    description: >-
      The Generative AI endpoint processes prompts using retrieval augmented
      generation, retrieving relevant brand knowledge and applying voice profile
      style guidelines to produce on-brand content. Responses are returned as
      streaming dictionary responses for real-time content delivery.
security:
  - bearerAuth: []
  - authtokenAuth: []
paths:
  /v1/genai/:
    post:
      operationId: generateContent
      summary: Generate AI content
      description: >-
        Processes a prompt using retrieval augmented generation (RAG) to produce
        AI-generated content aligned with the specified Brand Kit. When
        knowledge_vault is enabled, relevant content from the Brand Kit's
        Knowledge Vault is retrieved and used as context for the LLM. An
        optional voice_profile_uid can be specified to apply specific writing
        style guidelines to the generated content. Returns a streaming
        dictionary response. Rate limited to 10 requests per second per
        organization.
      tags:
        - Generative AI
      parameters:
        - $ref: '#/components/parameters/AuthToken'
        - $ref: '#/components/parameters/BrandKitUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenAIRequest'
      responses:
        '200':
          description: >-
            Streaming dictionary response containing the AI-generated content
            based on the prompt and retrieved knowledge context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenAIResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  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.
  parameters:
    AuthToken:
      name: authtoken
      in: header
      required: true
      description: User authentication token for authorization.
      schema:
        type: string
    BrandKitUid:
      name: brand_kit_uid
      in: header
      required: true
      description: >-
        The unique identifier of the Brand Kit to use for knowledge retrieval
        and brand guidelines during content generation.
      schema:
        type: string
  responses:
    BadRequest:
      description: The request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded. Maximum 10 requests per second per organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    GenAIRequest:
      type: object
      description: Parameters for an AI content generation request.
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: >-
            The content generation prompt to send to the LLM. Provide clear,
            specific instructions for the type of content to generate.
        knowledge_vault:
          type: boolean
          description: >-
            Set to true to enable knowledge vault retrieval, injecting relevant
            brand knowledge into the LLM context for more accurate and
            brand-aligned responses.
          default: false
        voice_profile_uid:
          type: string
          description: >-
            Optional UID of a Voice Profile to apply. When specified, the voice
            profile's style guidelines are used to shape the tone and format
            of the generated content.
    GenAIResponse:
      type: object
      description: >-
        The AI-generated content response including the generated text and
        token usage metrics.
      properties:
        content:
          type: string
          description: The AI-generated content produced in response to the prompt.
        token_usage:
          $ref: '#/components/schemas/TokenUsage'
    TokenUsage:
      type: object
      description: Token consumption metrics for the generation request.
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens consumed by the input prompt and retrieved context.
        completion_tokens:
          type: integer
          description: Number of tokens consumed by the generated response.
        total_tokens:
          type: integer
          description: Total tokens consumed by the generation request.
    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 identifying the error type.