> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# knowledge-base
> RAG search, document Q&A, and semantic search over uploaded documents
**Server path:** `/knowledge-base` | **Type:** Embedded | **PCID required:** No
## Tools
| Tool | Description |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`knowledge-base_list_collections`](#knowledge-base_list_collections) | List all available knowledge base collections |
| [`knowledge-base_create_collection`](#knowledge-base_create_collection) | Create a new knowledge base collection for storing and searching documents. Returns \{ id, name, type } - use the "id" field as collectionId for subsequent operations like uploading files. |
| [`knowledge-base_delete_collection`](#knowledge-base_delete_collection) | Delete a knowledge base collection and all its documents. Returns \{ message } on success. WARNING: This is a destructive operation that cannot be undone. |
| [`knowledge-base_ask`](#knowledge-base_ask) | Ask questions about document chunks from a knowledge base. Returns AI-generated answers based on semantic search of uploaded documents. Use collectionId from knowledge-base\_list\_collections to specify which collection to query. |
| [`knowledge-base_search`](#knowledge-base_search) | Search for semantically matching document chunks from a knowledge base. Returns relevant document snippets with similarity scores. Use collectionId from knowledge-base\_list\_collections to specify which collection to search. |
| [`knowledge-base_upload_file`](#knowledge-base_upload_file) | Upload a file to the knowledge base collection. Needs an EXISTING collection ID (not a name). You can get the existing collection IDs from the knowledge\_base\_list\_collections tool. Agents: to share the uploaded file, call knowledge-base\_create\_sharelink afterward — avoid requesting file\_url as it bloats context with storage credentials. Workflows: set returnFileUrl=true to include the file\_url in the response for convenient downstream use. |
| [`knowledge-base_delete_item`](#knowledge-base_delete_item) | Delete a file from the knowledge base collection. Needs an EXISTING collection ID (not a name). You can get the existing collection IDs from the knowledge\_base\_list\_collections tool. |
| [`knowledge-base_create_sharelink`](#knowledge-base_create_sharelink) | DEFAULT TOOL when a user asks to 'get', 'share', or 'send' a knowledge base file. Works for both public and private files. Creates a clean, shareable URL that serves the file directly in the browser. For private files, returns a short URL that does not expose storage signatures. For public files, returns the public URL directly. When the user says 'get me file X' or 'can I have file X', use this tool — do NOT retrieve file contents unless the user explicitly wants them for processing. Each call generates a unique short URL with its own independent expiration. Optionally store query parameters that will be appended to the URL when the link is accessed. |
***
## knowledge-base\_list\_collections
List all available knowledge base collections
**Parameters:** None
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
## knowledge-base\_create\_collection
Create a new knowledge base collection for storing and searching documents. Returns \{ id, name, type } - use the "id" field as collectionId for subsequent operations like uploading files.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------- |
| `name` | string | Yes | — | Display name for the knowledge base collection |
| `description` | string | No | — | Optional description of the collection purpose |
| `createdBy` | string | Yes | — | User ID creating the collection - use the current user ID or a service identifier |
| `createdByName` | string | Yes | — | Display name shown as creator - use the current user name or service name |
```json theme={null}
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name for the knowledge base collection"
},
"description": {
"type": "string",
"description": "Optional description of the collection purpose"
},
"createdBy": {
"type": "string",
"description": "User ID creating the collection - use the current user ID or a service identifier"
},
"createdByName": {
"type": "string",
"description": "Display name shown as creator - use the current user name or service name"
}
},
"required": [
"name",
"createdBy",
"createdByName"
]
}
```
***
## knowledge-base\_delete\_collection
Delete a knowledge base collection and all its documents. Returns \{ message } on success. WARNING: This is a destructive operation that cannot be undone.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID to delete - e.g. "KCny7nGXpBzWNYpJzC0b". Use knowledge-base\_list\_collections to get collection IDs. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID to delete - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use knowledge-base_list_collections to get collection IDs."
}
},
"required": [
"collectionId"
]
}
```
***
## knowledge-base\_ask
Ask questions about document chunks from a knowledge base. Returns AI-generated answers based on semantic search of uploaded documents. Use collectionId from knowledge-base\_list\_collections to specify which collection to query.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID (not name) to query - e.g. "KCny7nGXpBzWNYpJzC0b". Get from knowledge-base\_list\_collections. |
| `userPrompts` | string | Yes | — | Use the user's EXACT question or message as the query. Do NOT rephrase, summarize, or convert to keywords — semantic search works best with the user's original natural-language wording. Multiple questions are answered together in a comprehensive response. |
| `proxyId` | string | No | — | Optional proxy ID to access a shared knowledge base collection. Only needed for shared collections accessed via API key. For regular collections, omit this parameter. |
| `systemPrompts` | string | No | — | Instructions for response style. |
| `filterTags` | any | No | — | Filters are synonymous with tags. ALWAYS apply filterTags when provided in conversation memory (e.g. kbSearchHint). Otherwise, only use filters/tags if the user explicitly specifies them. Type is the operator, key is the attribute, and value is the value to filter on. Examples: Simple: \{"type": "eq", "key": "filename", "value": "TravelPolicy.pdf"} or Compound: \{"type": "and", "filters": \[\{"type": "eq", "key": "status", "value": "active"}, \{"type": "gt", "key": "priority", "value": 5}]}. Operators: eq, ne, gt, gte, lt, lte |
| `maxResults` | number | No | `10` | Documents to retrieve for context. More = better context but higher cost. Simple Q: 5-10, Complex: 15-25, Research: 30-50 |
| `provider` | string | No | `"groq"` | LLM provider. Prefer Groq. Only change to OpenAI if the user explicitly requests it. |
| `model` | string | No | — | AI model. Only set if the user explicitly requests a specific model. Omit to use provider default. |
| `stream` | boolean | No | — | Enable for real-time responses. Good for chat UIs and long answers. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID (not name) to query - e.g. \"KCny7nGXpBzWNYpJzC0b\". Get from knowledge-base_list_collections."
},
"userPrompts": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Use the user's EXACT question or message as the query. Do NOT rephrase, summarize, or convert to keywords — semantic search works best with the user's original natural-language wording. Multiple questions are answered together in a comprehensive response."
},
"proxyId": {
"type": "string",
"description": "Optional proxy ID to access a shared knowledge base collection. Only needed for shared collections accessed via API key. For regular collections, omit this parameter."
},
"systemPrompts": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Instructions for response style."
},
"filterTags": {
"type": "effects",
"description": "Filters are synonymous with tags. ALWAYS apply filterTags when provided in conversation memory (e.g. kbSearchHint). Otherwise, only use filters/tags if the user explicitly specifies them. Type is the operator, key is the attribute, and value is the value to filter on. Examples: Simple: {\"type\": \"eq\", \"key\": \"filename\", \"value\": \"TravelPolicy.pdf\"} or Compound: {\"type\": \"and\", \"filters\": [{\"type\": \"eq\", \"key\": \"status\", \"value\": \"active\"}, {\"type\": \"gt\", \"key\": \"priority\", \"value\": 5}]}. Operators: eq, ne, gt, gte, lt, lte"
},
"maxResults": {
"type": "number",
"default": 10,
"description": "Documents to retrieve for context. More = better context but higher cost. Simple Q: 5-10, Complex: 15-25, Research: 30-50"
},
"provider": {
"type": "string",
"enum": [
"groq",
"openai"
],
"default": "groq",
"description": "LLM provider. Prefer Groq. Only change to OpenAI if the user explicitly requests it."
},
"model": {
"type": "string",
"description": "AI model. Only set if the user explicitly requests a specific model. Omit to use provider default."
},
"stream": {
"type": "boolean",
"description": "Enable for real-time responses. Good for chat UIs and long answers."
}
},
"required": [
"collectionId",
"userPrompts"
]
}
```
***
## knowledge-base\_search
Search for semantically matching document chunks from a knowledge base. Returns relevant document snippets with similarity scores. Use collectionId from knowledge-base\_list\_collections to specify which collection to search.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID (not name) to search in - e.g. "KCny7nGXpBzWNYpJzC0b". Get from knowledge-base\_list\_collections. |
| `query` | string | Yes | — | Use the user's EXACT question or message as the search query. Do NOT rephrase, summarize, or convert to keywords — semantic search works best with the user's original natural-language wording. |
| `filterTags` | any | No | — | Filters are synonymous with tags. ALWAYS apply filterTags when provided in conversation memory (e.g. kbSearchHint). Otherwise, only use filters/tags if the user explicitly specifies them. Type is the operator, key is the attribute, and value is the value to filter on. Examples: Simple: \{"type": "eq", "key": "filename", "value": "TravelPolicy.pdf"} or Compound: \{"type": "and", "filters": \[\{"type": "eq", "key": "status", "value": "active"}, \{"type": "gt", "key": "priority", "value": 5}]}. Operators: eq, ne, gt, gte, lt, lte |
| `proxyId` | string | No | — | Optional proxy ID to access a shared knowledge base collection. Only needed for shared collections accessed via API key. For regular collections, omit this parameter. |
| `maxResults` | number | No | `10` | Maximum results to return. Higher = more comprehensive but slower. |
| `confidence` | number | No | `0.7` | Minimum confidence threshold. 0.3-0.5 = broad, 0.5-0.7 = balanced, 0.7-0.9 = precise |
| `rewriteQuery` | boolean | No | — | Auto-enhance query: fixes typos, expands abbreviations, adds synonyms. Good for user-typed searches. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID (not name) to search in - e.g. \"KCny7nGXpBzWNYpJzC0b\". Get from knowledge-base_list_collections."
},
"query": {
"type": "string",
"description": "Use the user's EXACT question or message as the search query. Do NOT rephrase, summarize, or convert to keywords — semantic search works best with the user's original natural-language wording."
},
"filterTags": {
"type": "effects",
"description": "Filters are synonymous with tags. ALWAYS apply filterTags when provided in conversation memory (e.g. kbSearchHint). Otherwise, only use filters/tags if the user explicitly specifies them. Type is the operator, key is the attribute, and value is the value to filter on. Examples: Simple: {\"type\": \"eq\", \"key\": \"filename\", \"value\": \"TravelPolicy.pdf\"} or Compound: {\"type\": \"and\", \"filters\": [{\"type\": \"eq\", \"key\": \"status\", \"value\": \"active\"}, {\"type\": \"gt\", \"key\": \"priority\", \"value\": 5}]}. Operators: eq, ne, gt, gte, lt, lte"
},
"proxyId": {
"type": "string",
"description": "Optional proxy ID to access a shared knowledge base collection. Only needed for shared collections accessed via API key. For regular collections, omit this parameter."
},
"maxResults": {
"type": "number",
"default": 10,
"description": "Maximum results to return. Higher = more comprehensive but slower."
},
"confidence": {
"type": "number",
"default": 0.7,
"description": "Minimum confidence threshold. 0.3-0.5 = broad, 0.5-0.7 = balanced, 0.7-0.9 = precise"
},
"rewriteQuery": {
"type": "boolean",
"description": "Auto-enhance query: fixes typos, expands abbreviations, adds synonyms. Good for user-typed searches."
}
},
"required": [
"collectionId",
"query"
]
}
```
***
## knowledge-base\_upload\_file
Upload a file to the knowledge base collection. Needs an EXISTING collection ID (not a name). You can get the existing collection IDs from the knowledge\_base\_list\_collections tool. Agents: to share the uploaded file, call knowledge-base\_create\_sharelink afterward — avoid requesting file\_url as it bloats context with storage credentials. Workflows: set returnFileUrl=true to include the file\_url in the response for convenient downstream use.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID to add the file to. |
| `filename` | string | Yes | — | Name of file to store |
| `fileUrl` | string | No | — | URL of file to upload. Preferred method - use this if you have a URL. Use either fileUrl OR fileContent, not both. |
| `fileContent` | string | No | — | File content to upload. Only use this if you do not have a fileUrl. Use either fileContent OR fileUrl, not both. |
| `fileLinksExpireInDays` | number | No | — | Number of days until file links expire |
| `fileLinksExpireInMinutes` | number | No | — | Number of minutes until file links expire |
| `returnFileUrl` | boolean | No | `false` | Whether to include the file\_url (signed storage URL) in the response. Agents should generally leave this false and use knowledge-base\_create\_sharelink instead. Workflows should set true when the URL is needed by downstream steps. |
| `proxyId` | string | No | — | Proxy ID to access a shared knowledge base collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID to add the file to."
},
"filename": {
"type": "string",
"description": "Name of file to store"
},
"fileUrl": {
"type": "string",
"description": "URL of file to upload. Preferred method - use this if you have a URL. Use either fileUrl OR fileContent, not both."
},
"fileContent": {
"type": "string",
"description": "File content to upload. Only use this if you do not have a fileUrl. Use either fileContent OR fileUrl, not both."
},
"fileLinksExpireInDays": {
"type": "number",
"description": "Number of days until file links expire"
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Number of minutes until file links expire"
},
"returnFileUrl": {
"type": "boolean",
"default": false,
"description": "Whether to include the file_url (signed storage URL) in the response. Agents should generally leave this false and use knowledge-base_create_sharelink instead. Workflows should set true when the URL is needed by downstream steps."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared knowledge base collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```
***
## knowledge-base\_delete\_item
Delete a file from the knowledge base collection. Needs an EXISTING collection ID (not a name). You can get the existing collection IDs from the knowledge\_base\_list\_collections tool.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID the file belongs to |
| `filename` | string | Yes | — | Name of file to delete |
| `proxyId` | string | No | — | Proxy ID to access a shared knowledge base collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID the file belongs to"
},
"filename": {
"type": "string",
"description": "Name of file to delete"
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared knowledge base collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```
***
## knowledge-base\_create\_sharelink
DEFAULT TOOL when a user asks to 'get', 'share', or 'send' a knowledge base file. Works for both public and private files. Creates a clean, shareable URL that serves the file directly in the browser. For private files, returns a short URL that does not expose storage signatures. For public files, returns the public URL directly. When the user says 'get me file X' or 'can I have file X', use this tool — do NOT retrieve file contents unless the user explicitly wants them for processing. Each call generates a unique short URL with its own independent expiration. Optionally store query parameters that will be appended to the URL when the link is accessed.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| -------------------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionId` | string | Yes | — | Collection ID the file belongs to |
| `filename` | string | Yes | — | Name of the file to create a share link for (required) - e.g. "example.json" |
| `fileLinksExpireInDays` | number | No | — | Share link expiration in days (1-7). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required. |
| `fileLinksExpireInMinutes` | number | No | — | Share link expiration in minutes. Can be combined with days (max 7 days total). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required. |
| `queryParams` | object | No | — | Optional key-value pairs to store with the link. When the short URL is accessed, these params are appended to the URL via redirect so client-side JavaScript can read them via URLSearchParams. |
| `proxyId` | string | No | — | Proxy ID to access a shared knowledge base collection. Requires X-API-Key header. |
```json theme={null}
{
"type": "object",
"properties": {
"collectionId": {
"type": "string",
"description": "Collection ID the file belongs to"
},
"filename": {
"type": "string",
"description": "Name of the file to create a share link for (required) - e.g. \"example.json\""
},
"fileLinksExpireInDays": {
"type": "number",
"description": "Share link expiration in days (1-7). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required."
},
"fileLinksExpireInMinutes": {
"type": "number",
"description": "Share link expiration in minutes. Can be combined with days (max 7 days total). At least one of fileLinksExpireInDays or fileLinksExpireInMinutes is required."
},
"queryParams": {
"type": "object",
"additionalProperties": true,
"description": "Optional key-value pairs to store with the link. When the short URL is accessed, these params are appended to the URL via redirect so client-side JavaScript can read them via URLSearchParams."
},
"proxyId": {
"type": "string",
"description": "Proxy ID to access a shared knowledge base collection. Requires X-API-Key header."
}
},
"required": [
"collectionId",
"filename"
]
}
```