Preferred API for website and file sources, discovered pages, and asynchronous source runs.
Use this source-based API for new integrations. Responses use camelCase fields and mutations return immediately while crawling and indexing continue in a run. Read a source, its items, or its runs to observe progress. Existing document endpoints remain available during the cutover.
Website creation accepts name, sourceUrl, settings, refreshIntervalHours, and optional folderId. settings controls scope, discovery, wildcard fetch rules, RE2 indexing rules, optional content selector, rendering, page limit, and depth. Upload one file with multipart file and optional name and folderId. To create a text source, upload the text as a Markdown or plain-text file.
Folders organize sources within an agent without changing retrieval or indexing. Create a folder with name and optional parentId; names may contain up to 120 characters. Omit the parent or set it to null for the library root. Update a source's folderId to move it, or set it to null to move it to the root. Update a folder's parentId to move the folder. Parents must belong to the same agent, and a folder cannot be moved into itself or a descendant. Only empty folders can be deleted.
api.heroui.pro/v1/agents/{agentId}/knowledge/foldersSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.heroui.pro/v1/agents/string/knowledge/folders"{
"folders": [
{
"createdAt": 0,
"id": "string",
"name": "string",
"parentId": "string",
"updatedAt": 0
}
]
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/foldersSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/folders" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{
"folder": {
"createdAt": 0,
"id": "string",
"name": "string",
"parentId": "string",
"updatedAt": 0
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/folders/{folderId}Send the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://api.heroui.pro/v1/agents/string/knowledge/folders/string" \ -H "Content-Type: application/json" \ -d '{}'{
"folder": {
"createdAt": 0,
"id": "string",
"name": "string",
"parentId": "string",
"updatedAt": 0
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/folders/{folderId}Send the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
curl -X DELETE "https://api.heroui.pro/v1/agents/string/knowledge/folders/string"{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sourcesSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.heroui.pro/v1/agents/string/knowledge/sources"{
"sources": [
{
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"createdAt": 0,
"errorMessage": "string",
"fileName": "string",
"fileSizeBytes": 0,
"folderId": "string",
"id": "string",
"isEnabled": true,
"lastCheckedAt": 0,
"lastSyncedAt": 0,
"name": "string",
"nextRefreshAt": 0,
"refreshIntervalHours": 0,
"settings": {
"contentSelector": "",
"depth": 5,
"discovery": "all",
"excludePatterns": [],
"excludeRegex": [],
"includePatterns": [],
"includeRegex": [],
"pageLimit": 1000,
"renderJavaScript": false,
"scope": "page"
},
"sourceUrl": "string",
"status": "queued",
"type": "website",
"updatedAt": 0,
"updatesPaused": true
}
]
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sourcesSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/sources" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "sourceUrl": "string" }'{
"source": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"createdAt": 0,
"errorMessage": "string",
"fileName": "string",
"fileSizeBytes": 0,
"folderId": "string",
"id": "string",
"isEnabled": true,
"lastCheckedAt": 0,
"lastSyncedAt": 0,
"name": "string",
"nextRefreshAt": 0,
"refreshIntervalHours": 0,
"settings": {
"contentSelector": "",
"depth": 5,
"discovery": "all",
"excludePatterns": [],
"excludeRegex": [],
"includePatterns": [],
"includeRegex": [],
"pageLimit": 1000,
"renderJavaScript": false,
"scope": "page"
},
"sourceUrl": "string",
"status": "queued",
"type": "website",
"updatedAt": 0,
"updatesPaused": true
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/filesSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/sources/files" \ -F file="string"{
"source": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"createdAt": 0,
"errorMessage": "string",
"fileName": "string",
"fileSizeBytes": 0,
"folderId": "string",
"id": "string",
"isEnabled": true,
"lastCheckedAt": 0,
"lastSyncedAt": 0,
"name": "string",
"nextRefreshAt": 0,
"refreshIntervalHours": 0,
"settings": {
"contentSelector": "",
"depth": 5,
"discovery": "all",
"excludePatterns": [],
"excludeRegex": [],
"includePatterns": [],
"includeRegex": [],
"pageLimit": 1000,
"renderJavaScript": false,
"scope": "page"
},
"sourceUrl": "string",
"status": "queued",
"type": "website",
"updatedAt": 0,
"updatesPaused": true
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}Send the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.heroui.pro/v1/agents/string/knowledge/sources/string"{
"source": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"createdAt": 0,
"errorMessage": "string",
"fileName": "string",
"fileSizeBytes": 0,
"folderId": "string",
"id": "string",
"isEnabled": true,
"lastCheckedAt": 0,
"lastSyncedAt": 0,
"name": "string",
"nextRefreshAt": 0,
"refreshIntervalHours": 0,
"settings": {
"contentSelector": "",
"depth": 5,
"discovery": "all",
"excludePatterns": [],
"excludeRegex": [],
"includePatterns": [],
"includeRegex": [],
"pageLimit": 1000,
"renderJavaScript": false,
"scope": "page"
},
"sourceUrl": "string",
"status": "queued",
"type": "website",
"updatedAt": 0,
"updatesPaused": true
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}Send the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://api.heroui.pro/v1/agents/string/knowledge/sources/string" \ -H "Content-Type: application/json" \ -d '{}'{
"source": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"createdAt": 0,
"errorMessage": "string",
"fileName": "string",
"fileSizeBytes": 0,
"folderId": "string",
"id": "string",
"isEnabled": true,
"lastCheckedAt": 0,
"lastSyncedAt": 0,
"name": "string",
"nextRefreshAt": 0,
"refreshIntervalHours": 0,
"settings": {
"contentSelector": "",
"depth": 5,
"discovery": "all",
"excludePatterns": [],
"excludeRegex": [],
"includePatterns": [],
"includeRegex": [],
"pageLimit": 1000,
"renderJavaScript": false,
"scope": "page"
},
"sourceUrl": "string",
"status": "queued",
"type": "website",
"updatedAt": 0,
"updatesPaused": true
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}Send the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
curl -X DELETE "https://api.heroui.pro/v1/agents/string/knowledge/sources/string"{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}/syncSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/sources/string/sync"{
"run": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"browserSecondsUsed": 0,
"createdAt": 0,
"errorMessage": "string",
"finishedAt": 0,
"id": "string",
"kind": "sync",
"sourceId": "string",
"startedAt": 0,
"status": "queued",
"updatedAt": 0
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}/previewSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/sources/string/preview" \ -H "Content-Type: application/json" \ -d '{}'{
"run": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"browserSecondsUsed": 0,
"createdAt": 0,
"errorMessage": "string",
"finishedAt": 0,
"id": "string",
"kind": "sync",
"sourceId": "string",
"startedAt": 0,
"status": "queued",
"updatedAt": 0
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}/itemsSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.heroui.pro/v1/agents/string/knowledge/sources/string/items"{
"items": [
{
"characterCount": 0,
"createdAt": 0,
"errorMessage": "string",
"id": "string",
"isEnabled": true,
"isExcluded": true,
"lastIndexedAt": 0,
"name": "string",
"skipReason": "string",
"sourceId": "string",
"status": "queued",
"updatedAt": 0,
"url": "string"
}
]
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}/runsSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.heroui.pro/v1/agents/string/knowledge/sources/string/runs"{
"runs": [
{
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"browserSecondsUsed": 0,
"createdAt": 0,
"errorMessage": "string",
"finishedAt": 0,
"id": "string",
"kind": "sync",
"sourceId": "string",
"startedAt": 0,
"status": "queued",
"updatedAt": 0
}
]
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/sources/{sourceId}/rules/testSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/sources/string/rules/test" \ -H "Content-Type: application/json" \ -d '{ "urls": [ "string" ] }'{
"results": [
{
"fetch": true,
"index": true,
"reason": "string",
"url": "string"
}
]
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/items/{itemId}Send the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://api.heroui.pro/v1/agents/string/knowledge/items/string" \ -H "Content-Type: application/json" \ -d '{}'{
"item": {
"characterCount": 0,
"createdAt": 0,
"errorMessage": "string",
"id": "string",
"isEnabled": true,
"isExcluded": true,
"lastIndexedAt": 0,
"name": "string",
"skipReason": "string",
"sourceId": "string",
"status": "queued",
"updatedAt": 0,
"url": "string"
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/items/{itemId}/retrySend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/items/string/retry"{
"run": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"browserSecondsUsed": 0,
"createdAt": 0,
"errorMessage": "string",
"finishedAt": 0,
"id": "string",
"kind": "sync",
"sourceId": "string",
"startedAt": 0,
"status": "queued",
"updatedAt": 0
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/items/{itemId}/contentSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.heroui.pro/v1/agents/string/knowledge/items/string/content"{
"content": "string"
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/runs/{runId}/cancelSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.heroui.pro/v1/agents/string/knowledge/runs/string/cancel"{
"run": {
"totalCount": 0,
"queuedCount": 0,
"processingCount": 0,
"indexedCount": 0,
"failedCount": 0,
"skippedCount": 0,
"browserSecondsUsed": 0,
"createdAt": 0,
"errorMessage": "string",
"finishedAt": 0,
"id": "string",
"kind": "sync",
"sourceId": "string",
"startedAt": 0,
"status": "queued",
"updatedAt": 0
}
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}api.heroui.pro/v1/agents/{agentId}/knowledge/runs/{runId}/previewSend the request to see the live response from the Agents API.
A workspace API key with the permission required by the operation. It may target any active Agent in its workspace.
In: header
The Agent targeted by this workspace API key request.
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://api.heroui.pro/v1/agents/string/knowledge/runs/string/preview"{
"content": "string",
"title": "string",
"url": "string"
}{
"message": "limit must be an integer between 1 and 100.",
"name": "bad_request"
}{
"message": "The supplied API key is invalid or revoked.",
"name": "unauthorized"
}{
"message": "Too many requests. Please try again later.",
"name": "rate_limited"
}{
"message": "The API is temporarily unavailable.",
"name": "service_unavailable"
}1 <= length <= 1201 <= length <= 1201 <= length <= 12024{"contentSelector":"","depth":5,"discovery":"all","excludePatterns":[],"excludeRegex":[],"includePatterns":[],"includeRegex":[],"pageLimit":1000,"renderJavaScript":false,"scope":"subtree"}1 <= length <= 2048binary1 <= length <= 1201 <= length <= 20481 <= items <= 100