Manage a knowledge base

This guide walks through adding documents to your knowledge base, referencing them from an agent, and removing them when they are no longer needed.

You'll need an API key with convai:read and convai:write.

1. List existing documents

Before adding a document, check what is already there:

curl https://api.simwood.com/convai/v1/knowledge-base \
  -H "Authorization: Bearer sk_live_..."

The response is an array of document records, each with an id, name, type, and size_bytes.

2. Add a document

Choose the ingestion method that matches your content.

From a URL

The platform fetches and indexes the page at the URL. Pass a name to identify it in the list.

curl -X POST https://api.simwood.com/convai/v1/knowledge-base/url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support FAQ",
    "url": "https://example.com/support/faq"
  }'

From text

Pass the content directly as a string. Suitable for policies, scripts, or any content you maintain in-house.

curl -X POST https://api.simwood.com/convai/v1/knowledge-base/text \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cancellation policy",
    "text": "Customers may cancel any subscription within 30 days of purchase for a full refund..."
  }'

From a file

Upload a file. Supported formats: .txt, .pdf, .docx, .epub, .html.

curl -X POST https://api.simwood.com/convai/v1/knowledge-base/file \
  -H "Authorization: Bearer sk_live_..." \
  -F "name=Product catalogue" \
  -F "file=@catalogue.pdf"

All three endpoints return the same document schema. Note the id from the response — you need it to reference the document from an agent.

3. Reference the document from an agent

Add the document to the agent's configuration.agent.knowledge_base array. If the agent already exists, use PUT /agents/:id with the full updated configuration:

curl -X PUT https://api.simwood.com/convai/v1/agents/<agent-id> \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My agent",
    "configuration": {
      ...
      "agent": {
        ...
        "knowledge_base": [
          { "type": "url",  "id": "<doc-id-1>", "source": "https://example.com/support/faq" },
          { "type": "text", "id": "<doc-id-2>", "source": "Cancellation policy" }
        ]
      }
    }
  }'

The agent begins drawing on the new documents immediately for new conversations.

Calls already in progress are not affected by agent configuration changes — only new conversations pick up the updated knowledge base.

4. Remove a document

To stop using a document, first remove its entry from configuration.agent.knowledge_base on any agent that references it (using PUT /agents/:id), then delete the document itself:

curl -X DELETE https://api.simwood.com/convai/v1/knowledge-base/<document-id> \
  -H "Authorization: Bearer sk_live_..."

Deleting a document does not automatically update agents. If you delete without removing the reference first, the agent will have a stale reference — update the agent configuration to remove it after deletion.