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 editor or platform-admin role (knowledge mutations require it as of runtime 0.5.4).
A knowledge provider configured via ALQUIMIA_KNOWLEDGE_PROVIDER (qdrant, redis, or in_memory).

Create a topic

As of runtime 0.5.4, topic_id and file_id are stable string UUIDs generated by the registry. The vector-store provider is deployment configuration, so do not pass a per-topic connector, distanceMetric, or vectorSize.

curl -X POST "http://localhost:8080/knowledge/topics?agentspace_id=default" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-docs",
    "description": "Product documentation and release notes",
    "is_active": true
  }'

As of alquimia-core 0.5.5, creating a topic creates its vector collection up front by default (ensure_collection=True). The response contains the generated topic_id.

Upload a file

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

The response contains the file’s generated id.

Associate a file with a topic

curl -X PUT "http://localhost:8080/knowledge/topics/<topic_id>/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 \
  --hydrate

This uploads the file, registers it, and indexes chunks into the topic’s collection. As of alquimia-core 0.5.5, ingest_file() returns an IngestResult containing the file registration, the number of hydrated chunks, and whether an existing blob was reused. The CLI prints the chunk count and indicates when a blob was deduplicated.

alquimia registry topics rebuild re-indexes every file in the topic and shows each file’s name next to its registered_file_id.

ALQUIMIA_KNOWLEDGE_PROVIDER selects the vector-store backend.

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.

Per-tag partitioning

As of alquimia-core 0.5.5, topics, collections, and files are partitioned per version tag. Each tag gets its own snapshot of file registrations and vector collection, so fetching or running a versioned agentspace does not affect the workspace copy. Lifecycle helpers such as snapshot_files_for_tag, rehydrate_tag, drop_tag_collections, and purge_tag_blobs manage these per-tag copies.

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.