API Cơ sở kiến thức

Cơ sở kiến thức là nơi AI đọc thông tin. Nó bao gồm hai phần và trang này sẽ đề cập đến cả hai:

Nguồn kiến thức (/kb-sources) — các trang web và tài liệu đã tải lên mà bạn cung cấp cho nền tảng. Mỗi nguồn sẽ được đọc, chia thành các phần và chuyển đổi thành các câu hỏi thường gặp (FAQ) để AI của bạn có thể trả lời.
Nhóm kiến thức (/kb-groups) — các gói FAQ được đặt tên mà bạn có thể áp dụng cho một Tác nhân (Agent) hoặc một chiến dịch trong một lệnh gọi duy nhất, nhờ đó khối kiến thức bạn đã biên soạn có thể được tái sử dụng cho Tác nhân tiếp theo mà bạn tạo.

Các FAQ được tạo ra từ một nguồn sẽ nằm trong cùng thư viện với các FAQ bạn tự viết, vì vậy sau khi quá trình nhập hoàn tất, bạn có thể đọc, chỉnh sửa và liên kết chúng bằng API FAQ.

Tất cả các endpoint bên dưới đều tương đối so với URL cơ sở https://api.youraiconnector.com/v1. Mọi yêu cầu đều phải được xác thực — xem Truy cập API và Xác thực. Truy cập API là một tính năng trả phí; nếu không có quyền truy cập, các yêu cầu sẽ bị từ chối với mã 403.

Việc nhập dữ liệu sẽ tiêu tốn tín dụng. Việc đọc một trang hoặc tài liệu và tạo FAQ từ đó sẽ tiêu tốn tín dụng, tỷ lệ thuận với lượng nội dung. Hãy sử dụng Ước tính chi phí nhập trước khi thực hiện một quá trình thu thập dữ liệu lớn.

Cách thức hoạt động của việc nhập dữ liệu

Nhập dữ liệu là một tác vụ chạy ngầm, không phải là tác vụ hoàn tất ngay lập tức. Mọi endpoint nhập dữ liệu sẽ phản hồi ngay lập tức với một source_id, và bạn cần thăm dò (poll) nguồn đó cho đến khi hoàn tất:

Bắt đầu nhập — POST /kb-sources/url (một trang), POST /kb-sources/file (một tài liệu đã tải lên), hoặc POST /kb-sources/bulk-import (tối đa 100 trang). Bạn sẽ nhận lại ID nguồn và status: "queued".
Thăm dò (Poll) — GET /kb-sources/{sourceId} cho đến khi status không còn là queued hoặc processing.
Đọc các FAQ — khi trạng thái là ready, các mục được tạo ra sẽ nằm trong thư viện FAQ của bạn: GET /faqs.

Mỗi nguồn sẽ báo cáo một trong các trạng thái sau:

Trạng thái	Ý nghĩa
`queued`	Đang chờ đọc. Chưa có phí nào được tính.
`processing`	Đang được đọc và chuyển đổi thành FAQ.
`ready`	Đã hoàn tất. Các FAQ của nó đã nằm trong thư viện của bạn.
`failed`	Không thể nhập. `error_message` cho biết lý do.
`cancelled`	Đã dừng trước khi được đọc (xem Dừng nhập).
`paused`	Đã dừng do khóa AI của bạn gặp lỗi trong quá trình nhập (xem Tiếp tục nhập bị tạm dừng).
`deleting`	Một quá trình xóa hàng loạt đang thực hiện trên đó.
`unknown`	Bản ghi không có trạng thái. Hãy coi như chưa sẵn sàng.

Đính kèm khi nhập. Truyền autoLinkToAgentId vào bất kỳ endpoint nhập nào và nguồn đó — cùng với mọi FAQ mà nó tạo ra — sẽ được thêm vào kiến thức của Tác nhân đó trong cùng một lệnh gọi, mà không cần bước liên kết bổ sung. autoLinkToCampaignId cũng thực hiện tương tự cho một chiến dịch cổ điển. Việc liên kết là nỗ lực tốt nhất: một ID không tồn tại hoặc thuộc về tài khoản khác sẽ bị bỏ qua một cách âm thầm và quá trình nhập vẫn tiếp tục, vì vậy hãy xác nhận liên kết bằng cách đọc lại Tác nhân.

Nhập một trang web

POST /kb-sources/url

Thêm một trang web vào cơ sở kiến thức của bạn.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`url`	Có	Địa chỉ `http` hoặc `https` đầy đủ của trang.
`autoLinkToAgentId`	Không	ID của AI Agent để đính kèm nguồn đã nhập.
`autoLinkToCampaignId`	Không	Kế thừa. ID của chiến dịch để đính kèm nguồn đã nhập.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

Phản hồi — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

Thăm dò source_id bằng Kiểm tra nguồn cho đến khi trạng thái là ready hoặc failed.

Nếu cùng một trang đã có trong cơ sở kiến thức của bạn, sẽ không có nội dung mới nào được xếp hàng và bạn sẽ nhận được 200 thay thế — và nếu bạn đã yêu cầu tự động liên kết, nguồn hiện có sẽ được liên kết cho bạn:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

Thiếu url, hoặc địa chỉ không phải là http/https hợp lệ, sẽ trả về 400.

Nhập tài liệu đã tải lên

POST /kb-sources/file

Thêm một tài liệu đã có trong bộ nhớ tệp của tài khoản làm nguồn kiến thức. Các định dạng được hỗ trợ: PDF, DOCX, TXT, MD, CSV và XLSX.

Endpoint này không chứa tệp. Không có tải lên multipart, không có body base64 và không có tải xuống từ URL: bạn gửi vị trí lưu trữ của một tệp đã tồn tại, và nó phải nằm trong thư mục tải lên của riêng bạn (storage_path phải bắt đầu bằng users/{your user id}/uploads/) nếu không yêu cầu sẽ bị từ chối với 403. Bảng điều khiển sẽ đặt các tệp ở đó khi bạn kéo chúng vào. Nếu bạn không có cách nào để đặt tệp ở đó, hãy nhập một trang web bằng Nhập trang web thay thế.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`storage_path`	Có	Nơi tệp đã tải lên nằm. Phải bắt đầu bằng `users/{your user id}/uploads/`.
`filename`	Có	Tên tệp gốc bao gồm phần mở rộng — đây là cách loại tệp được phát hiện.
`mime_type`	Có	Loại MIME của tệp, ví dụ `application/pdf`.
`autoLinkToAgentId`	Không	ID của AI Agent để đính kèm tài liệu vào.
`autoLinkToCampaignId`	Không	Kế thừa. ID của chiến dịch để đính kèm tài liệu vào.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

Phản hồi — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Trạng thái	Khi nào
`400`	Thiếu trường bắt buộc, hoặc tệp không thuộc loại chúng tôi có thể đọc.
`403`	`storage_path` nằm ngoài thư mục tải lên của riêng bạn.

Kiểm tra nguồn

GET /kb-sources/{sourceId}

Thăm dò theo sau mỗi lần nhập và làm mới. Lặp lại cho đến khi trạng thái là ready hoặc failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

Phản hồi

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}

Trường	Kiểu	Mô tả
`status`	string	Vị trí của nguồn trong quy trình (xem bảng trạng thái).
`faq_count`	integer	Số lượng FAQ đã được tạo từ nguồn này cho đến nay.
`section_count`	integer	Số lượng phần nội dung mà nguồn đã được chia thành.
`error_message`	string \| null	Lý do nhập thất bại, khi trạng thái là `failed`. `null` trong các trường hợp khác.

Xóa một nguồn

DELETE /kb-sources/{sourceId}

Xóa một nguồn kiến thức. Theo mặc định, các FAQ mà nguồn đó tạo ra sẽ được giữ lại — hãy thêm delete_faqs=true để xóa cả những FAQ đó.

Các tham số truy vấn

Tham số	Bắt buộc	Mô tả
`delete_faqs`	Không	Đặt thành `true` để xóa cả mọi FAQ mà nguồn này đã tạo ra. Mặc định là `false`.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted là 0 trừ khi bạn yêu cầu delete_faqs=true.

Nhập nhiều trang cùng lúc

POST /kb-sources/bulk-import

Thêm tối đa 100 trang web trong một lần gọi — đây là bước tiếp theo thông thường sau khi Khám phá các trang trên một trang web hoặc Tìm các trang mới trên một trang web. Các trang đã có trong cơ sở kiến thức của bạn sẽ được bỏ qua thay vì bị trùng lặp (và vẫn được liên kết với Tác nhân khi bạn yêu cầu điều đó).

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`urls`	Có	Các địa chỉ cần nhập. Tối thiểu 1, tối đa 100 cho mỗi lần gọi.
`autoLinkToAgentId`	Không	ID của một Tác nhân AI để đính kèm mọi trang đã nhập vào.
`autoLinkToCampaignId`	Không	Kế thừa. ID của một chiến dịch để đính kèm mọi trang đã nhập vào.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

Phản hồi — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

Truy vấn từng ID trong queued_source_ids bằng Kiểm tra nguồn. Việc gửi một mảng urls trống, một mục không phải là chuỗi hoặc hơn 100 mục sẽ trả về 400.

Xóa nhiều nguồn cùng lúc

POST /kb-sources/bulk-delete

Xóa tối đa 2.000 nguồn kiến thức trong một lần gọi. Việc xóa diễn ra trong nền và bạn sẽ nhận được email khi quá trình hoàn tất.

Xóa hàng loạt cũng sẽ xóa luôn các FAQ. Không giống như Xóa nguồn, vốn giữ lại các FAQ trừ khi bạn yêu cầu khác, điểm cuối này xóa từng nguồn cùng với các FAQ mà nó tạo ra. Không có tùy chọn nào để giữ lại chúng.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`sourceIds`	Có	ID của các nguồn cần xóa. Tối thiểu 1, tối đa 2.000 mỗi lệnh gọi.
`domainLabel`	Không	Tên thân thiện cho quá trình dọn dẹp này. Chỉ được sử dụng trong email thông báo hoàn tất.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

Phản hồi — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

Khám phá các trang trên một trang web

POST /kb-sources/discover-pages

Khám phá một trang web từ một địa chỉ bắt đầu và liệt kê các trang được tìm thấy trên cùng tên miền, mỗi trang đều kèm theo đánh giá về việc liệu nó có đáng để nhập hay không. Không có gì được nhập và không có gì được chọn cho bạn — đây là bước “có gì trên trang web này” mà bạn thực hiện trước khi quyết định những gì cần gửi đến Nhập nhiều trang cùng lúc.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`url`	Có	Địa chỉ bắt đầu khám phá, thường là trang chủ của trang web.
`maxPages`	Không	Giới hạn trên về số lượng trang cần trả về.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

Phản hồi

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}

Trường	Loại	Mô tả
`source_type`	string	Cách các trang được tìm thấy — `sitemap` (sơ đồ trang web của chính trang đó) hoặc `link_discovery` (bằng cách theo các liên kết).
`url`	string	Địa chỉ đầy đủ của trang.
`title`	string \| null	Tiêu đề trang, khi có thể đọc được.
`depth`	integer	Trang này được tìm thấy cách trang bắt đầu bao nhiêu liên kết.
`score`	integer	Trang trông hữu ích như thế nào dưới dạng kiến thức, từ `0` đến `100`.
`recommendation`	string	`add` (rõ ràng đáng để nhập, điểm 90 trở lên), `maybe` (ở mức trung bình), hoặc `skip` (nội dung hiếm khi giúp ích cho trợ lý — nhật ký thay đổi, trang pháp lý, bản dịch trùng lặp).
`reason_key`	string	Một lý do ổn định, máy có thể đọc được đằng sau đề xuất, ví dụ `core_page`, `changelog_history`, `legal_page` hoặc `locale_duplicate`.

Việc khám phá là nỗ lực tốt nhất. Nếu trang web không thể đọc được, phản hồi vẫn là 200, với success: false, danh sách pages trống và thông báo error. Kiểm tra success trước khi đọc pages.

Thiếu url sẽ trả về 400.

Ước tính chi phí nhập

POST /kb-sources/estimate-cost

Tính toán số lượng tín dụng mà một lần nhập đề xuất sẽ tiêu tốn trước khi bạn thực hiện. Các trang được tìm nạp và tài liệu được đọc để đo kích thước của chúng, nhưng không có gì được nhập và bản thân việc ước tính không tiêu tốn tín dụng.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`urls`	Không	Các địa chỉ trang bạn đang cân nhắc nhập.
`files`	Không	Các tệp đã tải lên mà bạn đang cân nhắc. Mỗi mục cần `storage_path`, `filename` và `mime_type`.
`tier`	Không	Cấp độ chất lượng AI mà quá trình nhập sẽ chạy, để ước tính khớp với những gì bạn thực sự bị tính phí. Để trống nếu sử dụng mức phí tiêu chuẩn.

Gửi urls, files, hoặc cả hai.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

Phản hồi

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7
}

Mỗi hàng phản hồi lại URL hoặc đường dẫn lưu trữ trong ref để bạn có thể khớp nó với dữ liệu đầu vào của mình. Một trang hoặc tệp không thể đọc được vẫn sẽ có một hàng, được tính là một đoạn, với một error trên đó.

Dừng nhập dữ liệu

POST /kb-sources/cancel-import

Dừng các trang vẫn đang chờ trong hàng đợi nhập dữ liệu — nút “dừng nhập” dành cho một quá trình thu thập dữ liệu (crawl) hóa ra lại lớn hơn bạn mong đợi. Việc hủy một trang đang chờ sẽ không tốn phí, vì nó chưa được đọc.

Các trang đã được xử lý sẽ không bị dừng: công việc của chúng đang được thực hiện và vẫn bị tính phí, vì vậy chúng sẽ hoàn tất. Phản hồi sẽ báo cáo số lượng các trang đó.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`host`	Không	Chỉ dừng các trang đang chờ trên trang web này (ví dụ: `docs.example.com`). Để trống để dừng mọi quá trình nhập đang chờ trên tài khoản.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

Phản hồi

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

Tiếp tục nhập dữ liệu đã tạm dừng

POST /kb-sources/resume-import

Khởi động lại quá trình nhập dữ liệu đã bị tạm dừng do khóa AI của riêng bạn ngừng hoạt động.

Việc gọi lệnh này đồng nghĩa với sự đồng ý của bạn để hoàn tất quá trình nhập dữ liệu trên bất kỳ khóa nào đang hoạt động — điều này có thể đồng nghĩa với việc tiêu tốn tín dụng nền tảng nếu khóa của riêng bạn vẫn chưa hoạt động trở lại.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`host`	Không	Chỉ tiếp tục các trang đã tạm dừng trên trang web này. Để trống để tiếp tục mọi thứ đã tạm dừng.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Phản hồi

{
  "success": true,
  "resumed": 58
}

Tìm các trang mới trên một trang web

POST /kb-sources/refresh-domain

Khám phá một trang web mà bạn đã nhập dữ liệu trước đó và chỉ báo cáo các trang chưa có trong cơ sở tri thức của bạn, mỗi trang đều có cùng đề xuất như khám phá trang. Không có gì được nhập và không có gì bị thay đổi.

Hai bước tiếp theo là các lệnh gọi riêng biệt, vì vậy việc rời khỏi bước này sẽ không tốn phí:

nhập các trang mới bạn muốn bằng Nhập nhiều trang cùng lúc;
đọc lại các trang bạn đã có bằng Làm mới mọi trang trên một trang web.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`baseUrl`	Có	Bất kỳ địa chỉ nào trên trang web, hoặc chỉ cần tên máy chủ.
`maxPages`	Không	Giới hạn trên về số lượng trang cần khám phá.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Phản hồi

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}

Trường	Kiểu	Mô tả
`discovered`	số nguyên	Tổng số trang được tìm thấy trên trang web.
`new_pages`	mảng	Các trang chưa có trong cơ sở kiến thức của bạn. Không có gì được xếp hàng cho bạn — hãy nhập những trang bạn muốn.
`new_urls_queued`	số nguyên	Luôn là `0`. Được giữ lại để tương thích ngược; điểm cuối này không bao giờ xếp hàng bất kỳ thứ gì.
`existing_refresh_queued`	số nguyên	Số lượng trang bạn đã nhập từ trang web này được tìm thấy và sẵn sàng để đọc lại. Không có gì được xếp hàng bởi lệnh gọi này.
`batch_id`	chuỗi	Chỉ xuất hiện khi một lô được tạo.

Giống như khám phá, lệnh này sẽ thất bại nhẹ nhàng: một trang web không thể đọc được vẫn trả về 200, với success: false, một new_pages trống và một error. Một baseUrl bị thiếu hoặc trống sẽ trả về 400.

Làm mới mọi trang trên một trang web

POST /kb-sources/trigger-domain-refresh

Đọc lại mọi trang bạn đã nhập từ một trang web, để các câu hỏi thường gặp (FAQ) của trang đó tuân theo nội dung hiện tại của trang web: các phần đã thay đổi sẽ được cập nhật, các phần mới được thêm vào và các phần đã xóa sẽ bị loại bỏ.

Lệnh này xếp hàng công việc và trả về ngay lập tức. Hãy theo dõi bằng Theo dõi quá trình làm mới trang web và dừng nó bằng Dừng quá trình làm mới trang web.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`baseUrl`	Có	Bất kỳ địa chỉ nào trên trang web, hoặc chỉ cần tên máy chủ.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Phản hồi

{
  "success": true,
  "queued": 249
}

Theo dõi quá trình làm mới trang web

GET /kb-sources/domain-refresh-status

Mức độ hoàn thành của quá trình làm mới trang web, để bạn có thể hiển thị tiến trình như “221 trên 249”.

Các tham số truy vấn

Tham số	Bắt buộc	Mô tả
`baseUrl`	Có	Bất kỳ địa chỉ nào trên trang web, hoặc chỉ cần tên máy chủ.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

job là null khi không có quá trình làm mới nào đang chạy cho trang web đó. Số trang đã hoàn thành cho đến nay là total trừ đi pending. Công việc status là một trong các trạng thái refreshing (vẫn đang xử lý các trang), deduplicating (bước dọn dẹp cuối cùng), hoặc trạng thái cuối cùng là completed, failed và cancelled. Hãy giữ lại domainBatchId — đó là thứ bạn truyền vào điểm cuối hủy bỏ.

Một baseUrl bị thiếu hoặc trống sẽ trả về 400.

Dừng làm mới trang web

POST /kb-sources/refresh-domain/cancel

Dừng việc làm mới trang web vẫn đang trong quá trình xử lý các trang. Các trang đã hoàn tất sẽ giữ lại nội dung đã cập nhật; các trang chưa bắt đầu sẽ bị loại bỏ, và các trang đang được đọc lại sẽ quay về trạng thái trước đó.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`jobId`	Có	`domainBatchId` được trả về bởi Theo dõi làm mới trang web.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

Phản hồi

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}

Trường	Loại	Mô tả
`status`	string	Trạng thái của việc làm mới sau lệnh gọi này: `cancelled`, `deduplicating`, `completed` hoặc `failed`.
`cancelled_units`	integer	Khối lượng công việc còn tồn đọng khi lệnh hủy được thực hiện. `0` nếu hủy lặp lại.
`sources_reset`	integer	Số trang được đưa ra khỏi quá trình xử lý và quay lại trạng thái `ready`.
`sources_cancelled`	integer	Các trang hoàn toàn mới của lần làm mới này vẫn đang trong hàng đợi và hiện đã bị hủy.

Việc hủy hai lần không gây hại gì — lệnh gọi thứ hai sẽ báo cáo cùng một trạng thái cuối cùng. Khi quá trình làm mới đã chuyển sang bước dọn dẹp, nó không thể bị dừng lại nữa và phản hồi sẽ trả về success: false và reason: "already_finalizing". Thiếu jobId sẽ trả về 400, và một công việc không có trong tài khoản của bạn sẽ trả về 404.

Làm mới một nguồn duy nhất

POST /kb-sources/{sourceId}/refresh

Đọc lại một trang web bạn đã nhập và đưa các câu hỏi thường gặp (FAQ) của trang đó về đúng với nội dung hiện tại: các phần thay đổi được cập nhật, phần mới được thêm vào, phần bị xóa sẽ bị loại bỏ.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

Phản hồi — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Thăm dò nguồn cho đến khi trạng thái của nó không còn là queued và processing. ID nguồn không có trong tài khoản của bạn sẽ trả về 404.

Chọn các trang phù hợp nhất

POST /kb-sources/select-relevant-pages

Yêu cầu AI chọn năm trang từ danh sách các ứng viên mô tả tốt nhất về một doanh nghiệp — được sử dụng khi tạo sổ tay chiến dịch từ một trang web. Việc này sẽ tiêu tốn tín dụng.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`urls`	Có	Các địa chỉ trang ứng viên để lựa chọn, thường là từ quá trình khám phá trang.
`homeUrl`	Có	Trang chủ của trang web, được sử dụng làm ngữ cảnh cho việc lựa chọn.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

Phản hồi

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

Đây là một trình trợ giúp, không phải là một tài nguyên: khi thất bại, nó vẫn phản hồi 200, với success: false, một danh sách pages trống và một thông báo error.

Các nhóm kiến thức

Một nhóm kiến thức là một tập hợp các câu hỏi thường gặp (FAQ) được đặt tên — ví dụ: “Vận chuyển và đổi trả”, “Giới thiệu” — mà bạn có thể áp dụng cho một Tác nhân hoặc một chiến dịch chỉ trong một lần gọi. Nhóm này chứa các tham chiếu chứ không phải bản sao: bản thân các FAQ vẫn nằm trong thư viện duy nhất của bạn, vì vậy việc chỉnh sửa một FAQ bằng FAQs API sẽ cập nhật nó ở mọi nơi mà nó được sử dụng.

Việc áp dụng một nhóm chỉ thêm những gì còn thiếu, vì vậy việc áp dụng cùng một nhóm hai lần là vô hại và added_count sẽ trả về là 0 trong lần thứ hai.

Tạo một nhóm kiến thức

POST /kb-groups

Tạo một nhóm. Nhóm này ban đầu sẽ trống — hãy thêm các FAQ vào nhóm bằng cách sử dụng Thêm FAQ vào nhóm.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`name`	Có	Tên của nhóm.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

Phản hồi — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

Đổi tên một nhóm kiến thức

PUT /kb-groups/{groupId}

Thay đổi tên của một nhóm. Các FAQ trong nhóm vẫn không bị ảnh hưởng.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`name`	Có	Tên mới của nhóm.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

Phản hồi

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

Xóa một nhóm kiến thức

DELETE /kb-groups/{groupId}

Xóa nhóm. Chỉ có tập hợp này bị xóa — các FAQ bên trong nó vẫn nằm trong thư viện của bạn, và bất kỳ đối tượng nào đã được áp dụng nhóm này trước đó vẫn giữ lại các FAQ đó.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true
}

Thêm FAQ vào một nhóm

POST /kb-groups/{groupId}/faqs

Đưa một FAQ hiện có vào một nhóm. Thao tác này chỉ thay đổi gói — nó không tự gắn FAQ vào bất kỳ Tác nhân (Agent) nào; hãy áp dụng nhóm cho việc đó.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`faq_id`	Có	ID của FAQ cần thêm.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

Phản hồi

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Xóa FAQ khỏi một nhóm

DELETE /kb-groups/{groupId}/faqs/{faqId}

Lấy một FAQ ra khỏi nhóm. Bản thân FAQ không bị xóa, và các Tác nhân đã được áp dụng nhóm này trước đó vẫn giữ lại FAQ đó.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Áp dụng một nhóm cho một Tác nhân

POST /kb-groups/{groupId}/apply-to-agent

Thêm mọi FAQ trong nhóm vào kiến thức của một Tác nhân AI trong một lần gọi — cách nhanh nhất để cung cấp cho một Tác nhân mới một kho kiến thức mà bạn đã biên soạn sẵn.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`agent_id`	Có	ID của Tác nhân AI cần áp dụng nhóm.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

Phản hồi

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count là số lượng FAQ thực sự đã được thêm — 0 khi nhóm trống hoặc đã được áp dụng.

Áp dụng một nhóm cho một chiến dịch

POST /kb-groups/{groupId}/apply-to-campaign

Phiên bản chiến dịch cổ điển của lệnh gọi trên. Trên tài khoản dựa trên Tác nhân, hãy sử dụng Áp dụng một nhóm cho một Tác nhân thay thế.

Các trường yêu cầu

Trường	Bắt buộc	Mô tả
`campaign_id`	Có	ID của chiến dịch để áp dụng nhóm vào.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

Phản hồi

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

Các lỗi API Cơ sở Kiến thức

Các endpoint này trả về cấu trúc lỗi tiêu chuẩn:

{
  "success": false,
  "error": "Knowledge base source not found."
}

Trạng thái	Khi nào nó xảy ra trên một endpoint cơ sở kiến thức
`400`	Một trường bắt buộc bị thiếu hoặc không hợp lệ — một `url` trống, thiếu `baseUrl` hoặc `jobId`, hơn 100 URL trong một lần nhập hàng loạt, hơn 2.000 ID trong một lần xóa hàng loạt, hoặc một loại tệp mà chúng tôi không thể đọc.
`402`	Không đủ tín dụng để thực hiện nhập. Hãy nạp thêm và thử lại.
`403`	Một `storage_path` nằm ngoài thư mục tải lên của riêng bạn — hoặc gói của bạn không bao gồm quyền truy cập API.
`404`	Nguồn, nhóm, FAQ, Tác nhân, chiến dịch hoặc tác vụ làm mới không được tìm thấy — hoặc là nó không tồn tại hoặc nó thuộc về một tài khoản khác.

Lỗi nhẹ không phải là lỗi hệ thống. Discovery (discover-pages, refresh-domain) và trình trợ giúp chọn trang trả về 200 với success: false và thông báo error khi không thể đọc trang web, thay vì làm thất bại yêu cầu. Luôn kiểm tra success trước khi đọc dữ liệu.

Các mã chung mà mọi điểm cuối có thể trả về — 401, 403 (gói của bạn không bao gồm quyền truy cập API), 429 (giới hạn tốc độ) và 500 — được liệt kê cùng với hướng dẫn thử lại trong Lỗi & Phân trang.

Liên quan

API FAQ — đọc, chỉnh sửa và liên kết các FAQ mà các nguồn của bạn tạo ra.
Quản lý FAQ — cùng một cơ sở kiến thức trong bảng điều khiển.
Tác nhân AI — các Tác nhân mà bạn đính kèm nguồn và nhóm vào.
Truy cập API — tạo khóa API của bạn.
Xác thực — tất cả các cách để truyền khóa của bạn.

API Cơ sở kiến thức #

Cách thức hoạt động của việc nhập dữ liệu #

Nhập một trang web #

Nhập tài liệu đã tải lên #

Kiểm tra nguồn #

Xóa một nguồn #

Nhập nhiều trang cùng lúc #

Xóa nhiều nguồn cùng lúc #

Khám phá các trang trên một trang web #

Ước tính chi phí nhập #

Dừng nhập dữ liệu #

Tiếp tục nhập dữ liệu đã tạm dừng #

Tìm các trang mới trên một trang web #

Làm mới mọi trang trên một trang web #

Theo dõi quá trình làm mới trang web #

Dừng làm mới trang web #

Làm mới một nguồn duy nhất #

Chọn các trang phù hợp nhất #

Các nhóm kiến thức #

Tạo một nhóm kiến thức #

Đổi tên một nhóm kiến thức #

Xóa một nhóm kiến thức #

Thêm FAQ vào một nhóm #

Xóa FAQ khỏi một nhóm #

Áp dụng một nhóm cho một Tác nhân #

Áp dụng một nhóm cho một chiến dịch #

Các lỗi API Cơ sở Kiến thức #

Liên quan #

API Cơ sở kiến thức

Cách thức hoạt động của việc nhập dữ liệu

Nhập một trang web

Nhập tài liệu đã tải lên

Kiểm tra nguồn

Xóa một nguồn

Nhập nhiều trang cùng lúc

Xóa nhiều nguồn cùng lúc

Khám phá các trang trên một trang web

Ước tính chi phí nhập

Dừng nhập dữ liệu

Tiếp tục nhập dữ liệu đã tạm dừng

Tìm các trang mới trên một trang web

Làm mới mọi trang trên một trang web

Theo dõi quá trình làm mới trang web

Dừng làm mới trang web

Làm mới một nguồn duy nhất

Chọn các trang phù hợp nhất

Các nhóm kiến thức

Tạo một nhóm kiến thức

Đổi tên một nhóm kiến thức

Xóa một nhóm kiến thức

Thêm FAQ vào một nhóm

Xóa FAQ khỏi một nhóm

Áp dụng một nhóm cho một Tác nhân

Áp dụng một nhóm cho một chiến dịch

Các lỗi API Cơ sở Kiến thức

Liên quan