Endpoints

GET https://veruscite-data.com/api/v1/health

No auth. Returns {"status":"ok"}.

GET https://veruscite-data.com/api/v1/me

Your email and credit balance: {"email":"…","credits":N} (no internal user id).

POST https://veruscite-data.com/api/v1/documents

Upload a file as multipart/form-data, field name file. The body is the raw file bytes (PDF/DOCX/bibliography) with a filename; this is what curl -F "[email protected]" and Python files={"file": (name, bytes_or_file, content_type)} send. Returns 202 with a document id and poll URLs.

Errors: 400 bad file, 401 bad key, 402 no credits, 413 too large. Raw JSON / base64 bodies are not accepted — use multipart only.

GET https://veruscite-data.com/api/v1/documents/{id}

Poll job status. Check status and finished.

GET https://veruscite-data.com/api/v1/documents/{id}/results

Document summary plus full citation list. Each citation has a version field: original (as extracted / before website edit) or edited (current values after a website edit). Citations never edited appear once as original; edited ones appear as two rows (original, then edited). citation_count is the number of unique citations; row_count is the length of the citations array.

PATCH https://veruscite-data.com/api/v1/documents/{id}

Update document metadata (JSON body). Any subset:

• filename (or name) — display title only; does not rename the file on disk
• notes — owner notes ("" or null clears)

Returns {"document":{…},"changed":["filename","notes"]}. Errors: 400 empty/invalid fields, 404 not found.

POST https://veruscite-data.com/api/v1/documents/{id}/citations/{citation_id}

Edit or delete one citation. Identify the row by its stable id from GET …/results (not list index). JSON body:

• action: "edit" (default) or "delete"
• fields: for edit — object of citation fields to change (e.g. title, year, status, citation notes). Unknown keys are ignored. Field keys may also be sent at the top level instead of nested under fields.

Edit returns the updated document summary plus that citation’s result row(s) (original/edited when a snapshot exists). Delete returns {"action":"delete","deleted_id":N,"document":{…}} and refreshes document citation counts. Errors: 400 bad body, 404 document or citation not found.

GET https://veruscite-data.com/api/v1/jobs

Active jobs only (pending or in-process).

GET https://veruscite-data.com/api/v1/documents

List all of your documents (newest first): filename, status, created_at, page/citation counts.

Query params: limit (default 50, max 200), offset, optional status (pending | in-process | completed | failed).

curl -sS "https://veruscite-data.com/api/v1/documents?limit=50" \
  -H "Authorization: Bearer $VERUSCITE_API_KEY" | jq .

Document fields

• id, filename, status, finished
• page_count, total_citations, verified_citations, hallucinations
• created_at
• notes — owner notes saved on the website (or null if unset)

Per-citation notes (checker notes and any edits saved on the results page) appear on each item under GET …/results, separate from the document-level field.

When status is failed, also:

• error — one of: not_enough_credits, too_many_pages, file_too_large, failed
• error_message — short generic message (no internal details)