watsonx.data as a Service on GenAI Unstructured Catalog | IBM Cloud API Docs

Introduction

Last updated: 2025-06-02

GenAI Unstructured retrieval services will be responsible for providing necessary context by querying appropriate data sources via a REST API call. This service processes natural language text queries combined with a specified metadata repository (Document libraries). It interacts with backend services, leverages strategic decision-making interfaces, and generates raw responses to satisfy user requests.

Endpoint URLs

  • Unstructured retrieval API:
    https://{host}/api/v1/retrieval/search
  • Unstructured solution-accelerator API:
    https://{host}/api/v1/retrieval/advanced/search

Authentication for Onprem

Required Purpose: To work with the API, you must use an IBM Cloud Pak for Data authorization token (platform token or instance token). For on-premises deployments, only token-based authentication is supported. The token is used to determine the actions that a user or service ID has access to when they use the API.

You can generate an authorization token for an authenticated user by using the Cloud Pak for Data APIs. For more information, see Generating an authorization token or API key.

To use the API, add a valid token to the HTTP Authorization request header: -H 'Authorization: Bearer {TOKEN}'.

Note: On-premises deployments do not support API key-based authentication.

Curl example (Displayed on the right)

To retrieve your access token:

For most Cloud Pak for Data endpoints, you can use the generated token in the authorization header of subsequent API calls.

curl -H "Authorization: Bearer <token>" "https://<cpd_instance_route>/<endpoint>"

Authentication for IBM Cloud

Required Purpose: To work with the API, you must use an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Curl authentication

You can generate an IAM token for an authenticated user or service ID by using the IAM Identity Services API. For more information, see Generating an IBM Cloud IAM token.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example: -H 'Authorization: Bearer {TOKEN}'

Curl example (Displayed on the right)

To retrieve your IAM access token:

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey={API_KEY}'

Replace {API_KEY} with the API key associated with your IAM identity to obtain the token.

Note: Although this request uses an API key to generate the IAM token, API keys cannot be used directly for authentication. All API requests must use the generated IAM token in the Authorization header.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
201 Created The request was successful and a new resource was created as a result.
202 Accepted The request has been accepted for processing, but the processing is not complete.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
500 Internal Server Error Your request could not be processed. Wait a few minutes and try again.

Methods

Retrieve relevant context for a natural language query

Executes a search query against the Lakehouse document library using SQL and/or vector search.

POST /v1/retrieval/search

Request

Query Parameters

  • async
    boolean

    If true, initiates an asynchronous search operation and returns a job ID. If false or not provided, runs the search synchronously and returns immediate results.

Request Body

Required*
RetrievalQueryRequest

Request payload for performing a search query across sql and vector datasources. Contains the natural language query, identification of document library and container, search configuration, inference configuration, and template suggestion control.

Examples: 
{
  "query": "What is the total of the invoice where the invoice number is 146437 or 287742?",
  "document_library_id": "2ef00505-be9b-4fa0-bde5-03cfbeea326d",
  "container_id": "084df95f-d848-46d9-bd3b-c366bffecf68",
  "container_type": "project",
  "search_config": [
    {
      "type": "vector",
      "enabled": true,
      "limit": 10
    },
    {
      "type": "sql",
      "enabled": true
    }
  ],
  "search_inference_config": {
    "enabled": true,
    "inference_model_id": "ibm/granite-3-2-8b-instruct"
  },
  "provide_suggested_template": true,
  "disable_cache": false
}
  • curl -k --location 'https://{host}/api/v1/retrieval/search' --header 'Authorization: Bearer ' --header 'Content-Type: application/json' --header 'Accept: application/json' --data '{
  "query": "Find the total number of documents",
  "document_library_id": "2556f6b6-4f54-4534-a135-669d6ef99577",
  "container_id": "eb8328f2-5590-4359-8a9a-dcc347dbd363",
  "container_type": "project",
  "searchConfig": [
    {
      "type": "vector",
      "enabled": true,
      "limit": 10
    },
    {
      "type": "sql",
      "enabled": true,
      "limit": 0
    }
  ],
  "search_inference_config": {
    "enabled": true,
    "inference_model_id": "ibm/granite-3-2-8b-instruct"
  },
  "provide_suggested_template": true
  "disable_cache": false
}'

Response

Response Body

RetrievalQueryResponse

Response payload containing search results and metadata

Status Code

  • 200

    Search results containing SQL search, vector search, and additional information.

  • 400

    Bad request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 500

    Internal server error

Example responses
  • {
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "results": [
    {
      "source": "sql",
      "data": [
        {
          "id": "113-0026789-2023",
          "invoice_number": "INV-0026789-2023",
          "sender": "John Doe wilson",
          "amount": "1500.50000000"
        }
      ],
      "metadata": {
        "execution_time": 120,
        "row_count": 1,
        "sql": "SELECT sender, amount FROM invoices WHERE invoice_number = 'INV-002'"
      },
      "summary": "SQL search results for invoice INV-002"
    },
    {
      "source": "vector",
      "data": [
        {
          "id": "101-12345678",
          "embedding_match_score": "0.955678902345",
          "snippet": "Invoice sent by John Doe on 2023-05-12."
        }
      ],
      "metadata": {
        "execution_time": 80,
        "page_number": 3,
        "location": "page_3"
      },
      "summary": "Vector search results matching the query"
    }
  ],
  "status": "success",
  "execution_time": 200,
  "suggested_template": {
    "template_name": "invoice_sender_lookup",
    "template_text": "Find invoices sent by [sender_name]",
    "reasoning": "This template helps to locate invoices filtered by sender name."
  }
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}

Retrieve status and result of an asynchronous search

Checks the status of an async search request and returns the result when complete.

GET /v1/retrieval/search/result/{request_id}

Request

Path Parameters

  • request_id
    Required*
    string

    Unique identifier for the asynchronous search job

    Possible values: 1 ≤ length ≤ 60, Value must match regular expression ^[a-zA-Z0-9_-]{1,60}$

Response

Response Body

RetrievalQueryResponse

Response payload containing search results and metadata

Status Code

  • 200

    Async job completed successfully and results are available

  • 202

    Accepted. Async job started successfully.

  • 404

    Request ID not found

Example responses
  • {
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "results": [
    {
      "source": "sql",
      "data": [
        {
          "id": "113-0026789-2023",
          "invoice_number": "INV-0026789-2023",
          "sender": "John Doe wilson",
          "amount": "1500.5000000000"
        }
      ],
      "metadata": {
        "execution_time": 120,
        "row_count": 1,
        "sql": "SELECT sender, amount FROM invoices WHERE invoice_number = 'INV-002'"
      },
      "summary": "SQL search results for invoice INV-002"
    },
    {
      "source": "vector",
      "data": [
        {
          "id": "101-12345678",
          "embedding_match_score": "0.955678902345",
          "snippet": "Invoice sent by John Doe on 2023-05-12."
        }
      ],
      "metadata": {
        "execution_time": 80
      },
      "summary": "Vector search results matching the query"
    }
  ],
  "status": "success",
  "execution_time": 200,
  "suggested_template": {
    "template_name": "invoice_sender_lookup",
    "template_text": "Find invoices sent by [sender_name]",
    "reasoning": "This template helps to locate invoices filtered by sender name."
  }
}
  • {
  "request_id": "c1e6c466-d828-4a09-bdf2-45a87577f244",
  "status": "success",
  "href": "https://api.example.com/v1/retrieval/search/result/c1e6c466-d828-4a09-bdf2-45a87577f244",
  "message": "Search request submitted successfully"
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}

Perform advanced retrieval of context for a natural language query

Search for contextual information to augment generative AI models based on strategic decision-making.

POST /v1/retrieval/advanced/search

Request

Query Parameters

  • async
    boolean

    If true, initiates an asynchronous search operation and returns a job ID. If false or not provided, runs the search synchronously and returns immediate results.

Request Body

Required*
SolutionQueryRequest

Query request parameters

Examples: 
{
  "query": "What is the total of the invoice where the invoice number is 146437 or 287742?",
  "document_library_id": "2ef00505-be9b-4fa0-bde5-03cfbeea326d",
  "container_id": "084df95f-d848-46d9-bd3b-c366bffecf68",
  "container_type": "project",
  "strategy": "default",
  "search_config": [
    {
      "type": "vector",
      "limit": 10
    }
  ],
  "search_inference_config": {
    "enabled": true,
    "inference_model_id": "ibm/granite-3-2-8b-instruct"
  },
  "disable_cache": false
}
  • curl -k --location 'https://{host}/api/v1/retrieval/advanced/search' --header 'Authorization: Bearer ' --header 'Content-Type: application/json' --header 'Accept: application/json' --data '{
  "query": "Find the total number of documents",
  "document_library_id": "2556f6b6-4f54-4534-a135-669d6ef99577",
  "container_id": "eb8328f2-5590-4359-8a9a-dcc347dbd363",
  "container_type": "project",
  "searchConfig": [
    {
      "type": "vector",
      "limit": 10
    }
  ],
  "search_inference_config": {
    "enabled": true,
    "inference_model_id": "ibm/granite-3-2-8b-instruct"
  }
}'

Response

Response Body

SolutionQueryResponse

Response structure for query results.

Status Code

  • 200

    Query processed successfully

  • 202

    Accepted. Async job started successfully.

  • 400

    Bad request

  • 401

    Unauthorized

  • 403

    Forbidden

  • 500

    Internal server error

Example responses
  • {
  "request_id": "38481862-e4cd-4335-b820-e0f05483ee32",
  "results": [
    {
      "source": "sql",
      "data": [
        {
          "total_invoices": "891"
        }
      ],
      "metadata": {
        "execution_time": 12892,
        "row_count": 1,
        "sql": "SELECT COUNT(*) AS total_invoices FROM invoice"
      },
      "summary": "Total number of invoices"
    }
  ],
  "additional_info": {
    "plan": {
      "chain_of_thought_reasoning": "This query requires counting the total number of invoices, which can be fulfilled using structured fields alone from the iceberg database.",
      "subquestions": [
        {
          "question": "What is the total count of invoices?",
          "tool": "iceberg",
          "label": "$var_1",
          "should_expose_answer": true,
          "answer_description": "Total number of invoices",
          "query_type": ""
        }
      ]
    },
    "fallback": {
      "was_fallback_applied": false,
      "reason": ""
    }
  },
  "status": "success",
  "execution_time": 72530
}
  • {
  "request_id": "c1e6c466-d828-4a09-bdf2-45a87577f244",
  "status": "success",
  "href": "https://api.example.com/v1/retrieval/advanced/search/result/c1e6c466-d828-4a09-bdf2-45a87577f244",
  "message": "Search request submitted successfully"
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}

Retrieve the status and result of an advanced retrieval asynchronous search

Checks the status of an advanced retrieval asynchronous search request and returns the result when complete.

GET /v1/retrieval/advanced/search/result/{request_id}

Request

Path Parameters

  • request_id
    Required*
    string

    Unique identifier for the asynchronous search job

    Possible values: 1 ≤ length ≤ 60, Value must match regular expression ^[a-zA-Z0-9_-]{1,60}$

Response

Response Body

SolutionQueryResponse

Response structure for query results.

Status Code

  • 200

    Async job completed successfully and results are available

  • 404

    Request ID not found

Example responses
  • {
  "request_id": "38481862-e4cd-4335-b820-e0f05483ee32",
  "generated_text": "The total of the invoices with invoice numbers 146437 or 287742 is not provided in the context.",
  "results": [
    {
      "source": "sql",
      "data": [
        {
          "total_invoices": "125"
        }
      ],
      "metadata": {
        "execution_time": 12892,
        "row_count": 1,
        "sql": "SELECT COUNT(*) AS total_invoices FROM invoice"
      },
      "summary": "Total number of invoices"
    }
  ],
  "additional_info": {
    "plan": {
      "chain_of_thought_reasoning": "This query requires counting the total number of invoices, which can be fulfilled using structured fields alone from the iceberg database.",
      "subquestions": [
        {
          "question": "What is the total count of invoices?",
          "tool": "iceberg",
          "label": "$var_1",
          "should_expose_answer": true,
          "answer_description": "Total number of invoices",
          "query_type": "structured"
        }
      ]
    },
    "fallback": {
      "was_fallback_applied": false,
      "reason": ""
    }
  },
  "status": "success",
  "execution_time": 72530
}
  • {
  "request_id": "2a9ae7f2-0dce-467b-955f-51c1adc9f6a0",
  "status": "error",
  "trace": "unknown",
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid authorization token",
      "severity": "medium"
    }
  ]
}
id=curlclassName=tab-item-selected
Privacy statement