> ## Documentation Index > Fetch the complete documentation index at: https://docs.featherhq.com/llms.txt > Use this file to discover all available pages before exploring further. # Updating a Knowledge File > Use this workflow to replace stale knowledge content, validate the new file, and roll it into the right collection safely. When knowledge content changes, treat the update as a controlled replacement. Upload the new file, add it to the target collection, confirm it is ready, then remove the stale file. This avoids breaking live agents while the new content is still being processed. Feather accepts knowledge files in `.pdf` and `.md` format. For safe replacements, use a distinct versioned filename such as `refund-policy-2026-03.pdf` instead of reusing the old filename. ## What You Are Updating There are two common cases: * **File refresh**: a policy, FAQ, script, or reference doc changed, but the collection should stay the same. * **Collection change**: the grouping itself needs to change, such as splitting one collection into multiple domains. For a file refresh, keep the same collection and replace the file membership. For a larger reorganization, create a new collection and switch agents over after validation. ## Step 1: Inspect the Current State Start by identifying: * the collection you want to update * the current file or files that should be replaced * any agent versions that rely on that collection ```bash theme={"system"} curl -X GET "https://prod.featherhq.com/api/v1/knowledge-base/collections" \ -H "X-API-Key: $FEATHER_API_KEY" ``` If you need a flat inventory of files and statuses, list files as well: ```bash theme={"system"} curl -X GET "https://prod.featherhq.com/api/v1/knowledge-base/files" \ -H "X-API-Key: $FEATHER_API_KEY" ``` ## Step 2: Request an Upload URL for the New File Generate an upload URL for the replacement document. This returns both a temporary upload URL and a `fileId` for that upload target. ```bash theme={"system"} curl -X POST "https://prod.featherhq.com/generate-presigned-url" \ -H "X-API-Key: $FEATHER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "fileName": "{updated-file-name}.pdf" }' ``` Then upload the file contents to the returned URL before you create the knowledge file record. ```bash theme={"system"} curl -X PUT "{uploadUrl}" \ -H "Content-Type: application/pdf" \ --upload-file "./{updated-file-name}.pdf" ``` If you are uploading markdown, change the content type to `text/markdown`. ## Step 3: Create the New Knowledge File Record Use the `fileId` from the previous step to create the knowledge file entry after the upload has completed. Add `prompt` only when you want retrieval instructions scoped to that file. ```bash theme={"system"} curl -X POST "https://prod.featherhq.com/api/v1/knowledge-base/file" \ -H "X-API-Key: $FEATHER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "fileId": "{newFileId}", "prompt": "Use this file for refund policy questions and customer eligibility details." }' ``` ## Step 4: Wait for the New File to Be Ready Do not remove the old file yet. First confirm the replacement file appears in the file list and reaches `INGESTED`. ```bash theme={"system"} curl -X GET "https://prod.featherhq.com/api/v1/knowledge-base/files" \ -H "X-API-Key: $FEATHER_API_KEY" ``` Look for the new file and confirm its status is `INGESTED`. If you want to verify the stored file directly, request a view URL: ```bash theme={"system"} curl -X POST "https://prod.featherhq.com/api/v1/knowledge-base/file/{newFileId}/view" \ -H "X-API-Key: $FEATHER_API_KEY" ``` ## Step 5: Add the New File to the Existing Collection Once the file is ready, attach it to the collection that your agents already use. ```bash theme={"system"} curl -X POST "https://prod.featherhq.com/api/v1/knowledge-base/collection/{collectionId}/file/{newFileId}" \ -H "X-API-Key: $FEATHER_API_KEY" ``` At this point, the collection contains both the old and new file. That overlap is useful while you validate the update. ## Step 6: Validate Before Cleanup Before removing the old file: 1. confirm the collection now includes the new file 2. test the affected agent version with representative questions 3. verify the agent answers from the updated content If the collection is attached to a production agent, validate on a draft or candidate version first when possible. ## Step 7: Remove the Stale File From the Collection After validation, remove the outdated file from the collection. ```bash theme={"system"} curl -X DELETE "https://prod.featherhq.com/api/v1/knowledge-base/collection/{collectionId}/file/{oldFileId}/remove" \ -H "X-API-Key: $FEATHER_API_KEY" ``` This is the step that actually updates the collection membership. ## Step 8: Delete the Old File Record If the old file is no longer needed anywhere else, delete it to keep the workspace clean. ```bash theme={"system"} curl -X DELETE "https://prod.featherhq.com/api/v1/knowledge-base/file/{oldFileId}" \ -H "X-API-Key: $FEATHER_API_KEY" ``` Only do this after confirming the file is not still referenced by another collection. ## Updating the Collection Structure If the collection itself needs to change, use this sequence: 1. create a new collection 2. upload and attach the correct file set 3. move the relevant agent version to the new collection 4. test the new setup 5. retire the old collection There is no separate "edit collection contents" endpoint beyond adding and removing files, so larger reorganizations are cleaner when treated as a new collection rollout. ## Recommended Operating Pattern * Use clear file names with dates or version markers. * Do not reuse the exact same filename when you want a staged replacement. * Replace content by adding the new file before removing the old one. * Keep collections organized by domain, not by one-off uploads. * Test agent answers after every material content change. * Delete stale files only after you have confirmed they are unused. ## Related Pages Learn how collections and files fit into agent grounding. Attach validated collections to the right agent version. Inspect collections and file membership. Track file status and cleanup stale entries.