Content-Aware Storage (CAS) APIs

/cas/api/v1

For more information about Swagger docs, see https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/docs#.

Try APIs from Swagger

In your browser, go to Swagger: https://<console-ibm-spectrum-fusion-ns.apps.openshifturl>/cas/api/v1/docs#.

In Swagger, expand the API and click Try it out.

• /vector_stores

  • Description: It returns a document processor "vector stores" query that you have access to.
  • Method: GET
  • Query parameters:

    Parameter:Type	Description
    "after":string	Optional. A cursor for use in pagination. This parameter is not yet implemented.
    "before":string	Optional. A cursor for use in pagination. This parameter is not yet implemented.
    "limit":int	Optional. A limit on the number of objects to be returned. The default limit is 10.
    "order":string	Optional. Sorts order by the vector store ID - asc for ascending order and desc for descending order. Default value is desc.

  • Usage: Check Swagger.
  • Response: Check Swagger.

• /vector_stores/{vector_store_id}/search

  • Description: Matches the exact words and uses Natural Language Processing (NLP) and machine learning to find results that are semantically relevant. If you do not have access to a specific domain, the API raises a 403 (Invalid access) error. If file-level security is enabled, semantic search results are restricted to only those files, which the CAS query user is authorized to read in the IBM Storage Scale file system.
  • Method: POST
  • Path parameter:

    Parameter:Type	Description
    "vector_store_id":string	Required. Name of a particular document processor that ingested documents from a particular domain.

  • Request body parameters:

    Parameter:Type	Description
    "query":string	Required. The natural language question that is used by the embedding model to return a list of relevant snippets of text from the ingested documents.
    "filters":dict	Optional. A filter to apply based on file attributes. For more information, see Filter parameters.
    "max_num_results":int	Optional. The maximum number of results returned. The default value is "10".
    "ranking_options":dict	Optional. Ranking options for search default is null: "ranker":str - Optional. The default value is "auto". "score_threshold":float - Optional. The default value is "0". This parameter is not yet implemented.
    "rewrite_query":bool	Optional. Whether to rewrite the natural language query for vector search. This parameter is not yet implemented.
    "enable_source":boolean	Optional. If true, any source information about the document is returned. Default value is "False".
    "enable_content_metadata":boolean	Optional. If true, any metadata about the relevant document is returned. Default value is "False".

  • Usage: Check Swagger.
  • Response: Check Swagger.

• /vector_stores/{vector_store_id}/files/{file_id}/content

  • Description: It returns all the content (text chunks) for a specific vector-store and file by their IDs.
  • Method: GET
  • Query parameters:

    Parameter	Description
    enable_source	Optional. When enabled, it returns top-level source file metadata attributes, or null, if not enabled.
    enable_content_metadata	Optional. When enabled, it returns content metadata attributes, or null, if not enabled.

  • Usage: Check Swagger.
  • Response: Check Swagger.

Filter parameters

Two types of filters can be used:

• Comparison filter: A filter used to compare a specified attribute key to a defined value using a defined comparison operation.

  Parameter	Type	Description
  key	str	Required. The key to compare against the value.
  type	str	Required. Comparison operators: eq, ne, gt, gte, lt, lte, in, nin The set of valid operators for a comparison filter depends on the key being compared.
  value	str, int, float, bool, ISO8601 str	Required. The value to compare against the key, which can be an array for in or nin operators.

• Compound filter: A filter used to combine an array of filters using and or or.

  Parameter	Type	Description
  type	str	Required. A type of logical operation: and, or.
  filters	array	Required. An array of filters to combine. Items can be Comparison filter or Compound filter.

Supported keys:

Key	Type	Description
file_id	str	The file identifier.
file_size	int, float	The size of the file in bytes.
file_path	str	The full path of the file including the file name.
file_name	str	The full name of the file after the last path delimiter.
file_type	str	The type of source file as determined by the ingester (for example: PDF).
file_created	ISO8601 str	The creation date of the file in ISO8601 format.
file_modified	ISO8601 str	The last modified date of the file in ISO8601 format.
attributes	str, int, bool	The custom attributes set on the file through IBM Data Cataloging service tags. For more information, see Managing tags.

Supported comparison operators for key types:

Key type	Operators
str	eq, ne, in, nin, contains
int, float	eq, ne, gt, gte, lt, lte, in, nin
ISO8601 str	eq, ne, gt, gte, lt, lte, in, nin
bool	eq, ne

Note: When using the in or nin operators, the value parameter of the comparison must be an array of the appropriate type.

Examples

• Comparison filter:

  "filters": {"key":"file_name","type":"eq","value":"sg248497.pdf"}

• Compound filter:

  "filters": {
      "type": "and",
      "filters": [ {"key":"file_path","type":"eq","value":"/gpfs/fs1/gt20"},
                   {"key":"file_size","type":"lt","value":28000000},
                   {"key":"file_size","type":"gt","value":24000000}
                 ]
  }

• Compound filters support two nesting levels:

  "filters": {
      "type":"or",
      "filters": [ {"key":"file_size","type":"gt","value":2000000},
                   {"type":"and",
                    "filters": [ {"key":"date_created","type":"gt","value":"2021-05-01"},
                                 {"key":"date_created","type":"lt","value":"2021-05-31"}
                               ]
                   }
                 ]
  }

/api/v1/querysearch

Try APIs from Swagger

In your browser, go to Swagger: https://<fusionconsoleurl>/api/v1/querysearch/docs.

In Swagger, expand the API and click Try it out.

• /tables

  • Description: It returns a document processor "tables" query that you have access to.

  • Method: GET

  • Usage: Check Swagger.

  • Response: Check Swagger.

• /semantic_search

  • Description: Matches the exact words and uses Natural Language Processing (NLP) and machine learning to find results that are semantically relevant. If you do not have access of a specific domain, the API raises a 403 (Invalid access) error. If file-level security is enabled, semantic search results are restricted to only those files, which the CAS query user is authorized to read in the IBM Storage Scale file system.

  • Method: POST

  • Parameters:

    Parameter: Type	Description
    "query": string	The natural language question that is used by the embedding model to return a list of relevant snippets of text from the ingested documents.
    "table": string	Name of a particular document processor that ingested documents from a specific domain.
    "limit": int	The maximum number of results returned, default is 5.
    "enable_source": boolean	If true, any source information about the document is returned.
    "enable_content_metadata": boolean	If true, any metadata about the relevant document is returned.

  • Usage: Check Swagger.

  • Response: Check Swagger.

End-user CLI chatbot sample

The CLI-powered chatbot enables a secured, authenticated access to Content-Aware Storage (CAS) through a conversational CLI. It is powered by LLMs such as IBM watsonx Granite, Open AI, NVIDIA NIM, and Ollama. It uses CAS's semantic APIs to deliver efficient, AI-enabled insights, accelerating RAG workflows with improved performance, security, and efficiency.

For more information, follow the reference example in GitHub.

Access Control List (ACL) users control the query search process. The system retrieves user identities from the Identity Provider (such as Keycloak) and validates them against CAS ACL users based on roles and permissions. If validation succeeds, the system issues a token, which the user uses to run the CAS query API.