開發者 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.

需要整合協助？聯絡支援