开发者 APIv1稳定版

CiteWise API 文档

将参考文献质量控制接入研究工作流。解析元数据、查看来源证据、生成修正建议、格式化引用，并通过同一套工作区 API 处理批量任务。

基础 URL

https://api.citewise.dev从请求开始

发出第一个请求

将参考文献质量控制接入研究工作流。解析元数据、查看来源证据、生成修正建议、格式化引用，并通过同一套工作区 API 处理批量任务。

bashCiteWise API

curl https://api.citewise.dev/api/v1/citations/parse \
  -X POST \
  -H "X-API-Key: cw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "Vaswani A. Attention Is All You Need. 2017.",
    "async": false
  }'

认证方式

服务端集成使用付费工作区 API 密钥；浏览器会话使用 Clerk JWT。每个资源都限定在已认证的工作区内。

请求约定

将参考文献质量控制接入研究工作流。解析元数据、查看来源证据、生成修正建议、格式化引用，并通过同一套工作区 API 处理批量任务。

内容类型

JSON or multipart

可下载的审计文件，包含风险、关键元数据和人工复核字段。

可追溯性

X-Trace-Id

可选 request ID. The response exposes the trace ID for support.

分页

page + size

批量条目页从 0 开始，单页最多 200 条。

重试

Retry-After

遇到速率、并发或系统繁忙响应时，请遵循此响应头。

参考文献 API

验证并丰富参考文献

先解析参考文献，再使用返回的 citationId 获取证据、生成修正和格式化结果。所有参考文献接口都限定在工作区内。

POST/api/v1/citations/parse

解析并验证参考文献

返回当前工作区范围内的资源和相关元数据。

API 密钥或 Clerk JWThttps://api.citewise.dev

请求体

内容类型: application/json

字段	类型	必填	描述
reference	string	必填	原始引用、DOI、URL 或不完整参考文献。最多 8,000 个字符。
async	boolean	可选	Reserved for asynchronous processing. 默认 false; send false for the immediate parse response.

jsonCiteWise API

{
  "reference": "Vaswani, A. Attention Is All You Need. 2017.",
  "async": false
}

响应

200 OK

字段	类型	必填	描述
citationId	UUID	-	标识符 for follow-up citation endpoints.
status	string	-	Verification decision.
confidence	number	-	总体置信度，范围为 0 到 1。
citation	CitationDto	-	Full persisted citation, metadata fields, verification details, and APA rendering.

jsonCiteWise API

{
  "citationId": "7d9a7d7e-9df7-4c84-9f2a-2f4a7d9c4b11",
  "status": "VERIFIED",
  "confidence": 0.99,
  "citation": {
    "id": "7d9a7d7e-9df7-4c84-9f2a-2f4a7d9c4b11",
    "status": "VERIFIED",
    "confidence": 0.99,
    "title": { "fieldName": "title", "value": "Attention Is All You Need", "confidence": 0.99, "algorithm": "PROVIDER_FUSION", "evidence": [] },
    "verification": { "rawReference": "Vaswani A. ...", "normalizedReference": "Vaswani A... 2017", "matchScore": 0.99, "candidateMargin": 0.42, "features": {}, "matchedProviders": ["CROSSREF", "OPENALEX"], "contradictions": [], "candidates": [], "providerDiagnostics": [] },
    "renderedApa": "Vaswani, A., ... (2017).",
    "createdAt": "2026-01-15T10:20:30Z"
  }
}

实现说明

返回当前工作区范围内的资源和相关元数据。

GET/api/v1/citations

列出最近的参考文献

返回 recent citations for the authenticated workspace, ordered by the workspace history service.

API 密钥或 Clerk JWThttps://api.citewise.dev

响应

200 OK

字段	类型	必填	描述
[]	CitationSummary[]	-	该字段表示系统对结果或提取值的置信度，范围为 0 到 1。

jsonCiteWise API

[
  {
    "id": "7d9a7d7e-9df7-4c84-9f2a-2f4a7d9c4b11",
    "rawReference": "Vaswani A. Attention Is All You Need. 2017.",
    "status": "VERIFIED",
    "confidence": 0.99,
    "renderedApa": "Vaswani, A., ... (2017).",
    "createdAt": "2026-01-15T10:20:30Z"
  }
]

GET/api/v1/citations/{id}

获取参考文献

返回当前工作区范围内的资源和相关元数据。

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。

响应

200 OK

字段	类型	必填	描述
id	UUID	-	已保存的参考文献标识符。
status	string	-	VERIFIED, PROBABLY_VERIFIED, AMBIGUOUS, CONFLICTING_METADATA, NOT_FOUND, INSUFFICIENT_EVIDENCE, or POSSIBLE_HALLUCINATION.
confidence	number	-	总体置信度，范围为 0 到 1。
parsingConfidence	number	-	该字段表示系统对结果或提取值的置信度，范围为 0 到 1。
identityConfidence	number	-	该字段表示系统对结果或提取值的置信度，范围为 0 到 1。
title ... publisher	FieldDto \| null	-	解析后的元数据字段；每个字段包含值、置信度、算法和证据。
verification	VerificationDto	-	标准化输入、匹配分数、来源诊断、冲突和候选匹配。
renderedApa	string \| null	-	APA rendering generated during verification.
createdAt	ISO-8601 timestamp	-	以 UTC 表示的创建时间。

jsonCiteWise API

{
  "id": "7d9a7d7e-9df7-4c84-9f2a-2f4a7d9c4b11",
  "status": "VERIFIED",
  "confidence": 0.99,
  "title": { "fieldName": "title", "value": "Attention Is All You Need", "confidence": 0.99 },
  "verification": { "matchedProviders": ["CROSSREF"], "contradictions": [], "candidates": [] },
  "renderedApa": "Vaswani, A., ... (2017).",
  "createdAt": "2026-01-15T10:20:30Z"
}

GET/api/v1/citations/{id}/evidence

获取字段证据

返回 provider evidence grouped by metadata field. Use this to show why a field was accepted or investigate a contradiction.

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。

响应

200 OK

字段	类型	必填	描述
{fieldName}	EvidenceDto[]	-	Dynamic keys such as title, authors, year, doi, or journal map to evidence arrays.
source / value	string / unknown	-	来源标识符及来源返回的值。
sourceReliability	number	-	已配置的来源可靠性，范围为 0 到 1。
extractionConfidence	number	-	该值被正确提取的置信度。
contextMatchScore	number	-	来源结果与提交的参考文献的匹配程度。
weightedScore	number	-	综合证据分数。
createdAt	ISO-8601 timestamp	-	以 UTC 表示的证据采集时间。

jsonCiteWise API

{
  "title": [
    { "source": "CROSSREF", "value": "Attention Is All You Need", "sourceReliability": 0.98, "extractionConfidence": 1.0, "contextMatchScore": 0.99, "weightedScore": 0.97, "createdAt": "2026-01-15T10:20:30Z" }
  ],
  "doi": []
}

POST/api/v1/citations/{id}/correction-proposals

生成修正建议

返回当前工作区范围内的资源和相关元数据。

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。

响应

200 OK

字段	类型	必填	描述
citationId	UUID	-	Citation being evaluated.
decision	string	-	PROPOSED, NO_CHANGES, or REVIEW_REQUIRED.
changes	CorrectionChangeDto[]	-	该字段表示系统对结果或提取值的置信度，范围为 0 到 1。
unresolvedConflicts	string[]	-	Conflicts that could not be resolved automatically.

jsonCiteWise API

{
  "citationId": "7d9a7d7e-9df7-4c84-9f2a-2f4a7d9c4b11",
  "decision": "PROPOSED",
  "changes": [{ "field": "doi", "changeType": "RECOVERED", "originalValue": null, "proposedValue": "10.48550/arXiv.1706.03762", "confidence": 0.98, "provenance": "PROVIDER_BACKED", "sources": ["CROSSREF"], "reason": "Proposed value is supported by external scholarly metadata" }],
  "unresolvedConflicts": []
}

POST/api/v1/citations/render

生成引用格式

Renders a stored citation or caller-supplied metadata in one or more supported styles. Exactly one of citationId or metadata is 必填.

API 密钥或 Clerk JWThttps://api.citewise.dev

请求体

内容类型: application/json

字段	类型	必填	描述
citationId	UUID	-	已保存的 citation. Mutually exclusive with metadata.
metadata	CitationMetadataRequest	-	Inline metadata. Include at least one field; mutually exclusive with citationId.
styles	string[]	-	最多 10 styles. 默认 ["APA7"]. 支持: APA7, MLA9, CHICAGO_AUTHOR_DATE, IEEE, VANCOUVER, GBT7714.

jsonCiteWise API

{
  "citationId": "7d9a7d7e-9df7-4c84-9f2a-2f4a7d9c4b11",
  "styles": ["APA7", "MLA9", "IEEE"]
}

响应

200 OK

字段	类型	必填	描述
citationId	UUID \| null	-	已保存的 citation ID, or null when rendering inline metadata.
renderings	object	-	Map of canonical style name to rendered citation string.

jsonCiteWise API

{
  "citationId": "7d9a7d7e-9df7-4c84-9f2a-2f4a7d9c4b11",
  "renderings": { "APA7": "Vaswani, A., ... (2017).", "MLA9": "Vaswani, Ashish, et al. ...", "IEEE": "A. Vaswani et al., ..." }
}

实现说明

For inline rendering, send metadata with fields such as title, authors, year, doi, and publisher. Inline metadata is not persisted.

批量任务

处理更大规模的工作流

使用持久化任务处理多条参考文献、进度查询或去重。创建任务会返回 HTTP 202 和 Location 响应头。

POST/api/v1/citation-imports/preview

预览结构化导入

返回解析结果或任务中的记录数量。

API 密钥或 Clerk JWThttps://api.citewise.dev

请求体

内容类型: multipart/form-data

字段	类型	必填	描述
file	multipart file	必填	处理结构化文件并返回格式、记录数量、警告和标准化元数据。
format	string (query)	-	可选 explicit format: BIBTEX, RIS, ENDNOTE, or CSL_JSON. The extension is used by default.

bashCiteWise API

curl -X POST "https://api.citewise.dev/api/v1/citation-imports/preview?format=RIS" -H "X-API-Key: cw_live_your_key" -F "file=@references.ris"

处理结构化文件并返回格式、记录数量、警告和标准化元数据。

响应

200 OK

字段	类型	必填	描述
format	string	-	Detected format: BIBTEX, RIS, ENDNOTE, or CSL_JSON.
totalRecords	integer	-	数量 source records found in the file.
validRecords	integer	-	Records successfully converted to common CSL metadata.
invalidRecords	integer	-	Records that could not be converted and will not enter a job.
warningCount	integer	-	总计 warnings across all parsed records.
records	ImportRecordPreview[]	-	最多 10 previews with index, sourceKey, title, authors, year, doi, and warnings.

jsonCiteWise API

{
  "format": "BIBTEX",
  "totalRecords": 2, "validRecords": 2, "invalidRecords": 0, "warningCount": 0,
  "records": [{ "index": 1, "sourceKey": "vaswani2017", "title": "Attention Is All You Need", "authors": "Vaswani, Ashish", "year": 2017, "doi": null, "warnings": [] }]
}

POST/api/v1/citation-imports/jobs

创建导入任务

Re-uploads a previously previewed structured file and creates a durable verification job. Only valid records are submitted, at least two valid records are 必填, and quota is reserved at this point.

API 密钥或 Clerk JWThttps://api.citewise.dev

请求体

内容类型: multipart/form-data

字段	类型	必填	描述
file	multipart file	必填	处理结构化文件并返回格式、记录数量、警告和标准化元数据。
styles	string[] (repeated multipart parts)	-	可选 repeated form parts such as styles=APA7&styles=MLA9; defaults to APA7.
format	string (query)	-	可选 explicit format override.

bashCiteWise API

curl -X POST "https://api.citewise.dev/api/v1/citation-imports/jobs?format=RIS" -H "X-API-Key: cw_live_your_key" -F "file=@references.ris" -F "styles=APA7" -F "styles=IEEE"

The response is the same 202 job resource returned by /api/v1/citation-jobs. Each item stores its original source record, while the upload itself is not persisted. At least two valid records are 必填.

响应

202 Accepted

字段	类型	必填	描述
id	UUID	-	用于后续请求的资源标识符。
type	string	-	VERIFY_AND_CORRECT or DEDUPLICATE.
status	string	-	按照请求安排或执行取消，并返回更新后的订阅或任务状态。
totalItems / processedItems	integer	-	总计 inputs and items that have finished processing.
succeededItems / failedItems	integer	-	成功的 and failed item counters.
cancelRequested	boolean	-	是否 cancellation has been requested.
result	object \| null	-	Aggregate result when the job completes.
errorCode / errorMessage	string \| null	-	Job-level failure details, when applicable.
createdAt ... updatedAt	ISO-8601 timestamp	-	Job lifecycle timestamps in UTC.

jsonCiteWise API

{
  "id": "3f0f7d3c-7033-4b0d-92df-5e8d5ab2e7f6",
  "type": "VERIFY_AND_CORRECT",
  "status": "QUEUED",
  "totalItems": 2, "processedItems": 0, "succeededItems": 0, "failedItems": 0
}

POST/api/v1/citation-jobs

创建参考文献任务

返回资源当前状态；可能值请参阅接口定义。

API 密钥或 Clerk JWThttps://api.citewise.dev

请求体

内容类型: application/json

字段	类型	必填	描述
type	string	必填	VERIFY_AND_CORRECT for references, or DEDUPLICATE for existing citationIds.
references	string[]	-	最多 1,000 references, each up to 8,000 characters. Required for VERIFY_AND_CORRECT.
citationIds	UUID[]	-	最多 1,000 stored citation IDs. Required for DEDUPLICATE.
options.styles	string[]	-	最多 10 render styles. 默认 ["APA7"].

jsonCiteWise API

{
  "type": "VERIFY_AND_CORRECT",
  "references": ["Vaswani A. Attention Is All You Need. 2017.", "Devlin J. BERT: Pre-training of Deep Bidirectional Transformers. 2019."],
  "options": { "styles": ["APA7", "IEEE"] }
}

响应

202 Accepted

字段	类型	必填	描述
id	UUID	-	用于后续请求的资源标识符。
type	string	-	VERIFY_AND_CORRECT or DEDUPLICATE.
status	string	-	按照请求安排或执行取消，并返回更新后的订阅或任务状态。
totalItems / processedItems	integer	-	总计 inputs and items that have finished processing.
succeededItems / failedItems	integer	-	成功的 and failed item counters.
cancelRequested	boolean	-	是否 cancellation has been requested.
result	object \| null	-	Aggregate result when the job completes.
errorCode / errorMessage	string \| null	-	Job-level failure details, when applicable.
createdAt ... updatedAt	ISO-8601 timestamp	-	Job lifecycle timestamps in UTC.

jsonCiteWise API

{
  "id": "3f0f7d3c-7033-4b0d-92df-5e8d5ab2e7f6",
  "type": "VERIFY_AND_CORRECT",
  "status": "QUEUED",
  "totalItems": 2, "processedItems": 0, "succeededItems": 0, "failedItems": 0,
  "cancelRequested": false, "result": null, "errorCode": null, "errorMessage": null,
  "createdAt": "2026-01-15T10:20:30Z", "startedAt": null, "completedAt": null, "updatedAt": "2026-01-15T10:20:30Z"
}

GET/api/v1/citation-jobs/{id}

获取任务状态

返回资源当前状态；可能值请参阅接口定义。

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。

响应

200 OK

字段	类型	必填	描述
id	UUID	-	用于后续请求的资源标识符。
type	string	-	VERIFY_AND_CORRECT or DEDUPLICATE.
status	string	-	按照请求安排或执行取消，并返回更新后的订阅或任务状态。
totalItems / processedItems	integer	-	总计 inputs and items that have finished processing.
succeededItems / failedItems	integer	-	成功的 and failed item counters.
cancelRequested	boolean	-	是否 cancellation has been requested.
result	object \| null	-	Aggregate result when the job completes.
errorCode / errorMessage	string \| null	-	Job-level failure details, when applicable.
createdAt ... updatedAt	ISO-8601 timestamp	-	Job lifecycle timestamps in UTC.

jsonCiteWise API

{
  "id": "3f0f7d3c-7033-4b0d-92df-5e8d5ab2e7f6",
  "type": "VERIFY_AND_CORRECT",
  "status": "COMPLETED_WITH_ERRORS",
  "totalItems": 2, "processedItems": 2, "succeededItems": 1, "failedItems": 1,
  "cancelRequested": false, "result": null, "errorCode": null, "errorMessage": null,
  "createdAt": "2026-01-15T10:20:30Z", "startedAt": "2026-01-15T10:20:31Z", "completedAt": "2026-01-15T10:21:02Z", "updatedAt": "2026-01-15T10:21:02Z"
}

GET/api/v1/citation-jobs/{id}/items

列出任务条目

返回 item-level results and failures in item-index order.

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。
page	integer (query)	-	Zero-indexed page number. 默认 0.
size	integer (query)	-	Page size, defaults to 100 and is clamped to 1-200.

响应

200 OK

字段	类型	必填	描述
jobId / page / size	UUID / integer / integer	-	Job ID and effective zero-indexed pagination values. Size is clamped to 1-200.
totalItems / totalPages	integer	-	分页 totals.
items	CitationJobItemResponse[]	-	记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。

jsonCiteWise API

{
  "jobId": "3f0f7d3c-7033-4b0d-92df-5e8d5ab2e7f6", "page": 0, "size": 100, "totalItems": 2, "totalPages": 1,
  "items": [{ "id": "a3c1...", "index": 0, "status": "SUCCEEDED", "reference": "Vaswani A. ...", "sourceRecord": "TY  - JOUR\nTI  - ...\nER  -", "inputCitationId": null, "citationId": "7d9a...", "result": { "parsed": {}, "correction": {}, "rendered": {} }, "errorCode": null, "errorMessage": null }]
}

实现说明

可选 query parameters are page (default 0) and size (default 100, maximum 200).

PATCH/api/v1/citation-jobs/{jobId}/items/{itemId}/review

记录人工复核决定

记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
jobId	UUID	必填	返回参考文献审计的风险分类、建议操作、复核进度和汇总数据。
itemId	UUID	必填	用于后续请求的资源标识符。

请求体

内容类型: application/json

字段	类型	必填	描述
decision	string	必填	ACCEPT_RESOLVED, ACCEPT_CORRECTION, CHOOSE_CANDIDATE, KEEP_ORIGINAL, MARK_FOR_REVIEW, or UNABLE_TO_DETERMINE.
candidateSourceId	string	-	用于后续请求的资源标识符。
note	string	-	可选 reviewer note, up to 2,000 characters.

jsonCiteWise API

{
  "decision": "CHOOSE_CANDIDATE",
  "candidateSourceId": "CROSSREF:10.5555/test",
  "note": "Confirmed against the publisher record."
}

响应

200 OK

字段	类型	必填	描述
reviewDecision	string	-	记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。
selectedCandidateSourceId	string \| null	-	Selected candidate for CHOOSE_CANDIDATE.
reviewNote	string \| null	-	记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。
reviewedBy / reviewedAt	UUID \| null / timestamp	-	记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。

jsonCiteWise API

{
  "id": "a3c1...",
  "riskLevel": "REVIEW",
  "reviewDecision": "CHOOSE_CANDIDATE",
  "selectedCandidateSourceId": "CROSSREF:10.5555/test",
  "reviewNote": "Confirmed against the publisher record.",
  "reviewedAt": "2026-10-09T08:30:00Z"
}

实现说明

记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。

POST/api/v1/citation-jobs/{id}/cancel

取消任务

按照请求安排或执行取消，并返回更新后的订阅或任务状态。

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。

响应

200 OK

字段	类型	必填	描述
id	UUID	-	用于后续请求的资源标识符。
type	string	-	VERIFY_AND_CORRECT or DEDUPLICATE.
status	string	-	按照请求安排或执行取消，并返回更新后的订阅或任务状态。
totalItems / processedItems	integer	-	总计 inputs and items that have finished processing.
succeededItems / failedItems	integer	-	成功的 and failed item counters.
cancelRequested	boolean	-	是否 cancellation has been requested.
result	object \| null	-	Aggregate result when the job completes.
errorCode / errorMessage	string \| null	-	Job-level failure details, when applicable.
createdAt ... updatedAt	ISO-8601 timestamp	-	Job lifecycle timestamps in UTC.

jsonCiteWise API

{
  "id": "3f0f7d3c-7033-4b0d-92df-5e8d5ab2e7f6", "type": "VERIFY_AND_CORRECT", "status": "CANCELLED",
  "totalItems": 100, "processedItems": 12, "succeededItems": 12, "failedItems": 0, "cancelRequested": true,
  "result": null, "errorCode": null, "errorMessage": null, "createdAt": "2026-01-15T10:20:30Z", "startedAt": "2026-01-15T10:20:31Z", "completedAt": "2026-01-15T10:21:02Z", "updatedAt": "2026-01-15T10:21:02Z"
}

GET/api/v1/citation-jobs/{id}/preflight

获取参考文献审计报告

返回 the pre-submission risk summary for a batch job. Each item is classified as BLOCKING, HIGH, REVIEW, LOW, or INFO with a recommended action. The report is derived from persisted verification results and does not re-run providers or consume additional verification quota.

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。

响应

200 OK

字段	类型	必填	描述
schemaVersion	integer	-	当前 Reference Audit schema version. Version 2 adds human review state.
summary	PreflightSummary	-	返回参考文献审计的风险分类、建议操作、复核进度和汇总数据。
items	CitationJobItemResponse[]	-	记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。
limitations	string[]	-	处理结构化文件并返回格式、记录数量、警告和标准化元数据。

jsonCiteWise API

{
  "schemaVersion": 2,
  "product": "CiteWise Reference Audit",
  "summary": { "jobId": "3f0f...", "complete": true, "totalReferences": 20, "processedReferences": 20, "verified": 14, "needsReview": 4, "blocking": 2, "reviewed": 12, "pendingReview": 8, "unableToDetermine": 1 },
  "items": [{ "index": 0, "riskLevel": "HIGH", "recommendedAction": "REPLACE_IDENTIFIER", "reviewDecision": "MARK_FOR_REVIEW" }],
  "limitations": ["Provider availability can affect an individual result."]
}

实现说明

返回当前工作区范围内的资源和相关元数据。

GET/api/v1/citation-jobs/{id}/preflight/export

导出参考文献审计

返回参考文献审计的风险分类、建议操作、复核进度和汇总数据。

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。
format	string (query)	必填	json, csv, or html.

响应

200 OK

字段	类型	必填	描述
JSON	application/json	-	Versioned report with summary, enriched items, and limitations.
CSV	text/csv; charset=UTF-8	-	返回参考文献审计的风险分类、建议操作、复核进度和汇总数据。
HTML	text/html; charset=UTF-8	-	可下载的审计文件，包含风险、关键元数据和人工复核字段。

jsonCiteWise API

GET /api/v1/citation-jobs/3f0f.../preflight/export?format=csv

Content-Disposition: attachment; filename="citewise-preflight-3f0f7d3c.csv"

实现说明

记录人工复核决定、复核备注与时间，同时保留系统生成的风险判断和原始参考文献。

工作区

管理用量和凭证

这些接口都限定在工作区内。控制台用户通常使用 Clerk 会话；当前后端也接受 API 密钥，但账单结账仍需要交互式 Clerk 会话。

GET/api/v1/console/overview

获取工作区概览

返回 the current user, workspace, plan entitlement, monthly reference usage, and admin flag.

API 密钥或 Clerk JWThttps://api.citewise.dev

响应

200 OK

字段	类型	必填	描述
user	object	-	id, email, displayName, imageUrl, and role.
workspace	object	-	id, name, and slug.
entitlement	EntitlementSnapshot	-	Plan code, status, monthly allowance, one-time credit balance, throughput, concurrency, and API 访问权限.
referencesUsed	integer	-	当前 monthly reference reservations.
admin	boolean	-	是否 the user has admin privileges.

jsonCiteWise API

{
  "user": { "id": "...", "email": "researcher@example.com", "displayName": "Ada", "imageUrl": null, "role": "USER" },
  "workspace": { "id": "...", "name": "Ada's workspace", "slug": "ada-workspace" },
  "entitlement": { "planCode": "FREE", "subscriptionStatus": "ACTIVE", "monthlyReferences": 10, "creditBalance": 100, "requestsPerMinute": 10, "concurrency": 1, "apiAccess": false, "currentPeriodEnd": null, "cancelAtPeriodEnd": false, "hasSubscription": false, "canCancel": false, "canResume": false },
  "referencesUsed": 2, "admin": false
}

GET/api/v1/api-keys

列出 API 密钥

返回当前工作区范围内的资源和相关元数据。

API 密钥或 Clerk JWThttps://api.citewise.dev

响应

200 OK

字段	类型	必填	描述
id / name	UUID / string	-	用于后续请求的资源标识符。
prefix / last4	string	-	Safe display prefix and last four secret characters.
status	string	-	ACTIVE or REVOKED.
createdAt / lastUsedAt / expiresAt	timestamp \| null	-	Key lifecycle metadata.

jsonCiteWise API

[
  { "id": "c4c7...", "name": "Production pipeline", "prefix": "cw_live_a1b2c3", "last4": "xYz9", "status": "ACTIVE", "createdAt": "2026-01-15T10:20:30Z", "lastUsedAt": null, "expiresAt": null }
]

POST/api/v1/api-keys

创建 API 密钥

创建或提交请求指定的资源，并返回其当前状态。

API 密钥或 Clerk JWThttps://api.citewise.dev

请求体

内容类型: application/json

字段	类型	必填	描述
name	string	必填	便于阅读的 name, trimmed and limited to 100 characters.

jsonCiteWise API

{
  "name": "Production pipeline"
}

响应

200 OK

字段	类型	必填	描述
key	ApiKeyView	-	Safe key metadata returned for display.
apiKey	string	-	完整密钥. This is the only response that contains it.

jsonCiteWise API

{
  "key": { "id": "c4c7...", "name": "Production pipeline", "prefix": "cw_live_a1b2c3", "last4": "xYz9", "status": "ACTIVE", "createdAt": "2026-01-15T10:20:30Z", "lastUsedAt": null, "expiresAt": null },
  "apiKey": "cw_live_a1b2c3_your-secret-value"
}

实现说明

API 访问权限 must be enabled for the workspace. A workspace can have up to 10 active keys. Treat the secret like a password.

DELETE/api/v1/api-keys/{id}

移除 API 密钥

Immediately marks a workspace API key as revoked. Existing requests using it will fail authentication.

API 密钥或 Clerk JWThttps://api.citewise.dev

路径和查询参数

字段	类型	必填	描述
id	UUID	必填	用于后续请求的资源标识符。

响应

204 No Content

无响应体。

实现说明

The response has no body. Keep the key ID from the list endpoint for revocation workflows.

账单

管理套餐和账单

账单接口由控制台使用。Creem 是结账、订阅生命周期、付款方式和发票的事实来源。

GET/api/v1/billing/subscription

获取订阅权益

返回 the effective plan and limits for the authenticated workspace, including free-plan defaults and cancellation state.

API 密钥或 Clerk JWThttps://api.citewise.dev

响应

200 OK

字段	类型	必填	描述
planCode / subscriptionStatus	string	-	返回资源当前状态；可能值请参阅接口定义。
monthlyReferences	integer	-	每月参考文献额度.
creditBalance	integer	-	剩余 one-time credits, consumed after the monthly allowance.
requestsPerMinute / concurrency	integer	-	Throughput and concurrent execution limits.
apiAccess	boolean	-	是否 workspace API keys are enabled.
currentPeriodEnd	timestamp \| null	-	当前 billing period end.
cancelAtPeriodEnd	boolean	-	是否 cancellation is scheduled at the end of the current period.
currentPeriodStart	timestamp \| null	-	当前 billing period start.
hasSubscription	boolean	-	是否 the workspace has a provider-managed paid subscription.
canCancel / canResume	boolean	-	是否 the current subscription state supports the corresponding lifecycle action.

jsonCiteWise API

{
  "planCode": "PRO", "subscriptionStatus": "ACTIVE", "monthlyReferences": 500, "creditBalance": 100, "requestsPerMinute": 60, "concurrency": 5, "apiAccess": true,
  "currentPeriodEnd": "2026-02-15T00:00:00Z", "cancelAtPeriodEnd": false, "hasSubscription": true, "canCancel": true, "canResume": false
}

POST/api/v1/billing/checkout

创建结账会话

返回当前工作区范围内的资源和相关元数据。

Clerk JWT 必填https://api.citewise.dev

请求体

内容类型: application/json

字段	类型	必填	描述
productKey	string	必填	Configured product key, such as pro-monthly, team-yearly, starter-pack, research-pack, or lab-pack.

jsonCiteWise API

{
  "productKey": "pro-monthly"
}

响应

200 OK

字段	类型	必填	描述
checkoutId	string	-	来源 checkout identifier.
checkoutUrl	string	-	Hosted checkout URL.

jsonCiteWise API

{
  "checkoutId": "ch_123456",
  "checkoutUrl": "https://checkout.creem.io/ch_123456"
}

POST/api/v1/billing/checkout/confirm

确认结账结果

返回资源当前状态；可能值请参阅接口定义。

Clerk JWT 必填https://api.citewise.dev

请求体

内容类型: application/json

字段	类型	必填	描述
checkoutId	string	必填	用于后续请求的资源标识符。

jsonCiteWise API

{
  "checkoutId": "chk_123456"
}

响应

200 OK

字段	类型	必填	描述
hasSubscription	boolean	-	True when a recurring checkout has been linked successfully.
planCode / subscriptionStatus	string	-	The reconciled workspace entitlement.

jsonCiteWise API

{
  "planCode": "PRO", "subscriptionStatus": "ACTIVE", "hasSubscription": true, "canCancel": true
}

POST/api/v1/billing/subscription/cancel

取消订阅

按照请求安排或执行取消，并返回更新后的订阅或任务状态。

Clerk JWT 必填https://api.citewise.dev

请求体

内容类型: application/json

字段	类型	必填	描述
mode	string (optional)	-	scheduled (default) or immediate.

jsonCiteWise API

{
  "mode": "scheduled"
}

响应

200 OK

字段	类型	必填	描述
cancelAtPeriodEnd	boolean	-	按照请求安排或执行取消，并返回更新后的订阅或任务状态。
currentPeriodEnd	timestamp \| null	-	日期 through which access remains available.

jsonCiteWise API

{
  "planCode": "PRO", "subscriptionStatus": "SCHEDULED_CANCEL", "cancelAtPeriodEnd": true,
  "currentPeriodEnd": "2026-02-15T00:00:00Z"
}

POST/api/v1/billing/subscription/resume

恢复订阅

按照请求安排或执行取消，并返回更新后的订阅或任务状态。

Clerk JWT 必填https://api.citewise.dev

响应

200 OK

字段	类型	必填	描述
subscriptionStatus	string	-	Usually ACTIVE after a successful resume.
cancelAtPeriodEnd	boolean	-	按照请求安排或执行取消，并返回更新后的订阅或任务状态。

jsonCiteWise API

{
  "planCode": "PRO", "subscriptionStatus": "ACTIVE", "cancelAtPeriodEnd": false
}

POST/api/v1/billing/portal

打开账单门户

创建或提交请求指定的资源，并返回其当前状态。

Clerk JWT 必填https://api.citewise.dev

响应

200 OK

字段	类型	必填	描述
customerPortalLink	string	-	Hosted Creem customer portal URL.

jsonCiteWise API

{
  "customerPortalLink": "https://creem.io/customer-portal/..."
}

错误

将参考文献质量控制接入研究工作流。解析元数据、查看来源证据、生成修正建议、格式化引用，并通过同一套工作区 API 处理批量任务。

HTTP	Code	含义
400	INVALID_REFERENCE / UNSUPPORTED_CITATION_STYLE / FUSION_FAILED	请求 body is invalid, a 必填 field is missing, a citation style is unsupported, or evidence fusion could not complete.
400	INVALID_REQUEST	请求 body, path parameter, or 必填 header is malformed.
401	UNAUTHENTICATED / API_KEY_INVALID / WEBHOOK_SIGNATURE_INVALID	No valid Clerk JWT or X-API-Key was provided, or a signed webhook request failed verification.
403	FORBIDDEN / SUBSCRIPTION_REQUIRED	The credential is valid but cannot access this workspace or paid-only feature.
404	CITATION_NOT_FOUND / JOB_NOT_FOUND	The resource does not exist in the authenticated workspace.
405	METHOD_NOT_ALLOWED	The HTTP method is not supported by this endpoint.
415	UNSUPPORTED_MEDIA_TYPE	请求 Content-Type is not supported.
429	QUOTA_EXCEEDED / API_KEY_LIMIT_REACHED / RATE_LIMIT_EXCEEDED / CONCURRENCY_LIMIT_EXCEEDED / SYSTEM_BUSY	The workspace allowance, active-key limit, or processing capacity has been reached. Honor Retry-After when present.
502/503	BILLING_UNAVAILABLE / PROVIDER_UNAVAILABLE / PROVIDER_TIMEOUT	A downstream billing or scholarly provider is unavailable. Retry with backoff.
500	DATABASE_ERROR / INTERNAL_ERROR	An unexpected server error. Include traceId when contacting support.

需要集成帮助？联系支持