Contentstack Generative AI API

openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Generative AI 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: 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.
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:
  responses:
    TooManyRequests:
      description: Rate limit exceeded. Maximum 10 requests per second per organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
  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'
    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.
    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.
  parameters:
    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
    AuthToken:
      name: authtoken
      in: header
      required: true
      description: User authentication token for authorization.
      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