Configuration API Overview

Overview

The Configuration API provides centralized management of pipeline processing defaults and conditional override rules for the Data Curation API. This is primarily designed for documents ingested through Cloud Content Repository, where configuration is automatically applied based on the source of the document.

The Configuration API allows you to:

Set environment-wide defaults for processing options, such as chunking strategy, chunk size, embedding models, and PII handling.
Create conditional rules that override defaults based on the Cloud Content Repository source ID.
Centrally manage configuration without requiring changes to Cloud Content Repository ingestion workflows.
Ensure consistency in how documents are processed across different content sources.

Cloud Content Repository Integration

The Configuration API is designed for Cloud Content Repository ingestion workflows where documents arrive via SNS/SQS messaging. For ad hoc document processing via the /presign endpoint, processing options are typically specified directly in the request body.

Key Concepts

Environment Configuration

Each environment can have its own configuration document stored in S3. The configuration consists of two main parts:

Component	Description
Defaults	The baseline processing options applied to all requests unless overridden by a rule or explicit request body
Rules	Conditional overrides that apply different settings when document properties match specified conditions

Configuration Hierarchy

When processing a document from Cloud Content Repository, the Data Curation API merges configuration from multiple sources in the following priority order (highest to lowest). This hierarchy ensures that source-specific rules take precedence over general environment defaults:

Matched rule — Configuration from the first rule whose conditions match the document's source ID
Environment defaults — The defaults configured for your environment
System defaults — Built-in fallback values provided by the platform

Rules and Matching

Rules enable you to automatically apply different processing configurations based on the Cloud Content Repository source. Each rule contains the following pieces:

Component	Description
Conditions	Criteria that must match for the rule to apply
Configuration overrides	The processing options to apply when conditions match
Optional name	A descriptive label for the rule

Supported Condition Fields

Rules can match on top-level fields only (no nested, array, or object fields). For example, you can match on cin_sourceId (the Cloud Content Repository source identifier), cin_contentType, or other top-level document properties.

When a document is processed from Cloud Content Repository, rules are evaluated in the order they were created. The first matching rule is applied, and subsequent matches are ignored. If no rules match, only the environment defaults are used.

Testing Rules

Use the POST /config/options/rules/test endpoint to preview which rule, if any, would match a given set of document properties without actually processing a document. This helps to validate your rule logic before documents arrive.

Common Use Cases

Consider the following common use cases for the Configuration API.

Scenario 1: Set Organization-Wide Defaults

Your organization wants all documents to use context-aware chunking with 2000-character chunks and the multilingual embedding model.

To set organization-wide defaults:

Initialize configuration: POST /config/options

Update defaults: PUT /config/options/defaults with:

{
  "chunking": {
    "strategy": "context",
    "chunk_size": 2000
  },
  "embedding": {
    "model": "cohere.embed-multilingual-v3"
  }
}

Now all API consumers inherit these settings without specifying them in each request.

Scenario 2: Configure Processing by Cloud Content Repository Source

Documents from a specific Cloud Content Repository source should use larger chunks.

To configure processing by Cloud Content Repository source:

Create a rule: POST /config/options/rules with:

{
  "name": "Large chunks for legal documents source",
  "conditions": [
    {
      "field": "cin_sourceId",
      "value": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "config": {
    "chunking": {
      "chunk_size": 3000
    }
  }
}

When documents from that Cloud Content Repository source are processed, they automatically use 3000-character chunks while other sources use the default chunks.

Scenario 3: Customize Embedding Model by Source

Documents from a specific Cloud Content Repository source should use a different embedding model optimized for their language.

To customize the embedding model by source:

Create a rule: POST /config/options/rules with:

{
  "name": "Multilingual embeddings for international content",
  "conditions": [
    {
      "field": "cin_sourceId",
      "value": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "config": {
    "embedding": {
      "model": "cohere.embed-multilingual-v3"
    }
  }
}

When documents arrive from that Cloud Content Repository source, they use the multilingual embedding model while documents from other sources use the environment default embedding settings.

Permissions

The Configuration API requires specific roles to access:

Operation	Required Role	Endpoints
Read	Data Curation User or Data Curation Admin	All `GET` endpoints
Write	Data Curation Admin	`POST`, `PUT`, and `DELETE` endpoints

Admin Role Required for Changes

Your service user or OAuth client must be assigned the Data Curation Admin role to create, update, or delete configuration. The Data Curation User role provides read-only access to view existing configuration.

Your organization's administrator can grant these roles by assigning user groups to roles in the Hyland CIC Administration Portal.

Getting Started

To begin using the Configuration API, complete the following tasks.

1. Initialize Configuration

Before you can set defaults or create rules, initialize the configuration for your environment:

POST /config/options
Authorization: Bearer <your-token>

This creates a new configuration document with system defaults and an empty rules array.

2. Set Your Defaults

Update the defaults to match your organization's needs, as shown in the following example:

PUT /config/options/defaults
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "chunking": {
    "strategy": "context",
    "chunk_size": 2000
  },
  "embedding": {
    "model": "cohere.embed-multilingual-v3"
  },
  "pii": {
    "mode": "redaction"
  }
}

3. Create Rules (Optional)

Add conditional overrides for specific Cloud Content Repository sources:

POST /config/options/rules
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "name": "Large chunks for legal documents source",
  "conditions": [
    {
      "field": "cin_sourceId",
      "value": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "config": {
    "chunking": {
      "chunk_size": 3000
    }
  }
}

4. Verify Configuration

Retrieve your complete configuration to verify:

GET /config/options
Authorization: Bearer <your-token>

You can also test how rules will match against specific document properties before processing real documents:

POST /config/options/rules/test
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "cin_sourceId": "book123",
  "cin_contentType": "application/pdf"
}

The response shows which rule (if any) would match, along with the effective configuration that would be applied. This is useful for validating your rule logic without affecting actual document processing.

Configuration Fields

The Configuration API accepts the same processing options as the /presign endpoint. For a complete reference of available fields, their validation rules, and detailed descriptions, see the Endpoints documentation.

Common configuration fields include the following:

Field	Description
`chunking`	Chunking configuration (strategy, chunk_size, location_reporting)
`embedding`	Embedding configuration (model, precision)
`normalization`	Unicode text normalization rules (quotations, dashes)
`pii`	PII detection or redaction settings (mode, entity_redaction)
`json_schema`	Structured JSON output format

Cloud Content Repository Requirements

Cloud Content Repository requires chunking and embedding to be enabled. Attempts to disable these features (by setting them to false, null, or empty objects) are dismissed with a warning message. The system preserves any existing valid chunking/embedding configuration instead. This ensures all Cloud Content Repository documents are indexed and searchable.

API Endpoints

The Configuration API provides the following operations:

Operation	Endpoint	Description
Initialize	`POST /config/options`	Create configuration with system defaults.
Get Full Config	`GET /config/options`	Retrieve complete configuration (defaults + rules).
Get Defaults	`GET /config/options/defaults`	Retrieve only the defaults section.
Update Defaults	`PUT /config/options/defaults`	Replace environment defaults.
Reset Defaults	`DELETE /config/options/defaults`	Reset to Cloud Content Repository-compliant system defaults.
List Rules	`GET /config/options/rules`	Retrieve all rules.
Create Rule	`POST /config/options/rules`	Add a new conditional rule.
Get Rule	`GET /config/options/rules/{rule_id}`	Retrieve a specific rule.
Update Rule	`PUT /config/options/rules/{rule_id}`	Modify an existing rule.
Delete Rule	`DELETE /config/options/rules/{rule_id}`	Remove a rule.
Test Rules	`POST /config/options/rules/test`	Preview rule matching (dry run).

For detailed endpoint schemas, request/response examples, and error codes, see the Endpoints reference.

Important Notes

When working with the Configuration API, also consider the following items.

Configuration Size Limit

Configuration documents are limited to 50 KB in total size. This includes defaults, all rules, and metadata. If you exceed this limit, the API returns a 400 Bad Request error.

Rule Matching Behavior

Rules are evaluated in the order they were created.
Only the first matching rule is applied per request.
If multiple rules match, a warning is returned but processing continues with the first match.
You can use the test endpoint to validate your rule logic before relying on it in production.

Environment Isolation

Configuration is scoped to your environment.
You cannot access or modify configuration for other environments.
The environment ID is automatically derived from your authentication token.

Configuration Updates

Changes to configuration take effect immediately for new requests.
Existing in-flight pipeline jobs continue using the configuration that was active when they started.
There is no versioning or rollback mechanism. Consider testing changes in a non-production environment first.

Cloud Content Repository Validation

Chunking and embedding cannot be disabled for Cloud Content Repository documents.
Any attempts to set chunking: false, embedding: false, or equivalent empty/null values are ignored.
The API returns warning messages in the response when disablement attempts are detected.
If you have existing valid chunking/embedding configuration, it is preserved if you attempt to disable these features.
System defaults (from POST /config/options or DELETE /config/options/defaults) are automatically Cloud Content Repository-compliant with chunking and embedding enabled.

Next Steps

See the Endpoints reference for complete API schemas, configuration field descriptions, and examples
Contact your administrator to request the Data Curation Admin role if you need to manage configuration

Overview​

Key Concepts​

Environment Configuration​

Configuration Hierarchy​

Rules and Matching​

Common Use Cases​

Scenario 1: Set Organization-Wide Defaults​

Scenario 2: Configure Processing by Cloud Content Repository Source​

Scenario 3: Customize Embedding Model by Source​

Permissions​

Getting Started​

1. Initialize Configuration​

2. Set Your Defaults​

3. Create Rules (Optional)​

4. Verify Configuration​

Configuration Fields​

API Endpoints​

Important Notes​

Configuration Size Limit​

Rule Matching Behavior​

Environment Isolation​

Configuration Updates​

Cloud Content Repository Validation​

Next Steps​