Files, Documents, and Context Sources API

Files provide short-lived uploaded-object URLs. Documents are the indexed units inside a Context. Context Sources describe repeatable loaders and splitting configuration that can populate a Context asynchronously.

Create the parent Context first. See Context API for Context creation, search, prompt, and detailed document contracts. Every route here requires Authorization: Bearer YOUR_API_KEY and uses https://api.klu.ai/v1.

File upload

Send data as a base64 string or data URL. The route infers a MIME type when possible and otherwise treats the payload as PNG data.

curl --request POST 'https://api.klu.ai/v1/files/upload' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"data":"data:text/plain;base64,SGVsbG8sIEtsdSE="}'

{ "url": "https://SIGNED_OBJECT_URL" }

The returned URL expires after 10 minutes. Store the resulting content in a Context or fetch it before expiry; the URL is not a permanent public asset URL. Invalid base64 data, storage configuration, or upload failures return an error and do not produce a usable URL.

Document endpoints

Create a Document with either content or the compatible text field. filter and metadata are optional.

curl --request POST 'https://api.klu.ai/v1/contexts/CONTEXT_GUID/documents' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "content":"Refund requests are accepted within 30 days.",
    "filter":"policy",
    "metadata":{"source":"support-handbook","revision":4}
  }'

Creation returns the created Document GUIDs and processing state:

{
  "docs": ["DOCUMENT_GUID"],
  "status": "success"
}

Document detail fields are guid, content, nullable filter, metadata, embedding, and creation/update timestamps. List accepts contextGuid, optional query, skip, and limit; pagination defaults to 0/100 and returns { data, total_count, has_next_page }.

Creation may split the supplied content into more than one Document, which is why docs is an array. A successful create response confirms that the Documents were created. Source ingestion can continue separately, so check Context or Context Source status before depending on newly ingested source content in production. Update and delete operations require both a valid parent Context GUID and Document GUID. Bulk deletion accepts an optional filter and returns { "status": "success" }; omitting filter deletes all Documents in the Context.

Context Source endpoints

A public Context Source create request is currently file-source-only. It requires a signed or otherwise reachable url; the controller fixes the loader to the Files loader and initializes an empty loader configuration.

curl --request POST 'https://api.klu.ai/v1/contexts/CONTEXT_GUID/context_sources' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://SIGNED_OBJECT_URL"
  }'

A Context Source response includes guid, name, url, loader_id, loader_config, splitter_config, indexing_status, indexed_at, indexing_metadata, creator, and timestamps. Listing returns a bare array and has no public pagination or filtering parameters.

Updates require all of name, splitterConfig, and loaderConfig; this is replacement-style configuration, so include values you want to preserve. Each loader configuration item requires name and value and can include required. Splitter configuration must match the Context Source splitter schema used by the selected loader. The public create route does not let you choose another loader or submit arbitrary loader configuration; create non-file integrations in Klu.

Start one source with the source GUID in the URL and contextGuid in the JSON body:

curl --request POST 'https://api.klu.ai/v1/context_sources/CONTEXT_SOURCE_GUID/process' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"contextGuid":"CONTEXT_GUID"}'

Batch processing accepts { "sources": ["GUID_1", "GUID_2"] }. Both processing routes return { "msg": "success" } after dispatching work. Poll the Context Source and inspect indexing_status, indexed_at, and indexing_metadata for completion or failure. Batch processing resolves known GUIDs and silently has no work for unknown GUIDs; validate your source list when exact coverage matters.

SDK coverage

The TypeScript klu.contexts and Python klu.context clients provide high-level file and Document helpers, including upload, add/list/update Documents, embedding, search, and prompt. Neither SDK exposes a dedicated public Context Sources client. Use the REST routes above for loader/source CRUD and processing.

Errors and ownership

Malformed URLs, UUIDs, loader configuration, or splitter configuration return 400. Missing Contexts, Documents, or Sources return 404 (some source reads use a generic not-found response). Storage and loader failures may surface immediately or later in indexing metadata. A Context Source or Document GUID should be treated as belonging to its authenticated workspace and parent Context; do not reuse identifiers across workspaces.