GET/v1/cards

列出卡片

list_cards

返回卡片，支持筛选、排序和分页。使用 preview=1（用于平铺视图）时，每张卡片还会在数据权限档案允许的范围内包含 preview（正文的前 200 个字符）和 preview_tables（工作表及其行数）。

身份验证

在 Authorization 请求头中传入 API 密钥：Authorization: Bearer <密钥>。

查询参数

collectionstring | null
folderstring | null
<folder ID> 返回该文件夹及其所有子文件夹中的卡片。none 返回合集中不在任何文件夹里的卡片，此时必须传入 collection（否则返回 400 cards.invalid_folder_filter）。文件夹不存在或您不可见时，请求返回 404 folders.not_found。
length ≤ 64
statusstring | null
可选值: processingreadyerrorarchivedall
ownerstring | null
me、none 或用户 ID。
owner_idinteger | null
verificationstring | null
可选值: verifiedneeds_verificationstale
kindCardKind
typestring | null
table 返回包含事实表的卡片，text 返回不含事实表的卡片。
可选值: tabletext
tagsstring | null
以逗号分隔的标签（卡片必须具有全部标签）。
idsstring | null
以逗号分隔的卡片 ID。
searchstring | null
categorystring | null
sensitiveboolean | null
sortCardSort
默认值："created_at"
orderstring
可选值: ascdesc
默认值："desc"
limitinteger
默认值：200
offsetinteger
默认值：0
previewboolean
为 true 时添加 preview（前 200 个字符）和 preview_tables，用于平铺视图。
默认值：false
updated_sincestring (date-time)
只返回 updated_at 不早于此时刻（带时区偏移的 RFC 3339）的卡片，用于同步。未显式指定 sort 和 order 时，列表按 updated_at 升序排列，再按 id 排序。已删除的卡片不会列出：删除以事件的形式通知。
metadatamap of string
按 metadata 筛选：metadata[<key>]=<value> 表示精确匹配。最多 3 个条件，且必须全部满足（?metadata[team]=support&metadata[crm_id]=A-1042）。超过 3 个条件或键无效时返回 400 api.metadata_invalid。
collection_idinteger
按 ID 指定合集。同时传入 collection 时，以 collection_id 为准。合集在组织中不存在或不可见时返回 404 collections.not_found。
external_idstring
只返回 external_id 为此值的卡片。
cursorstring
下一页的游标，取自 X-Next-Cursor 或上一个响应（筛选条件相同）的 next_cursor；游标中包含每页数量。与 offset 同时使用时返回 422 validation.failed；属于其他列表、其他筛选条件或格式错误的游标返回 400 api.cursor_invalid。
length ≤ 512
expand[]array of string
要在响应中包含的关联对象（自 1.62.0 起）：操作的 x-expandable 列表中的路径。该参数最多可重复 10 次。路径最多有 2 段，用点分隔（collection.default_owner）。在列表中，路径以 data. 开头，作用于页面中的每一项（expand[]=data.owner）。展开的对象放入该项的 expanded 对象中，ID 字段保持不变。按其自身读取操作的检查，调用方无权查看的对象展开为 null。路径未知、超过 10 个路径或路径超过 2 段时，返回 400 api.expand_invalid。
items ≤ 10

请求头参数

X-View-Asstring
仅适用于具有 admin 角色的 API 密钥。以数据权限档案 <profile>[:viewer|verifier|editor] 的身份发出请求，例如 employee:viewer。部署密钥不能使用此头（403）。

Cookie 参数

kb_view_asstring
会话的“View as”模式 Cookie。POST /auth/view-as 设置该 Cookie，DELETE /auth/view-as 将其清除。

响应

200成功响应

响应头

Link
下一页的地址，<…>; rel="next"。没有此头表示当前是最后一页。
X-Next-Cursor
下一页的游标，用于 cursor 参数。没有此头表示当前是最后一页。
RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：CardList

array of Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
可选值: wholepartial
access_contactstring
申请访问权限时的联系人（仅当 access=partial 时）。
aclobject
字段
- verifyboolean必填
- writeboolean必填
categorystring必填
category_confidencenumber | null必填
category_lockedboolean必填
category_reviewboolean必填
category_sourceCategorySource | null必填
collectionstring必填
collection_idinteger必填
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
最新发布版本的编辑器内容。该字段可能不存在；此时请从草稿获取编辑器内容（带 card_id 调用 POST /v1/drafts）。
editing_lockEditingLock | null
当前的编辑锁。该字段可能不存在；此时编辑器可从 POST /v1/cards/{card_id}/lock 返回的 409 cards.locked 得知谁持有锁。
created_atstring (date-time)必填
days_since_verifiedinteger必填
errorstring | null必填
eventsarray of CardEvent
feedback_neginteger必填
feedback_posinteger必填
foldersarray of CardFolderRef
仅在卡片列表中返回：包含该卡片的文件夹（用户可见的那些），以及它们从合集根目录起的路径。空列表表示卡片不在任何文件夹中。
has_tablesboolean
仅在卡片列表中返回。
hidden_partsboolean
idstring必填
jobJob | null
kindCardKind必填
org_idinteger必填
owner_activeboolean | null
owner_idinteger | null必填
owner_namestring | null必填
pagesinteger | null必填
parserstring | null必填
以中性代码表示的文档解析器：document（完整结构：页面、标题、表格、扫描页）、pdf（PDF 文本层）、docx、xlsx、csv、markdown、html、text。该列表可能扩充。
partsarray of CardPart必填
sensitiveboolean必填
sha256string | null必填
sizeinteger必填
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedboolean必填
source_pathstring | null必填
source_urlstring | null必填
statusstring必填
可选值: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of string必填
titlestring必填
trustnumber必填
trust_if_verifiednumber
trust_partsTrustParts必填
updated_atstring (date-time)必填
verificationVerification必填
verified_atstring (date-time) | null必填
verified_byinteger | null必填
verified_by_namestring | null
verifier_idsarray of integer必填
verifiersarray of object
字段
- activeboolean必填
- idinteger必填
- namestring必填
verify_interval_daysinteger必填
versioninteger必填
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
手动解析设置（预览）。
doc_kindDocKind | null
文档类型。无法确定类型时为 null（例如，在引入文档类型之前索引的卡片）。
doc_kind_confidencenumber | null
对文档类型的置信度，取值 0 到 1。
doc_kind_sourcestring | null
确定类型的方式：规则（rules）、用户（manual）或自动分类。该列表可能扩充：将未知值视为自动分类。
可选值: rulesmanualnull
invoiceDocInvoiceExtraction | null
发票、贷项通知单或收据的字段（仅限这些类型，且只在卡片中返回，不在列表中返回）。如果您无权访问整个文档，则为 null，因为这些字段是从整个文档中提取的。
warningsarray of ReviewWarning
文档解析警告（ReviewWarning；只在卡片中返回，不在列表中返回）。
enrichmentCardEnrichmentStatus | null
信息补全状态（只在卡片中返回，不在列表中返回）。文档类型、发票字段和财务记录在索引后于后台添加，之后可能重新计算；准备就绪后显示在卡片中。null 表示没有可用的状态（卡片在索引时未进行后台信息补全）。
external_idstring | null
卡片在集成方系统中的 ID。在组织内不来自数据源的卡片之间唯一；null 表示未设置。/v1/cards-by-external-id/{external_id} 按该 ID 读取和替换卡片。
length ≤ 512
metadataMetadata

400请求无效：参数值或对象状态不允许执行该操作（`detail` 为消息）。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

401未发送凭据（既没有会话 Cookie，也没有 API 密钥），或未找到该密钥。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

403不允许执行该操作：角色权限不足、无权访问合集或卡片、请求在“View as”模式下执行，或组织已被暂停或删除（`detail` 为对象，包含 `code: org_suspended | org_deleted`）。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

404对象不存在或您无权访问。对于访问受限的对象，API 不会确认其是否存在。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

422校验错误：请求体或参数不符合定义的结构（`detail` 为校验错误列表），或参数值超出范围（`detail` 为消息）。

响应头

RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

429请求过多（`api.rate_limited`）、组织每分钟、每天或每月的配额已用完（`api.quota_exceeded`；`error.details` 中包含 `quota`、`limit` 和 `reset_at`）、已达到组织的限额，或回答服务繁忙（`answers.engine_busy`）。请等待 `Retry-After` 头中给出的时间。

响应头

Retry-After
重试请求前需要等待的秒数。
RateLimit-Policy
当前生效的限制，格式遵循 IETF 草案 draft-ietf-httpapi-ratelimit-headers：以逗号分隔的项 "<name>";q=<quota>;w=<window in seconds>。key 是 API 密钥的请求速率（配额即突发量，时间窗口是配额完全恢复所需的时间；会话为 user，无凭据时为 ip）；minute、day 和 month 是组织按 UTC 计算的自然分钟、自然日和自然月的配额。
RateLimit
RateLimit-Policy 中每项限制的剩余量："<name>";r=<remaining>;t=<seconds until reset>。
X-RateLimit-Limit
RateLimit-Policy 中最严格一项（剩余请求数最少的一项）的限额。
X-RateLimit-Remaining
最严格限制下的剩余请求数。
X-RateLimit-Reset
距最严格限制重置的秒数。

application/json

对象：Error

错误码

除所有请求通用的错误码外，此接口还可能在 error.code 中返回以下错误码。

速率限制

响应带有 RateLimit 和 RateLimit-Policy 头，以及旧版的 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。429 响应带有以秒为单位的 Retry-After：等待后重试。

← cards · API 参考

curl 'https://api.sursa.com/v1/cards' \
  -H "Authorization: Bearer $SURSA_API_KEY"

在线调试

API 密钥

密钥只保存在此标签页的内存中，只会发送到 https://api.sursa.com。

请求会作用于您组织的真实数据。

X-View-As header

collection query

folder query

status query

owner query

owner_id query

verification query

kind query

type query

tags query

ids query

search query

category query

sensitive query

sort query

order query

limit query

offset query

preview query

updated_since query

metadata query

collection_id query

external_id query

cursor query

expand[] query