REST API · v1.0.0

API cho nhà phát triển

API của KnowLedge cho phép ứng dụng của bạn tìm kiếm và đọc metadata của các tài liệu, tác giả đã xuất bản công khai trên nền tảng: tiêu đề, mô tả, chủ đề, tác giả, giá, số liệu thống kê. API chỉ đọc, trả về JSON qua HTTPS và xác thực bằng khoá API.

Địa chỉ gốc
base url
https://knowledge.asyncs.tech/api/v1

Bắt đầu nhanh

  1. 1

    Lấy khoá API

    Đăng nhập, mở trang API & khoá truy cập và gửi yêu cầu cấp khoá (tên ứng dụng, mục đích sử dụng, website nếu có). Sau khi quản trị viên duyệt, bạn tạo khoá bí mật ngay trên trang đó. Khoá chỉ hiển thị một lần, hãy lưu lại ngay.

  2. 2

    Gọi lần đầu

    Đặt khoá vào biến môi trường KNOWLEDGE_API_KEY rồi tìm 5 tài liệu đầu tiên khớp từ khoá “marketing”:

    bash
    export KNOWLEDGE_API_KEY="kl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    
    curl "https://knowledge.asyncs.tech/api/v1/documents?q=marketing&perPage=5" \
      -H "Authorization: Bearer $KNOWLEDGE_API_KEY"
  3. 3

    Đọc kết quả

    Kết quả là JSON. Mảng data chứa các đối tượng Document, còn pagination cho biết tổng số kết quả và số trang. Xem ví dụ đầy đủ ở phần Tìm kiếm tài liệu. Nếu mã HTTP không phải 2xx, thân trả về có trường error như mô tả ở phần Lỗi.

Xác thực

Mọi endpoint dữ liệu đều cần khoá API, gửi trong header Authorization theo dạng Bearer. Khoá bắt đầu bằng kl_live_. Khoá đặt trong query string sẽ bị từ chối.

http
Authorization: Bearer kl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Khoá cho quyền đọc danh mục công khai (scope catalog:read): metadata của tài liệu và tác giả đã xuất bản. Khoá không cho phép lấy nội dung tài liệu, văn bản từng trang, tệp tải về hay tìm kiếm bằng AI.

  • Giữ khoá bí mật như mật khẩu. Chỉ gọi API từ máy chủ của bạn; không đặt khoá trong mã chạy trên trình duyệt hoặc ứng dụng di động, không đưa vào kho mã nguồn.
  • API bật CORS cho mọi nguồn (Access-Control-Allow-Origin: *), nhưng điều đó không có nghĩa là nên gọi trực tiếp từ trình duyệt: ai mở công cụ nhà phát triển cũng đọc được khoá.
  • Tại trang API & khoá truy cập bạn có thể tạo lại khoá (khoá cũ mất hiệu lực ngay lập tức) hoặc thu hồi khoá. Mỗi tài khoản có tối đa 3 khoá đang hoạt động.
  • Thiếu khoá, khoá sai, đã bị thu hồi hoặc hết hạn: API trả về HTTP 401 với mã lỗi unauthorized.
  • Hai địa chỉ không cần khoá: GET /api/v1 (thông tin phiên bản) và GET /api/v1/openapi.json (đặc tả OpenAPI).

Giới hạn tần suất

Mỗi khoá được gọi tối đa 60 lượt mỗi phút, tính theo từng khung một phút cố định. Quản trị viên có thể nâng hạn mức riêng cho từng khoá. Request thiếu khoá hoặc dùng khoá không hợp lệ bị giới hạn 30 lượt mỗi phút theo địa chỉ IP.

Mọi response đã xác thực đều kèm ba header:

  • X-RateLimit-Limit: hạn mức của khoá trong một phút.
  • X-RateLimit-Remaining: số lượt còn lại trong khung hiện tại.
  • X-RateLimit-Reset: thời điểm khung hiện tại kết thúc, tính bằng giây Unix.
http
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1791255660

Khi vượt hạn mức, API trả về HTTP 429 với mã lỗi rate_limited và header Retry-After ghi số giây cần chờ. Hãy chờ đúng số giây đó rồi mới gọi lại; nếu vẫn nhận 429, tăng dần thời gian chờ giữa các lần thử thay vì gọi lại liên tục. Response có Cache-Control: private, no-store; nếu cần giảm số lượt gọi, hãy tự lưu kết quả ở phía bạn.

Phân trang

Các endpoint trả về danh sách nhận hai tham số: page (bắt đầu từ 1) và perPage (mặc định 20, tối đa 50). Response gồm mảng data và đối tượng pagination:

TrườngKiểuMô tả
pagesố nguyênTrang hiện tại (từ 1).
perPagesố nguyênSố mục mỗi trang.
totalsố nguyênTổng số mục khớp.
pageCountsố nguyênTổng số trang.

Để lấy hết kết quả, tăng page cho đến khi bằng pageCount.

Tìm kiếm tài liệu chỉ xét tối đa 500 kết quả phù hợp nhất. Nếu cần đi hết một tập lớn hơn, hãy chia nhỏ bằng bộ lọc (chủ đề, năm xuất bản, định dạng…).

Lỗi

API dùng mã HTTP chuẩn. Mọi lỗi đều có thân JSON cùng một dạng: code là mã ổn định để xử lý trong mã nguồn, message là mô tả bằng tiếng Việt cho người đọc (có thể thay đổi, đừng so khớp chuỗi này), requestId là mã của lượt gọi.

401 · json
{
  "error": {
    "code": "unauthorized",
    "message": "Thiếu khoá API hoặc khoá không hợp lệ.",
    "requestId": "req_8f3a2c1d9b7e4a06"
  }
}
HTTPMã lỗiÝ nghĩa
400invalid_requestTham số không hợp lệ. message nêu tên tham số sai.
401unauthorizedThiếu khoá API, khoá sai, đã bị thu hồi hoặc đã hết hạn.
403forbiddenKhoá không có quyền (scope) cho endpoint này.
404not_foundKhông tìm thấy tài nguyên hoặc đường dẫn không tồn tại.
429rate_limitedVượt hạn mức lượt gọi. Chờ số giây ghi ở header Retry-After rồi thử lại.
500internalLỗi phía máy chủ. Thử lại sau; nếu còn lỗi hãy gửi requestId cho chúng tôi.

Endpoint

Tất cả đường dẫn dưới đây tính từ địa chỉ gốc https://knowledge.asyncs.tech/api/v1. Tham số không có trong bảng sẽ được bỏ qua.

GET/api/v1/documentscatalog:read

Tìm kiếm tài liệu

Tìm trong các tài liệu đã xuất bản theo từ khoá (tìm toàn văn tiếng Việt, không phân biệt dấu) và bộ lọc. Bỏ trống q để duyệt toàn bộ danh mục. Mỗi bộ lọc nhận nhiều giá trị ngăn bằng dấu phẩy (tối đa 20): tài liệu khớp MỘT trong các giá trị của bộ lọc và phải khớp MỌI bộ lọc được truyền. Tìm kiếm xét tối đa 500 kết quả phù hợp nhất.

Tham số

Tham sốVị tríKiểuMô tả
qtuỳ chọnquerychuỗitối đa 300 ký tựTừ khoá tìm kiếm.
sorttuỳ chọnquerymột trongrelevancenewestdownloadsThứ tự: relevance độ phù hợp (không có q thì theo lượt xem), newest mới nhất, downloads tải nhiều nhất.Mặc định: relevance
pagetuỳ chọnquerysố nguyêntừ 1 đến 100000Trang cần lấy, bắt đầu từ 1.Mặc định: 1
perPagetuỳ chọnquerysố nguyêntừ 1 đến 50Số mục mỗi trang (tối đa 50).Mặc định: 20
categorytuỳ chọnquerydanh sách ngăn bằng dấu phẩyGiáo trìnhĐề thiEbookNghiên cứuHSKIELTSWordPressAILập trìnhChủ đề / lĩnh vực.
workTypetuỳ chọnquerydanh sách ngăn bằng dấu phẩydocumentbookarticlecoursethesisLoại công trình.
fileTypetuỳ chọnquerydanh sách ngăn bằng dấu phẩyPDFDOCPPTXLSĐịnh dạng tệp.
languagetuỳ chọnquerydanh sách ngăn bằng dấu phẩyvienzhNgôn ngữ: vi tiếng Việt, en tiếng Anh, zh tiếng Trung.
audiencetuỳ chọnquerydanh sách ngăn bằng dấu phẩystudentgraduatephdlecturerresearcherbusinessgeneralĐối tượng sử dụng.
authortuỳ chọnquerydanh sách ngăn bằng dấu phẩyTên tác giả, khớp chính xác.
publishertuỳ chọnquerydanh sách ngăn bằng dấu phẩyĐơn vị xuất bản / cung cấp, khớp chính xác.
tagtuỳ chọnquerydanh sách ngăn bằng dấu phẩyTừ khoá gắn với tài liệu, khớp chính xác.
pricetuỳ chọnquerymột trongfreepaidChỉ tài liệu miễn phí hoặc chỉ tài liệu trả phí.
accesstuỳ chọnquerymột trongopenrestrictedMức truy cập của tài liệu.
yearFromtuỳ chọnquerysố nguyêntừ 1000 đến 3000Năm xuất bản từ (tính cả năm này).
yearTotuỳ chọnquerysố nguyêntừ 1000 đến 3000Năm xuất bản đến (tính cả năm này).

Ví dụ gọi

bash
curl "https://knowledge.asyncs.tech/api/v1/documents?q=marketing&perPage=5" \
  -H "Authorization: Bearer $KNOWLEDGE_API_KEY"

Ví dụ kết quả

200 · json
{
  "data": [
    {
      "id": "d-1",
      "slug": "marketing-can-ban",
      "url": "https://knowledge.asyncs.tech/documents/marketing-can-ban",
      "title": "Marketing căn bản",
      "description": "Giáo trình nhập môn marketing dành cho sinh viên khối ngành kinh tế.",
      "workType": "document",
      "fileType": "PDF",
      "category": "Giáo trình",
      "language": "Tiếng Việt",
      "pages": 248,
      "year": 2024,
      "tags": [
        "marketing",
        "kinh tế"
      ],
      "publisher": "NXB Đại học Kinh tế Quốc dân",
      "audience": [
        "student"
      ],
      "accessLevel": "open",
      "priceVnd": 0,
      "authors": [
        {
          "name": "Nguyễn Văn A",
          "slug": "nguyen-van-a"
        }
      ],
      "summary": "Trình bày các khái niệm nền tảng của marketing: thị trường, phân khúc, định vị và 4P.",
      "stats": {
        "views": 12840,
        "downloads": 3210,
        "rating": 4.6,
        "ratingCount": 87
      },
      "publishedAt": "2026-09-12T03:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 5,
    "total": 1,
    "pageCount": 1
  }
}

Lỗi có thể gặp

  • 400invalid_requestTham số không hợp lệ. message nêu tên tham số sai.
  • 401unauthorizedThiếu khoá API, khoá sai, đã bị thu hồi hoặc đã hết hạn.
  • 429rate_limitedVượt hạn mức lượt gọi. Chờ số giây ghi ở header Retry-After rồi thử lại.
GET/api/v1/documents/{slug}catalog:read

Chi tiết tài liệu

Metadata của một tài liệu đã xuất bản. Tài liệu chưa xuất bản hoặc đã gỡ trả về not_found.

Tham số

Tham sốVị tríKiểuMô tả
slugbắt buộcđường dẫnchuỗitối đa 200 ký tựĐịnh danh của tài liệu (trường slug).

Ví dụ gọi

bash
curl "https://knowledge.asyncs.tech/api/v1/documents/marketing-can-ban" \
  -H "Authorization: Bearer $KNOWLEDGE_API_KEY"

Ví dụ kết quả

200 · json
{
  "data": {
    "id": "d-1",
    "slug": "marketing-can-ban",
    "url": "https://knowledge.asyncs.tech/documents/marketing-can-ban",
    "title": "Marketing căn bản",
    "description": "Giáo trình nhập môn marketing dành cho sinh viên khối ngành kinh tế.",
    "workType": "document",
    "fileType": "PDF",
    "category": "Giáo trình",
    "language": "Tiếng Việt",
    "pages": 248,
    "year": 2024,
    "tags": [
      "marketing",
      "kinh tế"
    ],
    "publisher": "NXB Đại học Kinh tế Quốc dân",
    "audience": [
      "student"
    ],
    "accessLevel": "open",
    "priceVnd": 0,
    "authors": [
      {
        "name": "Nguyễn Văn A",
        "slug": "nguyen-van-a"
      }
    ],
    "summary": "Trình bày các khái niệm nền tảng của marketing: thị trường, phân khúc, định vị và 4P.",
    "stats": {
      "views": 12840,
      "downloads": 3210,
      "rating": 4.6,
      "ratingCount": 87
    },
    "publishedAt": "2026-09-12T03:15:00.000Z"
  }
}

Lỗi có thể gặp

  • 401unauthorizedThiếu khoá API, khoá sai, đã bị thu hồi hoặc đã hết hạn.
  • 404not_foundKhông tìm thấy tài nguyên hoặc đường dẫn không tồn tại.
  • 429rate_limitedVượt hạn mức lượt gọi. Chờ số giây ghi ở header Retry-After rồi thử lại.
GET/api/v1/authorscatalog:read

Danh sách tác giả

Các tác giả có ít nhất một tài liệu đã xuất bản, xếp theo tên.

Tham số

Tham sốVị tríKiểuMô tả
qtuỳ chọnquerychuỗitối đa 100 ký tựLọc theo tên tác giả (chứa chuỗi này, không phân biệt hoa thường, có phân biệt dấu).
pagetuỳ chọnquerysố nguyêntừ 1 đến 100000Trang cần lấy, bắt đầu từ 1.Mặc định: 1
perPagetuỳ chọnquerysố nguyêntừ 1 đến 50Số mục mỗi trang (tối đa 50).Mặc định: 20

Ví dụ gọi

bash
curl "https://knowledge.asyncs.tech/api/v1/authors?q=Nguy%E1%BB%85n&perPage=5" \
  -H "Authorization: Bearer $KNOWLEDGE_API_KEY"

Ví dụ kết quả

200 · json
{
  "data": [
    {
      "id": "a-1",
      "slug": "nguyen-van-a",
      "url": "https://knowledge.asyncs.tech/authors/nguyen-van-a",
      "name": "Nguyễn Văn A",
      "affiliation": "Đại học Kinh tế Quốc dân",
      "verified": true,
      "documentCount": 3
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 5,
    "total": 1,
    "pageCount": 1
  }
}

Lỗi có thể gặp

  • 400invalid_requestTham số không hợp lệ. message nêu tên tham số sai.
  • 401unauthorizedThiếu khoá API, khoá sai, đã bị thu hồi hoặc đã hết hạn.
  • 429rate_limitedVượt hạn mức lượt gọi. Chờ số giây ghi ở header Retry-After rồi thử lại.
GET/api/v1/authors/{slug}catalog:read

Hồ sơ tác giả

Hồ sơ tác giả kèm các tài liệu đã xuất bản của họ.

Tham số

Tham sốVị tríKiểuMô tả
slugbắt buộcđường dẫnchuỗitối đa 200 ký tựĐịnh danh của tác giả (trường slug).

Ví dụ gọi

bash
curl "https://knowledge.asyncs.tech/api/v1/authors/nguyen-van-a" \
  -H "Authorization: Bearer $KNOWLEDGE_API_KEY"

Ví dụ kết quả

200 · json
{
  "data": {
    "id": "a-1",
    "slug": "nguyen-van-a",
    "url": "https://knowledge.asyncs.tech/authors/nguyen-van-a",
    "name": "Nguyễn Văn A",
    "affiliation": "Đại học Kinh tế Quốc dân",
    "verified": true,
    "documentCount": 3,
    "bio": "Giảng viên marketing với 15 năm kinh nghiệm.",
    "orcid": null,
    "expertise": [
      "Marketing",
      "Hành vi người tiêu dùng"
    ],
    "documents": [
      {
        "id": "d-1",
        "slug": "marketing-can-ban",
        "url": "https://knowledge.asyncs.tech/documents/marketing-can-ban",
        "title": "Marketing căn bản",
        "description": "Giáo trình nhập môn marketing dành cho sinh viên khối ngành kinh tế.",
        "workType": "document",
        "fileType": "PDF",
        "category": "Giáo trình",
        "language": "Tiếng Việt",
        "pages": 248,
        "year": 2024,
        "tags": [
          "marketing",
          "kinh tế"
        ],
        "publisher": "NXB Đại học Kinh tế Quốc dân",
        "audience": [
          "student"
        ],
        "accessLevel": "open",
        "priceVnd": 0,
        "authors": [
          {
            "name": "Nguyễn Văn A",
            "slug": "nguyen-van-a"
          }
        ],
        "summary": "Trình bày các khái niệm nền tảng của marketing: thị trường, phân khúc, định vị và 4P.",
        "stats": {
          "views": 12840,
          "downloads": 3210,
          "rating": 4.6,
          "ratingCount": 87
        },
        "publishedAt": "2026-09-12T03:15:00.000Z"
      }
    ]
  }
}

Lỗi có thể gặp

  • 401unauthorizedThiếu khoá API, khoá sai, đã bị thu hồi hoặc đã hết hạn.
  • 404not_foundKhông tìm thấy tài nguyên hoặc đường dẫn không tồn tại.
  • 429rate_limitedVượt hạn mức lượt gọi. Chờ số giây ghi ở header Retry-After rồi thử lại.

Đối tượng dữ liệu

Trường ghi | null luôn có mặt trong response nhưng có thể mang giá trị null. Thời điểm ghi theo ISO 8601, múi giờ UTC.

Document

Metadata của một tài liệu đã xuất bản. Trả về bởi các endpoint tài liệu và nằm trong documents của hồ sơ tác giả.

TrườngKiểuMô tả
idchuỗiMã định danh nội bộ, không đổi.
slugchuỗiĐịnh danh trên URL, dùng cho /documents/{slug}.
urlchuỗiĐịa chỉ trang tài liệu trên KnowLedge.
titlechuỗiTiêu đề.
descriptionchuỗiMô tả do người đăng viết; có thể rỗng.
workTypechuỗiLoại công trình.Giá trị:documentbookarticlecoursethesis
fileTypechuỗi | nullĐịnh dạng tệp; null nếu công trình chỉ có metadata.Giá trị:PDFDOCPPTXLS
categorychuỗiChủ đề / lĩnh vực.
languagechuỗiNgôn ngữ của tài liệu, ví dụ "Tiếng Việt".
pagessố nguyên | nullSố trang; null nếu chưa xác định.
yearsố nguyênNăm xuất bản.
tagschuỗi[]Từ khoá gắn với tài liệu.
publisherchuỗi | nullĐơn vị xuất bản / cung cấp.
audiencechuỗi[]Đối tượng sử dụng.Giá trị:studentgraduatephdlecturerresearcherbusinessgeneral
accessLevelchuỗiopen = ai cũng xem được; restricted = chỉ thành viên tổ chức / người mua.Giá trị:openrestricted
priceVndsố nguyênGiá bán lẻ (VND); 0 = miễn phí.
authorsđối tượng[]Tác giả, theo thứ tự ghi trên tài liệu.
authors[].namechuỗiTên tác giả.
authors[].slugchuỗiĐịnh danh dùng cho /authors/{slug}.
summarychuỗi | nullTóm tắt ngắn; null nếu chưa có.
statsđối tượng—
stats.viewssố nguyênLượt xem.
stats.downloadssố nguyênLượt tải.
stats.ratingsốĐiểm đánh giá trung bình (0–5).
stats.ratingCountsố nguyênSố lượt đánh giá.
publishedAtchuỗi | nullThời điểm xuất bản trên KnowLedge (ISO 8601, UTC).

Author

Một tác giả trong danh mục. Trả về bởi danh sách tác giả.

TrườngKiểuMô tả
idchuỗiMã định danh nội bộ, không đổi.
slugchuỗiĐịnh danh trên URL, dùng cho /authors/{slug}.
urlchuỗiĐịa chỉ trang tác giả trên KnowLedge.
namechuỗiTên tác giả.
affiliationchuỗi | nullĐơn vị công tác.
verifiedbooleanHồ sơ đã được chính tác giả nhận.
documentCountsố nguyênSố tài liệu đã xuất bản.

AuthorDetail

Hồ sơ tác giả đầy đủ: mọi trường của Author cộng thêm các trường dưới đây.

TrườngKiểuMô tả
biochuỗi | nullTiểu sử ngắn.
orcidchuỗi | nullMã ORCID của tác giả, nếu có.
expertisechuỗi[]Lĩnh vực chuyên môn.
documentsDocument[]Tài liệu đã xuất bản của tác giả, mới nhất trước (tối đa 100).

Phiên bản & thay đổi

Phiên bản nằm trong đường dẫn: /api/v1. Phiên bản hiện tại là 1.0.0, cũng được trả về bởi GET /api/v1.

  • Trong v1 chỉ có thay đổi bổ sung: thêm trường vào response, thêm tham số tuỳ chọn, thêm endpoint. Trường và tham số hiện có không bị xoá hay đổi nghĩa.
  • Ứng dụng của bạn cần bỏ qua các trường chưa biết trong response, không coi đó là lỗi.
  • Thay đổi không tương thích ngược sẽ ra ở đường dẫn mới /api/v2; v1 không bị thay đổi theo.

Hỗ trợ

Câu hỏi, báo lỗi hoặc đề xuất thêm dữ liệu cho API: gửi tại bảng góp ý. Khi báo lỗi, hãy kèm requestId trong thân lỗi, endpoint đã gọi và thời điểm gọi để chúng tôi tra cứu nhanh. Đừng gửi khoá API trong nội dung góp ý.