The API supports workflows for managing collections and documents, processing content, and applying AI capabilities such as question answering, summarization, search, and structured extraction. Use this page to understand how those pieces work together, then use the API reference for endpoint-level implementation details.
Make sure you have:
If you haven't configured API access, see Set up Knowledge Base API access.
A typical Knowledge Base API workflow follows this sequence:
Authenticate → Collection → Document → Index → Inference → Response
A collection defines the knowledge domain your application works with. When you create a collection, the response includes its unique namespace, which you use in subsequent operations.
For example:
{
"namespace": "<collection-namespace>",
"name": "example-collection"
}
Retain the collection namespace for document and inference requests.
Documents are uploaded to collections and assigned unique document identifiers.
An upload response identifies the document so your application can track processing and reference it in later requests.
{
"document_id": "<document-id>",
"document_name": "example.pdf"
}
Uploading a document and indexing it are separate stages.
Uploading transfers the file to Knowledge Base. Indexing extracts its content and processes that content for use by AI operations.
Your application should confirm that processing has completed before submitting inference requests against the document.
Inference operations apply Knowledge Base AI capabilities to processed content.
Available operations include:
Use the API reference to determine the endpoint and request schema for the operation you want to perform.
Inference responses return the generated result and can include supporting attribution information.
Depending on the operation, attribution data can identify the source content, page, and coordinates associated with the result. Your application determines how that information is presented to the user.
The simplest application workflow is to create a collection, add a document, wait for processing, and then run an inference operation.
Create the collection that will contain the source documents for your application.
Retain the namespace returned in the response:
collection_namespace = <returned-namespace>
You'll use this value when adding documents and invoking operations against the collection.
Upload a document to the collection and retain the returned document ID:
document_id = <returned-document-id>
The document ID identifies the uploaded document independently of its file name.
Start the required indexing operation, then check the document status until processing completes.
Do not assume that a successful upload means the document is ready for AI operations.
A typical application flow is:
Upload document
↓
Start indexing
↓
Check processing status
↓
Complete
If processing fails, resolve the document-processing issue before submitting an inference request.
After processing completes, submit the collection namespace, document ID, and any operation-specific input required by the endpoint.
For example, a question-answering request conceptually supplies:
Collection: <collection-namespace>
Document: <document-id>
Question: What are the key findings?
Use the API reference for the actual request schema.
Use the returned answer or extracted data in your application.
If the response includes attribution information, you can use it to connect generated information back to its supporting document content.
The document lifecycle affects when your application can use uploaded content.
| Stage | What happens | Application action |
|---|---|---|
| Upload | The file is added to Knowledge Base and receives a document ID. | Retain the document ID. |
| Indexing | Content is extracted and processed for AI use. | Monitor document status. |
| Complete | The processed content is available for inference. | Submit AI requests. |
| Failed | Processing did not complete successfully. | Resolve the failure before continuing. |
This distinction is particularly important for automated workflows. An application should check processing status rather than immediately sending an inference request after upload.
Choose an operation based on what your application needs to do with the source content.
Use Q&A to submit natural-language questions about collection or document content.
The API provides both streaming and non-streaming Q&A.
Streaming Q&A returns the response incrementally as it's generated. Use it when your interface should display generated content progressively.
Streaming Q&A also supports controlling whether Custom Instructions are applied to the request. You can also control whether reasoning is generated for a streaming Q&A response.
Non-streaming Q&A waits for the generation to complete and returns the finished response. Use it when your application does not need to display partial output.
Use summarization to generate a condensed representation of document content.
The API reference defines the current request requirements and supported inputs.
Use context search to retrieve content relevant to the specified search text.
This can help applications identify relevant source material without generating a conversational response.
Use extraction when your application needs structured values from document content.
An extraction definition can identify information such as:
Property name: contract_value
Type: integer
Description: Agreement contract value
Prompt: Extract the largest agreement value in dollars.
The returned result can include the extracted value, confidence information, and source attribution.
The API provides several ways to determine which content participates in a request.
Use collection and document identifiers to define the primary content available to an operation.
Tags are associated with documents rather than collections.
Document tags are available only through the Knowledge Base API and are not exposed in the standard user interface.
You can use tags with supported operations to filter the documents considered for a request. For example, an application could tag a group of documents as financial documents and restrict a question to documents carrying that tag.
Attachments are separate from collection documents.
Adding an attachment to a conversation does not add that file to the collection. The attachment can still contribute context to a generated response, along with collection content and chat history.
Use attachment endpoints when your application needs temporary or conversation-specific content without permanently adding it to a collection.
Inference responses can include attribution information that connects generated output to supporting source content.
Attribution data can include information such as:
The API provides this information as data. Your application is responsible for deciding how to present it.
For example, an application can use returned coordinates to build a source-highlighting experience that identifies the location supporting a generated answer.
API operations use the permissions available to the authenticated identity.
A request can fail if the authenticated identity lacks access to the collection, document, or operation being requested.
When troubleshooting:
The X-Request-ID identifies the request across Knowledge Base services and can help Support investigate a failed request.
Use the Python Demo when you want working examples that demonstrate these concepts in an application.
Get started with the Knowledge Base Python Demo
Use the API reference when you're ready to implement a specific operation.
