Skip to main content
This guide shows how to sync documents from an external system such as Guru into a Profound knowledge base. All examples require authentication with an API key.
Knowledge bases must be created in the Profound app. The API cannot create a knowledge base. Replace your_api_key, your_knowledge_base_id, and your_organization_id with your actual values.

​
Syncing documents walkthrough

Use this flow to mirror documents and folders from an external system:
  1. Use List Knowledge Bases to find the knowledge base ID.
  2. Use Add Folder to mirror source folders when needed.
  3. Use Add Document to upload each source document.
  4. Use Update Document for idempotent re-syncs.
  5. Use Delete Document or Delete Folder when content is removed from the source system.

​
1. List Knowledge Bases

First, get the ID of the knowledge base you want to sync. The id returned here is required as the knowledge_base_id path parameter for every other Knowledge Base request.
If your API key can access multiple organizations, pass organization_id on the request:
Use the same query parameter on subsequent requests when the API key spans multiple organizations.

​
2. Add a Folder

Folders are empty when created. A document’s folder must already exist, so create the source hierarchy before uploading documents, and use folder paths such as Engineering/API to mirror the hierarchy in Guru. Create parent folders before their nested folders. Creating a folder that already exists returns 409 Conflict.

​
3. Add a Document

Add a document as JSON by sending its text in the text field. folder is optional; when provided, it is the folder path containing the document.
You can also upload a file as multipart form data. This is useful when your source system provides document files directly:
Both forms return the document name, path, and folder:
Adding a document does not overwrite an existing document: if the document path already exists, the request returns 409 Conflict. Use update instead when the path already exists.

​
4. Update a Document

Update overwrites an existing document at the target path. The JSON request has the same name, text, and optional folder fields as add:
Multipart uploads use the same name and optional folder fields, with file replacing text:
Update targets an existing document path in an existing folder; a missing folder returns 404 Not Found.

​
5. Delete a Document

Delete a document by sending its name in a JSON request body. Include folder in the name when deleting a nested document:

​
6. Delete a Folder

Delete an empty folder by setting recursive to false (the default):
If the folder is not empty, the request returns 409 Conflict and nothing is deleted. To delete the folder and all of its contents, set recursive to true:

​
7. Search a Knowledge Base

Search with a required query and top_k between 1 and 100. Set return_full_page to true to request full page content instead of snippets.
filters.tags matches documents with any of the supplied tags. filters.folders limits the search to folder paths and currently accepts exactly one folder. Each result includes an id, relevance score, metadata, and matched content:
For an external-system sync, loop over the source documents, use their folder paths to mirror the source hierarchy, use PUT for idempotent re-syncs, and use DELETE for documents removed from the source.