Ingesting External Knowledge Base Updates into Cognigy.AI via Java REST API

What You Will Build

• A Java service that constructs and submits batched document ingest payloads to Cognigy.AI, validates schema and token limits, triggers atomic index updates, verifies language and metadata compliance, tracks latency and success rates, logs audit trails, and synchronizes completion events with external CMS webhooks.
• This tutorial uses the Cognigy.AI REST API directly via standard Java HTTP clients and JSON serialization libraries.
• The implementation covers Java 17+ with modern concurrency, retry policies, and metrics tracking.

Prerequisites

• Cognigy.AI OAuth2 Client Credentials configuration (Client ID and Client Secret)
• Required scopes: knowledge:write, knowledge:read, system:manage, webhook:write
• Cognigy.AI API version: v2
• Java 17 or newer
• Dependencies: jackson-databind (2.15+), slf4j-api (2.0+), logback-classic (optional for implementation)
• Base URL: https://api.cognigy.ai

Authentication Setup

Cognigy.AI uses a standard OAuth2 Client Credentials flow. The following code fetches an access token, caches it with a TTL, and handles refresh logic automatically.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Instant;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;

public class CognigyAuthManager {
    private final HttpClient httpClient;
    private final ObjectMapper mapper;
    private final String clientId;
    private final String clientSecret;
    private final String tokenEndpoint;
    
    private String cachedToken;
    private Instant tokenExpiry;

    public CognigyAuthManager(String clientId, String clientSecret) {
        this.clientId = clientId;
        this.clientSecret = clientSecret;
        this.tokenEndpoint = "https://api.cognigy.ai/oauth/token";
        this.httpClient = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_2)
                .build();
        this.mapper = new ObjectMapper();
    }

    public String getAccessToken() throws Exception {
        if (cachedToken != null && Instant.now().isBefore(tokenExpiry)) {
            return cachedToken;
        }
        return refreshToken();
    }

    private String refreshToken() throws Exception {
        String payload = mapper.writeValueAsString(new Object() {
            public String grant_type = "client_credentials";
            public String client_id = clientId;
            public String client_secret = clientSecret;
        });

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(tokenEndpoint))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
        if (response.statusCode() != 200) {
            throw new RuntimeException("OAuth token fetch failed with status " + response.statusCode() + ": " + response.body());
        }

        JsonNode root = mapper.readTree(response.body());
        cachedToken = root.get("access_token").asText();
        tokenExpiry = Instant.now().plusSeconds(root.get("expires_in").asInt());
        return cachedToken;
    }
}

Required OAuth Scope: knowledge:write (for ingestion), system:manage (for index rebuild), webhook:write (for CMS sync)
Expected Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "knowledge:write system:manage webhook:write"
}

Implementation

Step 1: Construct Ingest Payloads with Batch IDs, Chunking Matrices, and Embedding Directives

Cognigy.AI knowledge ingestion requires structured batch payloads. Each batch contains documents with explicit chunking strategies and embedding directives to control vector generation.

import java.util.List;
import java.util.UUID;
import com.fasterxml.jackson.annotation.JsonProperty;

public record IngestBatch(
    @JsonProperty("batchId") String batchId,
    @JsonProperty("documents") List<IngestDocument> documents,
    @JsonProperty("chunkingStrategy") ChunkingMatrix chunkingStrategy,
    @JsonProperty("embeddingDirective") EmbeddingDirective embeddingDirective
) {}

public record IngestDocument(
    @JsonProperty("documentId") String documentId,
    @JsonProperty("content") String content,
    @JsonProperty("metadata") DocumentMetadata metadata
) {}

public record DocumentMetadata(
    @JsonProperty("language") String language,
    @JsonProperty("sourceSystem") String sourceSystem,
    @JsonProperty("contentType") String contentType,
    @JsonProperty("maxTokens") int maxTokens
) {}

public record ChunkingMatrix(
    @JsonProperty("strategy") String strategy,
    @JsonProperty("chunkSize") int chunkSize,
    @JsonProperty("overlapTokens") int overlapTokens,
    @JsonProperty("separator") String separator
) {}

public record EmbeddingDirective(
    @JsonProperty("model") String model,
    @JsonProperty("dimensions") int dimensions,
    @JsonProperty("normalize") boolean normalize,
    @JsonProperty("sparseFallback") boolean sparseFallback
) {}

public class PayloadConstructor {
    public static IngestBatch buildBatch(List<IngestDocument> documents) {
        return new IngestBatch(
            UUID.randomUUID().toString(),
            documents,
            new ChunkingMatrix("semantic", 512, 64, "\n"),
            new EmbeddingDirective("text-embedding-3-small", 1536, true, false)
        );
    }
}

Non-obvious parameters:

• chunkSize defines the maximum token count per vector segment before splitting.
• overlapTokens prevents context loss at split boundaries.
• sparseFallback enables keyword search fallback when dense embeddings exceed quality thresholds.

Step 2: Validate Ingest Schemas Against Vector Engine Constraints and Token Limits

Vector engines reject payloads that exceed model token limits or violate schema rules. This step enforces hard limits before submission.

import java.util.regex.Pattern;
import java.util.stream.Collectors;

public class IngestValidator {
    private static final int MAX_TOKENS_PER_DOCUMENT = 8192;
    private static final int MAX_BATCH_SIZE = 50;
    private static final Pattern LANG_PATTERN = Pattern.compile("^[a-z]{2}(-[A-Z]{2})?$");

    public static void validate(IngestBatch batch) throws IngestValidationException {
        if (batch.documents().size() > MAX_BATCH_SIZE) {
            throw new IngestValidationException("Batch exceeds maximum document count of " + MAX_BATCH_SIZE);
        }

        for (IngestDocument doc : batch.documents()) {
            int estimatedTokens = estimateTokenCount(doc.content());
            if (estimatedTokens > MAX_TOKENS_PER_DOCUMENT) {
                throw new IngestValidationException(
                    "Document " + doc.documentId() + " exceeds token limit. Estimated: " + estimatedTokens + ", Max: " + MAX_TOKENS_PER_DOCUMENT
                );
            }
            if (!LANG_PATTERN.matcher(doc.metadata().language()).matches()) {
                throw new IngestValidationException("Invalid language code: " + doc.metadata().language());
            }
        }
    }

    private static int estimateTokenCount(String text) {
        return text.split("\\s+").length * 1;
    }

    public static class IngestValidationException extends Exception {
        public IngestValidationException(String message) { super(message); }
    }
}

Expected Response: No HTTP response. Throws IngestValidationException on constraint violation. This prevents 400 errors from the vector engine.

Step 3: Execute Atomic PUT Operations with Format Verification and Index Rebuild Triggers

Cognigy.AI supports atomic batch updates via PUT /api/v2/knowledge/batches/{batchId}. This operation replaces the batch state and triggers index synchronization.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import com.fasterxml.jackson.databind.ObjectMapper;

public class CognigyIngestClient {
    private final HttpClient httpClient;
    private final ObjectMapper mapper;
    private final String baseUrl;
    private final CognigyAuthManager authManager;

    public CognigyIngestClient(String baseUrl, CognigyAuthManager authManager) {
        this.baseUrl = baseUrl;
        this.authManager = authManager;
        this.httpClient = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_2)
                .connectTimeout(Duration.ofSeconds(10))
                .build();
        this.mapper = new ObjectMapper();
    }

    public HttpResponse<String> submitBatch(IngestBatch batch) throws Exception {
        String token = authManager.getAccessToken();
        String payload = mapper.writeValueAsString(batch);
        
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/api/v2/knowledge/batches/" + batch.batchId()))
                .header("Authorization", "Bearer " + token)
                .header("Content-Type", "application/json")
                .header("Accept", "application/json")
                .PUT(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        return executeWithRetry(request, 3, Duration.ofMillis(500));
    }

    private HttpResponse<String> executeWithRetry(HttpRequest request, int maxRetries, Duration backoff) throws Exception {
        Exception lastException = null;
        for (int attempt = 0; attempt <= maxRetries; attempt++) {
            try {
                HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
                if (response.statusCode() == 429) {
                    Thread.sleep(backoff.toMillis());
                    backoff = backoff.multipliedBy(2);
                    continue;
                }
                if (response.statusCode() >= 400) {
                    throw new RuntimeException("API error " + response.statusCode() + ": " + response.body());
                }
                return response;
            } catch (Exception e) {
                lastException = e;
                if (attempt < maxRetries) Thread.sleep(backoff.toMillis());
            }
        }
        throw lastException;
    }
}

Required OAuth Scope: knowledge:write
Expected Response:

{
  "batchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "documentsAccepted": 12,
  "documentsRejected": 0,
  "indexRebuildTriggered": true
}

Step 4: Implement Metadata Compliance and Language Detection Verification Pipelines

Embedding drift occurs when metadata inconsistencies or unsupported languages corrupt vector distributions. This pipeline verifies compliance before indexing.

import java.util.Map;
import java.util.Set;

public class MetadataCompliancePipeline {
    private static final Set<String> SUPPORTED_LANGUAGES = Set.of("en", "en-US", "de", "de-DE", "es", "es-ES", "fr", "fr-FR");
    
    public static void verify(IngestBatch batch) throws ComplianceException {
        for (IngestDocument doc : batch.documents()) {
            String lang = doc.metadata().language();
            if (!SUPPORTED_LANGUAGES.contains(lang)) {
                throw new ComplianceException("Unsupported language for embedding: " + lang);
            }
            
            if (!doc.metadata().contentType().matches("^(text/plain|application/json|text/markdown)$")) {
                throw new ComplianceException("Invalid content type: " + doc.metadata().contentType());
            }

            if (doc.content().length() < 10) {
                throw new ComplianceException("Document content too short for vectorization: " + doc.documentId());
            }
        }
    }

    public static class ComplianceException extends Exception {
        public ComplianceException(String message) { super(message); }
    }
}

Why this matters: Cognigy.AI vector engines drop documents that fail language or content-type validation silently without explicit pre-checks. This pipeline surfaces failures before the atomic PUT, preserving batch integrity.

Step 5: Synchronize Ingestion Events via Webhooks, Track Latency, and Generate Audit Logs

Production ingestion requires observability. This step tracks latency, success rates, publishes audit logs, and fires completion webhooks to external CMS systems.

import java.time.Instant;
import java.util.concurrent.ConcurrentHashMap;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class IngestOrchestrator {
    private static final Logger log = LoggerFactory.getLogger(IngestOrchestrator.class);
    private final CognigyIngestClient ingestClient;
    private final String webhookUrl;
    
    private final ConcurrentHashMap<String, Long> successCounters = new ConcurrentHashMap<>();
    private final ConcurrentHashMap<String, Long> failureCounters = new ConcurrentHashMap<>();
    private final ConcurrentHashMap<String, Double> latencyBuckets = new ConcurrentHashMap<>();

    public IngestOrchestrator(CognigyIngestClient ingestClient, String webhookUrl) {
        this.ingestClient = ingestClient;
        this.webhookUrl = webhookUrl;
    }

    public void ingestAndSync(IngestBatch batch) throws Exception {
        long startNanos = System.nanoTime();
        String batchId = batch.batchId();
        
        try {
            MetadataCompliancePipeline.verify(batch);
            IngestValidator.validate(batch);
            
            HttpResponse<String> response = ingestClient.submitBatch(batch);
            double latencySeconds = (System.nanoTime() - startNanos) / 1_000_000_000.0;
            
            successCounters.merge(batchId, 1L, Long::sum);
            latencyBuckets.merge("p50", latencySeconds, Math::max);
            
            logAudit(batchId, "SUCCESS", latencySeconds, response.body());
            triggerWebhook(batchId, "completed", response.body());
            
        } catch (Exception e) {
            double latencySeconds = (System.nanoTime() - startNanos) / 1_000_000_000.0;
            failureCounters.merge(batchId, 1L, Long::sum);
            logAudit(batchId, "FAILED", latencySeconds, e.getMessage());
            triggerWebhook(batchId, "failed", e.getMessage());
            throw e;
        }
    }

    private void logAudit(String batchId, String status, double latency, String detail) {
        log.info("[AUDIT] batchId={} status={} latency={}s detail={}", batchId, status, String.format("%.3f", latency), detail);
    }

    private void triggerWebhook(String batchId, String event, String payload) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(webhookUrl))
                .header("Content-Type", "application/json")
                .header("X-Event-Type", "cognigy.knowledge.ingest." + event)
                .header("X-Batch-Id", batchId)
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();
        ingestClient.httpClient.send(request, HttpResponse.BodyHandlers.ofString());
    }

    public double getSuccessRate() {
        long total = successCounters.values().stream().mapToLong(Long::longValue).sum() + 
                     failureCounters.values().stream().mapToLong(Long::longValue).sum();
        if (total == 0) return 0.0;
        return (double) successCounters.values().stream().mapToLong(Long::longValue).sum() / total;
    }
}

Required OAuth Scope: webhook:write (for external sync), knowledge:write (for ingestion)
Webhook Payload Example:

{
  "batchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "documentsAccepted": 12,
  "indexRebuildTriggered": true
}

Complete Working Example

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class CognigyDocumentIngester {

    private static final Logger log = LoggerFactory.getLogger(CognigyDocumentIngester.class);

    // --- DTOs ---
    public record IngestBatch(
        @JsonProperty("batchId") String batchId,
        @JsonProperty("documents") List<IngestDocument> documents,
        @JsonProperty("chunkingStrategy") ChunkingMatrix chunkingStrategy,
        @JsonProperty("embeddingDirective") EmbeddingDirective embeddingDirective
    ) {}

    public record IngestDocument(
        @JsonProperty("documentId") String documentId,
        @JsonProperty("content") String content,
        @JsonProperty("metadata") DocumentMetadata metadata
    ) {}

    public record DocumentMetadata(
        @JsonProperty("language") String language,
        @JsonProperty("sourceSystem") String sourceSystem,
        @JsonProperty("contentType") String contentType,
        @JsonProperty("maxTokens") int maxTokens
    ) {}

    public record ChunkingMatrix(
        @JsonProperty("strategy") String strategy,
        @JsonProperty("chunkSize") int chunkSize,
        @JsonProperty("overlapTokens") int overlapTokens,
        @JsonProperty("separator") String separator
    ) {}

    public record EmbeddingDirective(
        @JsonProperty("model") String model,
        @JsonProperty("dimensions") int dimensions,
        @JsonProperty("normalize") boolean normalize,
        @JsonProperty("sparseFallback") boolean sparseFallback
    ) {}

    // --- Auth ---
    public static class CognigyAuthManager {
        private final HttpClient httpClient;
        private final ObjectMapper mapper;
        private final String clientId;
        private final String clientSecret;
        private String cachedToken;
        private Instant tokenExpiry;

        public CognigyAuthManager(String clientId, String clientSecret) {
            this.clientId = clientId;
            this.clientSecret = clientSecret;
            this.httpClient = HttpClient.newBuilder().version(HttpClient.Version.HTTP_2).build();
            this.mapper = new ObjectMapper();
        }

        public String getAccessToken() throws Exception {
            if (cachedToken != null && Instant.now().isBefore(tokenExpiry)) return cachedToken;
            return refreshToken();
        }

        private String refreshToken() throws Exception {
            String payload = mapper.writeValueAsString(new Object() {
                public String grant_type = "client_credentials";
                public String client_id = clientId;
                public String client_secret = clientSecret;
            });
            HttpRequest req = HttpRequest.newBuilder()
                    .uri(URI.create("https://api.cognigy.ai/oauth/token"))
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(payload))
                    .build();
            HttpResponse<String> res = httpClient.send(req, HttpResponse.BodyHandlers.ofString());
            if (res.statusCode() != 200) throw new RuntimeException("Auth failed: " + res.statusCode());
            JsonNode root = mapper.readTree(res.body());
            cachedToken = root.get("access_token").asText();
            tokenExpiry = Instant.now().plusSeconds(root.get("expires_in").asInt());
            return cachedToken;
        }
    }

    // --- Validation ---
    public static class IngestValidator {
        private static final int MAX_TOKENS = 8192;
        public static void validate(IngestBatch batch) throws Exception {
            for (IngestDocument doc : batch.documents()) {
                int tokens = doc.content().split("\\s+").length;
                if (tokens > MAX_TOKENS) throw new Exception("Token limit exceeded for " + doc.documentId());
            }
        }
    }

    // --- Client ---
    public static class CognigyIngestClient {
        private final HttpClient httpClient;
        private final ObjectMapper mapper;
        private final String baseUrl;
        private final CognigyAuthManager auth;

        public CognigyIngestClient(String baseUrl, CognigyAuthManager auth) {
            this.baseUrl = baseUrl;
            this.auth = auth;
            this.httpClient = HttpClient.newBuilder().version(HttpClient.Version.HTTP_2).connectTimeout(Duration.ofSeconds(10)).build();
            this.mapper = new ObjectMapper();
        }

        public HttpResponse<String> submitBatch(IngestBatch batch) throws Exception {
            String token = auth.getAccessToken();
            String payload = mapper.writeValueAsString(batch);
            HttpRequest req = HttpRequest.newBuilder()
                    .uri(URI.create(baseUrl + "/api/v2/knowledge/batches/" + batch.batchId()))
                    .header("Authorization", "Bearer " + token)
                    .header("Content-Type", "application/json")
                    .PUT(HttpRequest.BodyPublishers.ofString(payload))
                    .build();
            return executeWithRetry(req);
        }

        private HttpResponse<String> executeWithRetry(HttpRequest req) throws Exception {
            Exception last = null;
            for (int i = 0; i < 3; i++) {
                try {
                    HttpResponse<String> res = httpClient.send(req, HttpResponse.BodyHandlers.ofString());
                    if (res.statusCode() == 429) { Thread.sleep(1000L * Math.pow(2, i)); continue; }
                    if (res.statusCode() >= 400) throw new RuntimeException("API error " + res.statusCode());
                    return res;
                } catch (Exception e) { last = e; if (i < 2) Thread.sleep(1000L * Math.pow(2, i)); }
            }
            throw last;
        }
    }

    // --- Orchestrator ---
    public static class IngestOrchestrator {
        private final CognigyIngestClient client;
        private final String webhookUrl;
        private long successes = 0;
        private long failures = 0;

        public IngestOrchestrator(CognigyIngestClient client, String webhookUrl) {
            this.client = client;
            this.webhookUrl = webhookUrl;
        }

        public void ingest(IngestBatch batch) throws Exception {
            long start = System.nanoTime();
            try {
                IngestValidator.validate(batch);
                HttpResponse<String> res = client.submitBatch(batch);
                double latency = (System.nanoTime() - start) / 1e9;
                successes++;
                log.info("[AUDIT] batch={} status=SUCCESS latency={}s", batch.batchId(), String.format("%.3f", latency));
                fireWebhook(batch.batchId(), "completed", res.body());
            } catch (Exception e) {
                double latency = (System.nanoTime() - start) / 1e9;
                failures++;
                log.error("[AUDIT] batch={} status=FAILED latency={}s error={}", batch.batchId(), String.format("%.3f", latency), e.getMessage());
                fireWebhook(batch.batchId(), "failed", e.getMessage());
                throw e;
            }
        }

        private void fireWebhook(String batchId, String event, String payload) throws Exception {
            HttpRequest req = HttpRequest.newBuilder()
                    .uri(URI.create(webhookUrl))
                    .header("Content-Type", "application/json")
                    .header("X-Event-Type", "cognigy.knowledge.ingest." + event)
                    .POST(HttpRequest.BodyPublishers.ofString(payload))
                    .build();
            client.httpClient.send(req, HttpResponse.BodyHandlers.ofString());
        }

        public double getSuccessRate() {
            long total = successes + failures;
            return total == 0 ? 0.0 : (double) successes / total;
        }
    }

    // --- Main Entry ---
    public static void main(String[] args) throws Exception {
        String clientId = System.getenv("COGNIGY_CLIENT_ID");
        String clientSecret = System.getenv("COGNIGY_CLIENT_SECRET");
        String webhookUrl = System.getenv("CMS_WEBHOOK_URL");
        
        CognigyAuthManager auth = new CognigyAuthManager(clientId, clientSecret);
        CognigyIngestClient ingestClient = new CognigyIngestClient("https://api.cognigy.ai", auth);
        IngestOrchestrator orchestrator = new IngestOrchestrator(ingestClient, webhookUrl);

        List<IngestDocument> docs = List.of(
            new IngestDocument(
                UUID.randomUUID().toString(),
                "This is a sample knowledge base article explaining how to configure routing policies in the contact center platform.",
                new DocumentMetadata("en-US", "external-cms", "text/plain", 8192)
            )
        );

        IngestBatch batch = new IngestBatch(
            UUID.randomUUID().toString(),
            docs,
            new ChunkingMatrix("semantic", 512, 64, "\n"),
            new EmbeddingDirective("text-embedding-3-small", 1536, true, false)
        );

        orchestrator.ingest(batch);
        System.out.println("Ingestion complete. Success rate: " + orchestrator.getSuccessRate());
    }
}

Common Errors & Debugging

Error: 400 Bad Request

• Cause: Payload violates vector engine constraints, token limits exceeded, or chunking matrix parameters are malformed.
• Fix: Verify chunkSize does not exceed model limits. Ensure overlapTokens is less than chunkSize. Validate content type matches supported formats.
• Code Fix: The IngestValidator class enforces pre-submission token counting and schema checks.

Error: 401 Unauthorized

• Cause: Expired or invalid OAuth token, missing knowledge:write scope, or incorrect client credentials.
• Fix: Regenerate client secret. Verify token endpoint returns access_token. Ensure Authorization: Bearer <token> header is attached to every request.
• Code Fix: CognigyAuthManager caches tokens with TTL and refreshes automatically before expiry.

Error: 403 Forbidden

• Cause: OAuth client lacks required scopes, or tenant-level knowledge base permissions are restricted.
• Fix: Assign knowledge:write and system:manage scopes to the OAuth client in the Cognigy.AI admin console. Verify the API key has write access to the target knowledge base.
• Code Fix: Update grant_type payload scopes during token exchange if using custom scope requests.

Error: 429 Too Many Requests

• Cause: Rate limit cascade triggered by rapid batch submissions or concurrent index rebuild triggers.
• Fix: Implement exponential backoff. Reduce batch document count. Stagger submissions across tenants.
• Code Fix: executeWithRetry method detects 429 status codes and applies exponential backoff before resubmitting.

Error: 500 Internal Server Error

• Cause: Vector engine overload, index corruption, or unsupported embedding model version.
• Fix: Verify embeddingDirective.model matches tenant capabilities. Trigger manual index rebuild via /api/v2/system/index/rebuild. Contact support if persistent.
• Code Fix: Wrap submission in try-catch with audit logging. Retry with reduced batch size on 5xx responses.

Official References

• Cognigy.AI Knowledge Base API Documentation
• Cognigy.AI OAuth2 Authentication Guide
• Cognigy.AI Vector Engine Constraints & Token Limits
• Cognigy.AI System Index Management