Chuyển tới nội dung
Sursa Developers

POST/v1/cards/text

Tạo thẻ văn bản (Markdown)

create_text_card

Tạo thẻ văn bản từ Markdown (kind=text). Thẻ được lập chỉ mục giống như tệp đã tải lên. Với async=true, việc lập chỉ mục được đưa vào hàng đợi: phản hồi trả về ngay, và tiến độ có tại /v1/jobs.

Xác thực

Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.

Tham số header

  • Idempotency-Keystring

    Khóa để thử lại an toàn một thao tác ghi: 1 đến 255 ký tự ASCII in được; nên dùng một UUID v4 cho mỗi thao tác logic. Lần thử lại với cùng khóa trong vòng 24 giờ không chạy lại thao tác: dịch vụ trả về phản hồi đã lưu (trạng thái, header và phần thân) kèm header Idempotency-Replayed: true. Cùng khóa nhưng khác phương thức, đường dẫn, Content-Type hoặc phần thân trả về 409 api.idempotency_mismatch; khi yêu cầu đầu tiên vẫn đang chạy, trả về 409 api.idempotency_in_progress kèm Retry-After: 1. Sau phản hồi 5xx hoặc 429, khóa được giải phóng và lần thử lại sẽ chạy lại thao tác. Khóa có phạm vi theo tổ chức và bên gọi (khóa API, người dùng hoặc khóa nguồn tùy chỉnh).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Chỉ dành cho khóa API có vai trò admin. Thực hiện yêu cầu với tư cách hồ sơ dữ liệu <profile>[:viewer|verifier|editor], ví dụ employee:viewer. Khóa cài đặt không thể dùng header này (403).

Tham số cookie

  • kb_view_asstring

    Cookie của chế độ “View as” cho một phiên. POST /auth/view-as đặt cookie này, còn DELETE /auth/view-as xóa nó.

Phần thân yêu cầu

application/json

Đối tượng: TextCardRequest

  • titlestringbắt buộc

    length ≥ 1, length ≤ 200

  • collectionstring

    Mặc định: "default"

  • body_markdownstring

    Nội dung thẻ bằng Markdown; content_type không áp dụng cho trường này. Bạn có thể truyền body thay thế.

    length ≥ 1, length ≤ 500000

  • tagsarray of string | null

    items ≤ 30

  • categorystring | null

    length ≤ 60

  • sensitiveboolean | null
  • owner_idinteger | null
  • asyncboolean

    Mặc định: false

  • bodystring

    Nội dung thẻ theo định dạng content_type. Truyền body hoặc body_markdown; truyền cả hai sẽ trả về 422 validation.failed.

    length ≥ 1, length ≤ 500000

  • content_typeCardTextContentType
  • collection_idinteger | null

    Bộ sưu tập theo ID. Khi collection cũng được truyền, collection_id được ưu tiên. Bộ sưu tập không tồn tại trong tổ chức hoặc không hiển thị với bạn trả về 404 collections.not_found.

  • folder_idstring | null

    Thư mục của bộ sưu tập để đặt thẻ vào, với cùng các bước kiểm tra như folder_id khi tải tệp lên. Thư mục của bộ sưu tập khác trả về 400 folders.card_collection_mismatch, thư mục không tồn tại trả về 404 folders.not_found, còn khi không có quyền COLLECTION_EDIT_CARDS trên thư mục thì trả về 403 authz.forbidden.

    length ≤ 64

  • external_idstring | null

    external_id của thẻ mới. Nếu một thẻ khác của tổ chức đang dùng giá trị này, yêu cầu trả về 409 cards.external_id_taken. Để tạo hoặc thay thế thẻ theo external_id, hãy dùng PUT /v1/cards-by-external-id/{external_id}.

    length ≤ 512

  • metadataMetadataPatch

Phản hồi

200Phản hồi thành công

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

  • Idempotency-Replayed

    true nghĩa là phản hồi được phát lại từ phản hồi đã lưu cho Idempotency-Key này: thao tác không chạy lại.

application/json

Đối tượng: TextCardResult

  • statusstringbắt buộc

    Giá trị cho phép: readyerrorskippedqueued

  • cardCard | nullbắt buộc
  • tablesinteger
  • timingsobject
    Trường
    • total_snumber
  • errorstring
  • reasonstring
  • duplicatetrue
  • card_idstring | null
  • job_idinteger
  • jobJob
400Yêu cầu không hợp lệ: giá trị tham số hoặc trạng thái của đối tượng không cho phép thực hiện hành động (`detail` là thông báo).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

403Hành động không được phép: vai trò không đủ quyền, không có quyền truy cập vào bộ sưu tập hoặc thẻ, yêu cầu chạy ở chế độ “View as”, hoặc tổ chức bị tạm ngưng hay đã bị xóa (`detail` là đối tượng có `code: org_suspended | org_deleted`).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

404Đối tượng không tồn tại hoặc bạn không có quyền truy cập. API không xác nhận sự tồn tại của đối tượng bị hạn chế quyền truy cập.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

409Trạng thái của đối tượng không cho phép thực hiện hành động, ví dụ bản trùng lặp, đang lập chỉ mục, hoặc tác vụ đã được xử lý.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

422Lỗi dữ liệu không hợp lệ: phần thân hoặc tham số không khớp với lược đồ (`detail` là danh sách lỗi dữ liệu không hợp lệ), hoặc giá trị tham số nằm ngoài phạm vi cho phép (`detail` là thông báo).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.

Header phản hồi

  • Retry-After

    Số giây cần chờ trước khi thử lại yêu cầu.

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

Mã lỗi

Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lại yêu cầu.

Giới hạn tốc độ

Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.

← cards · Tài liệu tham chiếu API