NiCE Documents API

: Knowledge hub Custom connector document ingestion operations

GitHub OpenAPI

Operations 2

POST /eai-knowledge-hub-services/ingestion-service/v1/documents Process documents #
POST /eai-knowledge-hub-services/ingestion-service/v1/{khId}/documents/snapshot New in 26.1 release - Get snapshot of ingested documents #

Specifications

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nice:nice-documents-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nice-documents-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Nice Documents API
  version: v1
  description: 'Operations tagged Documents across 2 of this provider''s published API definitions: nice-cxone-documents.json, nice-cxone-documents-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Documents
  description: ': Knowledge hub Custom connector document ingestion operations'
paths:
  /eai-knowledge-hub-services/ingestion-service/v1/documents:
    post:
      tags:
      - Documents
      summary: Process documents
      operationId: createKnowledgeHubConfiguration
      description: This API is used to ingest document content and metadata into knowledgehub and datasource. The Token which will be used, for that tenant knowledge hub license must be enabled and user must have khConfig:view permission. Pre-Setup:- Tenant must have created knowledgeBase via KnowledgeHub UI. Please contact to Professional service team or TAM for your tenant, they will provide with knowledgeHubId & dataSourceId. Total number of files accepted per request - 50, each file max file size - 30MB
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              description: Document ingestion request payload
              required:
              - clientToken
              - dataSourceId
              - knowledgeHubId
              - documents
              properties:
                clientToken:
                  type: string
                  description: A UUID v4 token to uniquely identify and track the request
                  example: 5632fde8-5b70-4b47-a0ca-dbeb5501a553
                dataSourceId:
                  type: string
                  description: UUID of the data source where documents will be ingested
                  example: 7539e98b-4ae3-47e4-bc56-4ecebf892469
                knowledgeHubId:
                  type: string
                  description: UUID of the Knowledge Hub instance
                  example: 148849ee-3688-4894-84fb-d1accee61f31
                documents:
                  type: string
                  description: JSON string containing an array of document objects. Each document object should contain the `content` and `metadata` properties. The content property should include the `documentIdentifier` and `inlineContent` or `byteContent` properties. `deleted` property when used `documentIdentifier` is must to be provided. In Metadata, Caller must provide `PagePath` and `Title` metadata field in exact case as its required for retrieval(If not provided validation error will be thrown). `PageRestriction` and `Tags` is reserved keyword from NICE, This field has two values(public|private) it will be used for retrieval purpose. <br> Metadata attribute value types supported - **STRING** (`stringValue`), **STRING_LIST** (`stringListValue`), **NUMBER** (`numberValue`), **BOOLEAN** (`booleanValue`). The `type` field must match the value field used.
                  example: "[\n  {\n    \"content\": {\n      \"documentIdentifier\": \"my-document-001.txt\",\n      \"deleted\": false,\n      \"parseImage\": false,\n      \"inlineContent\": {\n        \"type\": \"TEXT\",\n        \"textContent\": {\n          \"data\": \"This is a sample document text content.\"\n        }\n      }\n    },\n    \"metadata\": {\n      \"inlineAttributes\": [\n        {\n          \"key\": \"Title\",\n          \"value\": {\n            \"stringValue\": \"Sample page\",\n            \"type\": \"STRING\"\n          }\n        },\n        {\n          \"key\": \"PagePath\",\n          \"value\": {\n            \"stringValue\": \"https://example.com/sample.html\",\n            \"type\": \"STRING\"\n          }\n        },\n        {\n          \"key\": \"categories\",\n          \"value\": {\n            \"stringListValue\": [\n              \"Finance\",\n              \"HR\",\n              \"Compliance\"\n            ],\n            \"type\": \"STRING_LIST\"\n          }\n        },\n        {\n          \"key\": \"Tags\",\n          \"value\": {\n            \"stringListValue\": [\n              \"important\",\n              \"reviewed\",\n              \"updated-2026\"\n            ],\n            \"type\": \"STRING_LIST\"\n          }\n        },\n        {\n          \"key\": \"viewCount\",\n          \"value\": {\n            \"numberValue\": 1250,\n            \"type\": \"NUMBER\"\n          }\n        },\n        {\n          \"key\": \"isPublished\",\n          \"value\": {\n            \"booleanValue\": true,\n            \"type\": \"BOOLEAN\"\n          }\n        }\n      ]\n    }\n  }\n]\n"
                documentParseConfig:
                  type: string
                  description: JSON string containing definition of parsing configuration that needs to be used for parsing document content. This is optional. The field `contentTags` and `permissionAttributeNames` must be provided or `cssClassName` and `permissionAttributeNames` either of them. This parsing config applies on all the documents provided in documents array.
                  example: "{\n  \"conditionalContent\": {\n    \"contentTags\": [\"div\", \"span\"],\n    \"permissionAttributeNames\": [\"data-role\"],\n    \"cssClassName\": [\"string\"]\n  }\n}\n"
      responses:
        '200':
          description: Success - When documents are successfully validated and accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  documentDetails:
                    type: array
                    items:
                      type: object
                      properties:
                        documentIdentifier:
                          type: string
                          description: Unique identifier of the document as provided in request
                        status:
                          enum:
                          - SUBMITTED_SUCCESSFULLY
                          - VALIDATION_ERROR
                          - UNKNOWN_ERROR
                          description: Status indicating if the document was accepted successfully
                          type: string
                        statusReason:
                          type: string
                          description: In case of errors, error description
                        updatedAt:
                          type: string
                          description: Timestamp when the document was accepted
              examples:
                Document response:
                  value:
                    documentDetails:
                    - documentIdentifier: doc001
                      status: SUBMITTED_SUCCESSFULLY
                      statusReason: Successfully parsed
                      updatedAt: '2025-02-21T11:29:47Z'
                    - documentIdentifier: doc002
                      status: VALIDATION_ERROR
                      statusReason: Input content must not be empty
                      updatedAt: '2025-02-21T11:29:47Z'
                    - documentIdentifier: doc003...
                      status: VALIDATION_ERROR
                      statusReason: DocumentIdentifier length exceeds the maximum limit of 2000 characters
                      updatedAt: '2025-02-21T11:29:47Z'
        '400':
          description: Validation Error - Invalid Input (When request is missing required fields)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  error:
                    type: string
              examples:
                Invalid Input:
                  value:
                    message: 'Missing required field: knowledgeHubId'
                    error: INVALID_INPUT
        '401':
          description: Validation Error - Authentication (When Bearer authorization token is invalid or missing)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                Unauthorized:
                  value:
                    message: Unauthorized
        '404':
          description: Not Found (When API endpoint doesn't exist or invalid API path is used)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  error:
                    type: string
              examples:
                Not Found:
                  value:
                    message: Path not found
                    error: NOT_FOUND
        '500':
          description: General Error (When unhandled exceptions occur)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  error:
                    type: string
              examples:
                Internal Server Error:
                  value:
                    message: An unexpected error occurred.
                    error: INTERNAL_SERVER_ERROR
  /eai-knowledge-hub-services/ingestion-service/v1/{khId}/documents/snapshot:
    post:
      tags:
      - Documents
      summary: New in 26.1 release - Get snapshot of ingested documents
      description: 'Retrieves a snapshot view of successfully ingested documents in the Knowledge Base.

        Returns document metadata including filename, last ingestion timestamp, and status.

        Supports pagination with default page size of 25 documents.'
      operationId: getDocumentSnapshot
      parameters:
      - name: khId
        in: path
        required: true
        description: The unique identifier of the Knowledge Hub
        schema:
          type: string
          format: uuid
        example: ac15d016-bc8c-4bea-847c-37304b92cb9d
      - name: Content-Type
        in: header
        required: true
        description: Content type of the request
        schema:
          type: string
          enum:
          - application/json
        example: application/json
      - name: X-B3-Traceid
        in: header
        required: false
        description: Trace ID for request tracking
        schema:
          type: string
          pattern: ^[0-9]+$
        example: 0987612345
      - name: X-B3-Spanid
        in: header
        required: false
        description: Span ID for distributed tracing (optional)
        schema:
          type: string
          pattern: ^[0-9]+$
        example: 0987612345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - dataSourceId
              properties:
                dataSourceId:
                  type: string
                  format: uuid
                  description: UUID of the data source to query documents for
                  example: 06f1d675-788a-4244-a18c-00d0aaec91b6
                pageToken:
                  type: string
                  description: Token for pagination to get next set of results (optional)
                  example: eyJuZXh0VG9rZW4iOiJhYmNkZWYxMjM0NTYifQ==
            examples:
              initialRequest:
                summary: Request without pagination
                value:
                  dataSourceId: 06f1d675-788a-4244-a18c-00d0aaec91b6
              paginatedRequest:
                summary: Request with pagination token
                value:
                  dataSourceId: 06f1d675-788a-4244-a18c-00d0aaec91b6
                  pageToken: eyJuZXh0VG9rZW4iOiJhYmNkZWYxMjM0NTYifQ==
      responses:
        '200':
          description: Successfully retrieved document snapshot
          headers:
            traceId:
              description: Trace ID for request tracking
              schema:
                type: string
              example: trace-12345-abcde
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentSnapshotResponse'
              examples:
                successResponse:
                  summary: Document snapshot response
                  value:
                    documents:
                    - documentIdentifier: financial-report.pdf
                      filename: financial-report.pdf
                      lastUpdatedTimestamp: '2025-06-15T12:34:56Z'
                      ingestionStatus: INDEXED
                    - documentIdentifier: doc-001-user-guide.txt
                      filename: user-guide.txt
                      lastUpdatedTimestamp: '2025-06-15T11:20:30Z'
                      ingestionStatus: INDEXED
                    nextPageToken: eyJuZXh0VG9rZW4iOiJhYmNkZWYxMjM0NTYifQ==
                lastPageResponse:
                  summary: Last page response
                  value:
                    documents:
                    - documentIdentifier: final-document
                      filename: final-document.pdf
                      lastUpdatedTimestamp: '2025-06-15T10:15:45Z'
                      ingestionStatus: INDEXED
        '400':
          description: Bad request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotErrorResponse'
              examples:
                invalidDataSourceId:
                  summary: Invalid dataSourceId format
                  value:
                    error: INVALID_INPUT
                    message: Invalid request input
                invalidKhId:
                  summary: Invalid khId format
                  value:
                    error: INVALID_INPUT
                    message: Invalid request input
                invalidPageToken:
                  summary: Invalid page token
                  value:
                    error: INVALID_INPUT
                    message: Invalid request input
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotErrorResponse'
              examples:
                unauthorized:
                  summary: Missing or invalid authorization token
                  value:
                    error: UNAUTHORIZED
                    message: Authentication token is required
        '404':
          description: Not Found (When API endpoint doesn't exist or invalid API path is used)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotErrorResponse'
              examples:
                unauthorized:
                  summary: API Path not foung
                  value:
                    error: NOT_FOUND
                    message: Path not found
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotErrorResponse'
              examples:
                internalError:
                  summary: Internal server error
                  value:
                    error: INTERNAL_ERROR
                    message: Internal server error, please try again later
components:
  schemas:
    DocumentInfo:
      type: object
      required:
      - documentIdentifier
      - filename
      - lastUpdatedTimestamp
      - ingestionStatus
      properties:
        documentIdentifier:
          type: string
          description: Original document identifier as sent in ingestion request
          example: doc-12345-user-manual
        lastUpdatedTimestamp:
          type: string
          format: date-time
          description: ISO-8601 timestamp when document was last successfully ingested
          example: '2025-06-15T12:34:56Z'
        ingestionStatus:
          enum:
          - INDEXED
          - PARTIALLY_INDEXED
          - PENDING
          - FAILED
          - METADATA_PARTIALLY_INDEXED
          - METADATA_UPDATE_FAILED
          - IGNORED
          - NOT_FOUND
          - STARTING
          - IN_PROGRESS
          - DELETING
          - DELETE_IN_PROGRESS
          type: string
          description: Current ingestion status as documented
    SnapshotErrorResponse:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code identifying the type of error
          example: INVALID_INPUT
        error:
          type: string
          description: Error code identifying the type of error
          example: INVALID_INPUT
        message:
          type: string
          description: Human-readable error message
          example: Invalid request input
    DocumentSnapshotResponse:
      type: object
      required:
      - documents
      properties:
        documents:
          type: array
          description: List of successfully ingested documents
          items:
            $ref: '#/components/schemas/DocumentInfo'
        nextPageToken:
          type:
          - string
          - 'null'
          description: Token to retrieve next page of results (null if no more pages)
          example: eyJuZXh0VG9rZW4iOiJ4eXo3ODkwMTIzNDUifQ==
x-refined-from:
- nice-cxone-documents.json
- nice-cxone-documents-openapi.yml