Ingest files into a topic

Topics usually hold vectorized text chunks, but they can also contain registered files. Files can be read through search_mode="direct" or embedded into a vector collection.

Before you begin

A running Alquimia Platform runtime master.
An API token with write access.
A knowledge provider configured (qdrant, redis, or in_memory).

Create a topic

curl -X POST http://localhost:8080/knowledge/topics \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic_id": "product-docs",
    "description": "Product documentation and release notes",
    "connector": { "provider_id": "qdrant" }
  }'

Upload a file

curl -X POST http://localhost:8080/knowledge/files/upload \
  -H "Authorization: Bearer $API_TOKEN" \
  -F "file=@release-notes-v2.pdf"

The response contains a file_id.

Associate a file with a topic

curl -X PUT http://localhost:8080/knowledge/topics/product-docs/add/<file_id> \
  -H "Authorization: Bearer $API_TOKEN"

Embed file contents for vector search

For rag or on_demand modes, parse and index the file contents into the topic’s vector collection. The CLI can do this in one step:

alquimia registry topics add-file product-docs release-notes-v2.pdf \
  --namespace default \
  --provider qdrant

This uploads the file, registers it, and indexes chunks into the topic’s collection.

Direct file access

If the agent uses search_mode: "direct", it gets list_files and read_file tools over the topic instead of vector search.

{
  "knowledge_base": [
    {
      "topic_id": "product-docs",
      "search_mode": "direct",
      "tier_ceiling": ["reader", "editor"]
    }
  ]
}

connector must be omitted.
The topic’s access_policy is still enforced by the KnowledgeAuthzPolicy.

Manage files

Operation	Endpoint
List files	`GET /knowledge/files`
Download	`GET /knowledge/files/download/{file_id}`
Delete	`DELETE /knowledge/files/delete/{file_id}`
Remove from topic	`PUT /knowledge/topics/{topic_id}/remove/{file_id}`
Tag/untag file	`PUT /knowledge/files/{file_id}/tag` / `untag`

Storage backends

Files are stored outside the registry according to ALQUIMIA_FILE_STORAGE_PROVIDER:

Provider	Key variables
`local`	`ALQUIMIA_FILE_STORAGE_LOCAL_DIR`
`s3`	`ALQUIMIA_FILE_STORAGE_S3_ENDPOINT_URL`, `ACCESS_KEY`, `SECRET_KEY`, `BUCKET`

See Runtime configuration for details.