Skip to main content
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
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: 
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. 
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. 
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. 
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. 
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: 
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. 
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. 
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. 
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.
  • 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.

Knowledge Base

Learn how collections and files fit into agent grounding.

Agents

Attach validated collections to the right agent version.

Collections API

Inspect collections and file membership.

Files API

Track file status and cleanup stale entries.