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.