Document Search API

Document Search

These endpoints allow you to search for documents in the Smart-Cache.

Note: These endpoints require authentication which has been deliberately excluded from the example(s) below.

Get Documents

GET /documents

Performs a search over the Smart-Cache, returning documents that match the query and for which the user has permissions.

Parameters

  • query (string, required): The search query.
  • type (string, optional, default: query): Specifies how the query parameter is interpreted.
    • query: Uses the underlying search index’s query syntax.
    • term: Interpreted as a set of terms to be matched exactly.
    • phrase: Interpreted as a complete phrase that must be matched.
    • wildcard: Interpreted as a set of wildcard terms (e.g., pre* matches terms starting with “pre”).
  • limit (integer, optional, default: 100): Maximum number of results to return (1-1000).
  • offset (integer, optional, default: 1): 1-based offset to start returning results from.
  • highlighting (boolean, optional, default: false): Enables result highlighting. If true, results will include a highlighted field.
  • highlighting-pre-tag (string, optional): HTML tag to prepend to highlighted terms.
  • highlighting-post-tag (string, optional): HTML tag to append to highlighted terms.
  • type-filter (string, optional): Entity/identifier type to filter by.
  • is-type-filter-base64 (boolean, optional, default: false): If true, the type-filter will be Base64 decoded.
  • type-filter-mode (string, optional, default: any): Specifies whether to filter by entity, identifier, or any (match either).
  • range-start (string, optional): Specifies the start of a range to filter results.
  • range-end (string, optional): Specifies the end of a range to filter results.
  • range-fields (string, optional): Fields to apply the range filter on (e.g., *primaryName). Supports wildcards.
  • show-security-labels (boolean, optional, default: false): If true, security labels will be returned as part of the documents.
  • indices (string, optional): Specific indices to apply the operation on.

Example Call 

curl -X GET  https://telicent.core.domain/api/search/documents?query=John%20Smith&type=phrase&limit=10&offset=1&highlighting=true

Response

  • 200 OK: Search was successful. Contains SearchResults object.
    • maybeMore (boolean): Indicates if more results might be available.
    • limit (integer): The limit applied to the results.
    • offset (integer): The offset applied to the results.
    • query (string): The query used.
    • type (string): The query type used.
    • results (array of Result): The matched documents, sorted by relevance.
      • id (string): Document ID (internal, not for user display).
      • score (number): Relevance score (internal, not for user display).
      • document (object): The document content.
      • highlighted (object, optional): Highlighted portions of the document.
  • 400 Bad Request: Invalid search parameters or unsupported query type/feature.
  • 500 Internal Server Error: Server failed to process the request.
  • 503 Service Unavailable: No underlying search index available.

Get Documents (POST)

POST /documents

Identical functionality to GET /documents, but allows parameters to be submitted via an application/x-www-form-urlencoded POST request.

Request Body (application/x-www-form-urlencoded)

  • query (string, required): The query string.
  • query-type (string, optional): The type of query.
  • limit (integer, optional): Maximum number of results.
  • offset (integer, optional): Number of results to skip.
  • highlighting-enabled (boolean, optional): Enable or disable highlighting.
  • highlighting-pre-tag (string, optional): Tag to prepend for highlighting.
  • highlighting-post-tag (string, optional): Tag to append for highlighting.
  • type-filter (string, optional): Filter for specific types.
  • is-type-filter-base64 (boolean, optional): true if type-filter is Base64 encoded.
  • type-filter-mode (string, optional): Filter mode (entity, identifier, or match).
  • range-start (string, optional, format: date-time): Start of the range filter.
  • range-end (string, optional, format: date-time): End of the range filter.
  • range-fields (array of string, optional): Fields for range filtering.
  • show-security-labels (boolean, optional): true to include security labels.
  • indices (string, optional): Specific indices to apply the operation to.

Example Call 

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "query=example&limit=5&query-type=term" \
     https://telicent.core.domain/api/search/documents

Response

Same as GET /documents.

Retrieve Documents by ID

GET /documents/{id}

Retrieves a single document based on its ID.

Parameters

  • id (string, required, in path): The ID of the document.
  • is-base64 (boolean, optional, default: false): If true, the id will be Base64 decoded.
  • show-security-labels (boolean, optional, default: false): If true, security labels will be returned as part of the document.
  • indices (string, optional): Specific indices to apply the operation on.

Example Call 

curl -X GET https://telicent.core.domain/api/search/documents/ab45645c?is-base64=false&show-security-labels=true

Response

  • 200 OK: The document was successfully retrieved. Contains a Document object.
  • 400 Bad Request: Insufficient information (e.g., ID omitted).
  • 404 Not Found: Document with the given ID does not exist.
  • 500 Internal Server Error: Server failed to process the request.
  • 503 Service Unavailable: No underlying search index available.

Retrieve Documents by ID (POST)

POST /documents/id

Retrieves a single document by its ID using a POST request, identical to GET /documents/{id} but with parameters in the request body. Note the fixed “id” in the path compared to the GET call’s “{id}”.

Request Body (application/x-www-form-urlencoded)

  • id (string, required): The ID of the document.
  • is-base64 (boolean, optional): Set to true if the ID is Base64 encoded.
  • show-security-labels (boolean, optional): Set to true to include security labels.
  • indices (string, optional): Specific indices to apply the operation to.

Example Call 

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "id=document123&is-base64=false" \
     https://telicent.core.domain/api/search/documents/id

Response

Same as GET /documents/{id}.

Get Document List

GET /list

Retrieves multiple documents based on their IDs. The response will be an object where each ID is a key, mapping to either the document or null if not found.

Parameters

  • id (array of string, required): The IDs of the documents to retrieve.
  • is-base64 (boolean, optional, default: false): If true, the IDs will be Base64 decoded.
  • show-security-labels (boolean, optional, default: false): If true, security labels will be returned.
  • indices (string, optional): Specific indices to apply the operation on.

Example Call 

curl -X GET https://telicent.core.domain/api/search/list?id=doc1&id=doc2&is-base64=false

Response

  • 200 OK: The document selection. Contains a DocumentSelection object (map of ID to Document or null).
  • 400 Bad Request: Insufficient information (e.g., IDs omitted).
  • 500 Internal Server Error: Server failed to process the request.
  • 503 Service Unavailable: No underlying search index available.

Get Document List (POST)

POST /list

Retrieves multiple documents by their IDs using a POST request, identical to GET /list but with parameters in the request body.

Request Body (application/x-www-form-urlencoded)

  • id (array of string, required): The IDs of the documents to retrieve.
  • is-base64 (boolean, optional): Set to true if IDs are Base64 encoded.
  • show-security-labels (boolean, optional): Set to true to include security labels.
  • indices (string, optional): Specific indices to apply the operation to.

Example Call 

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
     -d "id=docA&id=docB&show-security-labels=true" \
     https://telicent.core.domain/api/search/list

Response

Same as GET /list.

Update an Entity in a Document

POST /documents/update-entity

Updates an entity within a search document. It locates an existing entity based on documentUri, entityText, and entityCategory, then adds or updates its resolved URI and category. Entities with the same text and new resolved category will be merged.

Request Body (application/json)

  • documentUri (string, required): The URI of the document to update.
  • entityText (string, required): The text of the entity.
  • entityCategory (string, required): The current entity category URI.
  • resolvedEntityUri (string, required): The resolved entity URI.
  • resolvedCategory (string, required): The new entity category URI.
  • indices (string, optional): Specific indices to apply the operation on.

Example Call 

curl -X POST -H "Content-Type: application/json" \
     -d '{
           "documentUri": "http://telicent.io/docsearch#8d2f893c-9072-476a-801f-48036947cc86",
           "entityText": "Abdelaziz",
           "entityCategory": "http://ies.data.gov.uk/ontology/ies4#Person",
           "resolvedEntityUri": "http://telicent.io/data#abdelaziz_inc",
           "resolvedCategory": "http://ies.data.gov.uk/ontology/ies4#Organisation"
         }' \
     https://telicent.core.domain/api/search/documents/update-entity

Response

  • 200 OK: Document successfully updated. Returns the updated Document object.
  • 400 Bad Request: No matching entities found or invalid request.
  • 500 Internal Server Error: Server failed to process the request.
[EARLY DRAFT RELEASE] Copyright 2020-2025 Telicent Limited. All rights reserved