تحقق من الاستشهادات برمجيًا. نقطة نهاية واحدة، تدفق عبر SSE.
Base URL
https://api.citetrue.comبداية سريعة
- انتقل إلى لوحة التحكم → مفاتيح API وانقر مفتاح API جديد. انسخ المفتاح الذي يبدأ بـ
sk_. يُعرض مرة واحدة فقط. - أضف المفتاح في
Authorization: Bearer sk_…مع كل طلب. - أرسل POST لـ task إلى
/verify/v2. الاستجابةtext/event-stream؛ استهلك أحداث SSE حتى ترىtask_completed.
أدنى نداء:
curl -N -X POST https://api.citetrue.com/verify/v2 \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"[1] Vaswani, A., Shazeer, N., Parmar (2017). Attention is all you need."}'-N يعطّل تخزين curl المؤقت فتتدفق أحداث SSE سطرًا سطرًا. لم يعد هناك depth لتختاره — تمر كل المراجع بالمسار نفسه. معظمها يكلف رصيدًا واحدًا؛ أما الصعبة التي تحتاج إلى مزيد من مصادر البيانات ومزيد من التحليل فحتى 5.
أمثلة العميل
SSE استجابة HTTP طويلة الأمد حيث ينتهي كل حدث بسطر فارغ (\n\n). تجاوز الأسطر التي لا تبدأ بـ data: وقم بتحليل JSON لبقية.
ملاحظة المتصفح: لا يستطيع EventSource المدمج إرسال رأس Authorization — استخدم fetch + ReadableStream كما يظهر أدناه.
Node 18+ with native fetch.
const API = 'https://api.citetrue.com'
const KEY = process.env.API_KEY
async function verify(text) {
const resp = await fetch(`${API}/verify/v2`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ text }),
})
if (!resp.ok) throw new Error(`${resp.status}: ${await resp.text()}`)
const reader = resp.body.getReader()
const decoder = new TextDecoder()
const refs = []
let buf = ''
while (true) {
const { value, done } = await reader.read()
if (done) break
buf += decoder.decode(value, { stream: true })
let idx
while ((idx = buf.indexOf('\n\n')) !== -1) {
const chunk = buf.slice(0, idx); buf = buf.slice(idx + 2)
for (const line of chunk.split('\n')) {
if (!line.startsWith('data: ')) continue
const evt = JSON.parse(line.slice(6))
if (evt.event === 'ref_completed') {
refs.push(evt.data.ref)
}
if (evt.event === 'task_completed') return { refs, balance: evt.data.balance }
if (evt.event === 'error') throw new Error(evt.error)
}
}
}
}
const out = await verify('[1] Vaswani, A., Shazeer, N., Parmar (2017). Attention is all you need.')
console.log(out)المصادقة
مفاتيح API رموز bearer طويلة الأمد بالشكل sk_<40-char-token>. أرسلها في ترويسة Authorization:
Authorization: Bearer sk_AbCd123…- يمكنك إلغاء مفتاح من لوحة التحكم. الإلغاء ساري خلال ثوانٍ.
- يمكن للمفتاح فعل كل ما يفعله مستخدمه. تعامل معه ككلمة مرور — دوّره وحدّد نطاقه لكل تكامل.
حدود المعدل
لكل مفتاح API مُحدِّد token-bucket:
- دفعة: 10 طلبات.
- مستدام: 60 طلبًا/دقيقة (bucket يُعاد ملؤه بمعدل 1 token/s).
- عند التجاوز يفشل الطلب بـ
429مع ترويسةRetry-After(ثوانٍ).
المُحدِّد لكل مفتاح؛ المفاتيح المختلفة لنفس الحساب لها دِلاء مستقلة. الأرصدة تُطبَّق إضافةً لذلك.
ترويسات الطلب
Every endpoint accepts the same authentication and content-type headers; only the request body and URL differ.
| Header | مطلوب | القيمة |
|---|---|---|
| Authorization | yes | Bearer sk_… |
| Content-Type | yes | application/json |
Responses are 200 OK with Content-Type: text/event-stream.
data: {"event":"<name>","data":{...},"error":""}POST /verify/v2
Split a text blob into references and verify each. Supply exactly one of text (new task) or taskHash (resume). Every reference goes through the same flow — there is no verification level to choose.
جسم الطلب
| الحقل | النوع | ملاحظات |
|---|---|---|
| text | string | New verify task. Max 10MB. Accepts numbered, bulleted, blank-line-separated, BibTeX, or in-text prose with (Author, Year) citations. |
| taskHash | string | Resume an existing task — replays cached state or attaches to live stream. References already charged aren't charged again; any that still need work are finished and billed as usual. |
| force | bool | Bypass the task-level dedup cache (forces a fresh run, billed like a new check). |
| locale | string | Optional 2-letter language code ("zh", "ja", "de", …). When set, AI translates the per-ref note into that language and surfaces it under noteTranslated[locale]. Default "" / "en" = no translation. |
Idempotency: same text + same user returns the cached task on second POST (no re-billing) unless force: true.
Deprecated fields
depth— still accepted but ignored (1,5,20or omitted all behave the same). Don't send it.refHash+parentTaskHash— legacy single-reference mode kept for older clients. It ignoresdepthand simply finishes that one reference, billed under the normal rules. New integrations shouldn't use it.
طلب مثال (text)
{
"text": "[1] Vaswani, A., Shazeer, N., Parmar (2017). Attention is all you need.\n[2] Piketty, T. (2016). Capital in the twenty-first century. Harvard University Press."
}طلب مثال (resume)
{
"taskHash": "f0e1d2c3b4a5..."
}تسلسل الأحداث النموذجي
task_created → refs_created (N refs) →
[ref_processing + ref_completed] × N (parallel) +
task_progress × several →
task_completedPer-ref assessment
Each ref_completed event carries an assessment string from this closed set:
authentic— paper exists and is the one cited.valuecontains the matched paper.unsure— a close candidate was found but couldn't be confirmed;valueis that candidate andconfidencehow likely it is the cited work.inauthentic— definitively not found / fabricated / unrelated.value, if present, is only the closest candidate — not a match.invalid— input wasn't a citation; pipeline refused to search before any datasource hit.error— verification failed on this single ref; sibling refs may still succeed.data.errors[]lists tokens (datasource_unavailable,timeout,rate_limited,parse_failed).exceeded— account ran out of credits before this ref could run.
Notices on a result (year mismatch, author mismatch, …) are orthogonal to assessment — even an authentic verdict can carry notices worth showing. data.cost is the total credits this task has charged for the reference (0–5): 1 for most references, up to 5 for tricky ones that needed more data sources and more analysis, 0 if it was already paid for in another task. It covers every connection and resume of the same task, and the same number is sent on every push, replays included — overwrite it, don't add it up across reconnects. data.depth is kept only for compatibility with older clients — ignore it.
قيم Notice
notices[] on a ref is a set of soft-fail flags. For programmatic checks, match on these rather than on the English note.
| Value | Meaning |
|---|---|
doi_incorrect | The DOI written in the citation doesn't exist, or it belongs to a different work. Can come with any assessment: on authentic the work is real but the citation carries the wrong DOI; on unsure / inauthentic it is strong evidence that the reference was made up. |
year | The matched record's year differs from the cited year by two years or more. One-year gaps (online-first vs. print), books (editions) and web pages (page dates) are not flagged. |
link | Only a citation record was matched, with no link to the work itself — other papers cite it, but no direct source was found. |
authors | In-text citations: the cited authors don't fully line up with the matched work. |
title | In-text citations: what the sentence describes doesn't fully line up with the matched work. |
likely, url_inaccessible, url_inconsistent, url_mismatch, url_unsure, url_incorrect | Only on results of older checks that are replayed from cache; current checks don't produce them. |
Notices never change the assessment. New values may appear as more mismatch classes are detected — treat unknown tokens as a generic warning.
أحداث SSE
SSE event names emitted during verification. Listen for task_completed as the terminal success event; error for terminal failure.
task_created— task accepted, hash assigned.refs_created— text was split into N refs.split_completed— splitting phase finished.ref_processing/ref_status— per-ref progress signal.ref_completed— per-ref final assessment.task_completed— all refs done; carriescost(credits newly charged during this connection, 0 for a pure replay) and the accountbalanceafterwards (can be negative — see Credits & billing).task_progress— periodic progress %.warn— non-fatal warning.error— terminal task-level failure.
GET /credits
GET /credits — returns the current credit balance (totalBalance) and the active credit records. Auth required. The balance can be negative (see Credits & billing).
الأرصدة والفوترة
Most references cost 1 credit. Tricky ones that need more data sources and more analysis can cost up to 5. Each reference is charged 1 credit when it's queued; anything extra is added when it finishes. Cached tasks (same text + user) do not re-bill.
Reading the charge: data.cost in ref_completed is the running total this task has charged for that reference — the same number is sent again on reconnects and replays, so overwrite it rather than adding it up. cost in task_completed is what this connection newly charged (0 for a pure replay), so after a reconnect it won't equal the sum of the per-ref costs. balance is the account balance afterwards.
Running out: a reference that hasn't started when the balance can't cover it comes back as exceeded, and the task still ends with task_completed. If you run out of credits mid-check, references already in progress still finish; the overage is deducted at your next credit reset, so balance can be negative.
مرجع الأخطاء
Standard HTTP status codes apply (400 malformed body, 401 missing / invalid / revoked key, 405 wrong method, 429 rate-limited, 5xx upstream). Running out of credits is not an HTTP error: references that can't start come back as exceeded. SSE-level failures arrive as a final error event.
الإصدارات والاستقرار
Path-versioned (/verify/v2 etc.). Breaking changes bump the version segment; backwards-compatible additions ship in-place.
يتولى صيانته فريق CiteTrue · آخر تحديث: