query_knowledge_base¶

ArtificialIntelligenceApi.query_knowledge_base(id, role_id, query_body, content_type=None, source_id=None, file_name=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Query an unstructured knowledge base

Vector-retrieves relevant chunks and generates an answer. Unstructured knowledge bases only. Structured knowledge bases are not queried on this path (they have no embedding model and this handler does not call the structured retrieve-and-generate flow). Requires at least read-only access. modelId must be a TEXT model assigned to knowledge bases. Optional SourceId (Bedrock data source ID) and FileName (source URI) scope retrieval. Citations are not returned on this REST path. Fails if no sources are attached or the embedding model is not assigned.

Parameters:

id (str) – Unique identifier of the knowledge base. (required)
role_id (str) – Amorphic role ID of the requesting user. Must be a role the authenticated user belongs to. (required)
query_body (QueryBody) – modelId is required and must be assigned for knowledge bases. prompt is optional (defaults to empty string). Extra fields are ignored. (required)
content_type (str) – Request body media type.
source_id (str) – Optional Bedrock data source ID. When set, retrieval is limited to that source (x-amz-bedrock-kb-data-source-id).
file_name (str) – Optional source URI to limit retrieval to one file (x-amz-bedrock-kb-source-uri). Empty values are ignored.
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

KnowledgeBaseQueryResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /ai/knowledgebases/{id}/query

Parameter examples¶

Name	In	Example
`Content-Type`	header	`"application/json"`
`id`	path	`"ABCDEFGHIJ"`
`SourceId`	query	`"ABCDEFGHIJDS"`
`FileName`	query	`"s3://example-dlz/sales_domain/sales_docs/upload_date=2026-08-01/quarterly_report.pdf"`
`role_id`	header	`"custom-role-123e4567-e89b-12d3-a456-426614174000"`

Request¶

modelId is required and must be assigned for knowledge bases. prompt is optional (defaults to empty string). Extra fields are ignored.

Standard RAG query

{
  "prompt": "What were Q2 sales highlights?",
  "modelId": "anthropic.claude-sonnet-4-6"
}

Model only (prompt defaults to empty string)

{
  "modelId": "anthropic.claude-sonnet-4-6"
}

Detailed question with context

{
  "prompt": "Summarize the key risks and mitigation steps mentioned in the quarterly report, focusing on supply chain.",
  "modelId": "anthropic.claude-sonnet-4-6"
}

Success (HTTP 200)¶

Answer plus ChunksRetrieved. GuardRailIntervention fields are included when the model returns. Metrics is included when present on the model response. ChunksRetrieved is empty when no accessible content is found or a guard rail blocks the answer.

Answer with retrieved chunks

{
  "Answer": "1. Q2 revenue increased 12% year over year.",
  "ChunksRetrieved": [
    {
      "FileName": "sales_domain/sales_docs/upload_date=2026-08-01/quarterly_report.pdf",
      "DatasetName": "sales_docs",
      "DomainName": "sales_domain",
      "Text": [
        "Q2 revenue increased 12% year over year..."
      ]
    }
  ],
  "GuardRailIntervention": false,
  "GuardRailInterventionReason": ""
}

No accessible chunks

{
  "Answer": "I could not find any relevant information in the files you have access to. Please try rephrasing your question or contact your administrator if you believe you should have access to additional content.",
  "ChunksRetrieved": []
}

Errors¶

Documented error codes: IPV-1002, AI-1009, IPV-1008, AUTH-1012, AUTH-1001, AUTH-1011, GE-1085, DB-1002.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1002 (KB not found or no sources attached), AI-1009 (embedding model not assigned), IPV-1008 (invalid modelId), AUTH-1012 (insufficient access), AUTH-1001 (missing role_id), AUTH-1011 (caller not authorized).

Missing role_id header

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

Caller not authorized

{
  "Message": "AUTH-1011 - User does not have sufficient permission to perform this action"
}

No sources attached

{
  "Message": "IPV-1002 - There are no sources attached to this knowledge base for testing. Please attach a source and try again."
}

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. Codes: GE-1085 (unexpected backend failure), DB-1002 (persistence failure).

Unexpected backend failure

{
  "Message": "GE-1085 - An unexpected error occurred"
}