Contentstack Knowledge Vault API

openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Knowledge Vault 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: Knowledge Vault
  description: Knowledge Vault endpoints allow developers to programmatically manage the brand knowledge content stored in a Brand Kit's vector database. Content items are vectorized upon ingestion and used to provide contextually relevant information during AI content generation.
paths:
  /v1/knowledge-vault/:
    post:
      operationId: ingestKnowledgeVaultContent
      summary: Ingest content into Knowledge Vault
      description: Adds new content to the Knowledge Vault associated with the specified Brand Kit. The content is vectorized and stored in the vector database for retrieval during AI content generation. Rate limited to 10 requests per second per organization.
      tags:
      - Knowledge Vault
      parameters:
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/BrandKitUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestContentRequest'
      responses:
        '200':
          description: Content ingested and vectorized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeVaultResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/knowledge-vault/{content_uid}:
    put:
      operationId: updateKnowledgeVaultContent
      summary: Update Knowledge Vault content
      description: Updates an existing content item in the Knowledge Vault. The content is re-vectorized after update to reflect the changes in the vector database.
      tags:
      - Knowledge Vault
      parameters:
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/BrandKitUid'
      - $ref: '#/components/parameters/ContentUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestContentRequest'
      responses:
        '200':
          description: Content updated and re-vectorized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeVaultResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      operationId: deleteKnowledgeVaultContent
      summary: Delete Knowledge Vault content
      description: Permanently removes a content item from the Knowledge Vault vector database. Deleted content will no longer be available for retrieval during AI content generation.
      tags:
      - Knowledge Vault
      parameters:
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/BrandKitUid'
      - $ref: '#/components/parameters/ContentUid'
      responses:
        '200':
          description: Content deleted from Knowledge Vault successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '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'
    NotFound:
      description: The requested content item was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    BrandKitUid:
      name: brand_kit_uid
      in: header
      required: true
      description: The unique identifier of the Brand Kit whose Knowledge Vault to access.
      schema:
        type: string
    AuthToken:
      name: authtoken
      in: header
      required: true
      description: User authentication token for authorization.
      schema:
        type: string
    ContentUid:
      name: content_uid
      in: path
      required: true
      description: The unique identifier of the Knowledge Vault content item.
      schema:
        type: string
  schemas:
    DeleteResponse:
      type: object
      description: Response returned after a successful Knowledge Vault delete operation.
      properties:
        message:
          type: string
          description: Confirmation message for the deletion.
    KnowledgeVaultResponse:
      type: object
      description: Response returned after a successful Knowledge Vault ingest or update operation.
      properties:
        message:
          type: string
          description: Confirmation message for the operation.
        uid:
          type: string
          description: Unique identifier assigned to the ingested content item.
        token_usage:
          $ref: '#/components/schemas/TokenUsage'
    IngestContentRequest:
      type: object
      description: Parameters for ingesting or updating a Knowledge Vault content item.
      required:
      - content
      properties:
        content:
          type: string
          description: The text content to ingest into the Knowledge Vault. This content will be vectorized and stored for retrieval during AI generation.
        title:
          type: string
          description: Optional title or label for the content item.
        metadata:
          type: object
          description: Optional key-value metadata to associate with the content item.
          additionalProperties:
            type: string
    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 vectorization operation.
      properties:
        prompt_tokens:
          type: integer
          description: Number of tokens consumed in processing the content.
        total_tokens:
          type: integer
          description: Total tokens consumed by the operation.
  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