Examples

export VERUSCITE_API_KEY='vc_your_key_here'

Check account

curl -sS "https://veruscite-data.com/api/v1/me" \
  -H "Authorization: Bearer $VERUSCITE_API_KEY" | jq .

Submit a file

The form field name must be file, and the path needs @ so curl uploads the file contents (not a plain string).

curl -sS -X POST "https://veruscite-data.com/api/v1/documents" \
  -H "Authorization: Bearer $VERUSCITE_API_KEY" \
  -F "file=@./paper.pdf" | jq .

Poll until finished, then get results

DOC_ID=123

while true; do
  RESP=$(curl -sS "https://veruscite-data.com/api/v1/documents/$DOC_ID" \
    -H "Authorization: Bearer $VERUSCITE_API_KEY")
  echo "$RESP" | jq '{status, finished, total_citations}'
  echo "$RESP" | jq -e '.finished == true' >/dev/null && break
  sleep 5
done

curl -sS "https://veruscite-data.com/api/v1/documents/$DOC_ID/results" \
  -H "Authorization: Bearer $VERUSCITE_API_KEY" | jq .

List active jobs

curl -sS "https://veruscite-data.com/api/v1/jobs" \
  -H "Authorization: Bearer $VERUSCITE_API_KEY" | jq .

List all your documents

# Newest first: id, filename, status, created_at, citation counts
curl -sS "https://veruscite-data.com/api/v1/documents?limit=50" \
  -H "Authorization: Bearer $VERUSCITE_API_KEY" | jq .

# Only completed
curl -sS "https://veruscite-data.com/api/v1/documents?status=completed&limit=20" \
  -H "Authorization: Bearer $VERUSCITE_API_KEY" | jq .

Python

import os
import time
import requests

API_KEY = os.environ["VERUSCITE_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
paper_path = "paper.pdf"

with open(paper_path, "rb") as f:
    r = requests.post(
        "https://veruscite-data.com/api/v1/documents",
        headers=HEADERS,
        files={"file": (paper_path, f, "application/pdf")},
    )
r.raise_for_status()
doc_id = r.json()["document"]["id"]

while True:
    st = requests.get(
        f"https://veruscite-data.com/api/v1/documents/{doc_id}",
        headers=HEADERS,
    ).json()
    print(st["status"], st.get("total_citations"))
    if st.get("finished"):
        break
    time.sleep(5)

results = requests.get(
    f"https://veruscite-data.com/api/v1/documents/{doc_id}/results",
    headers=HEADERS,
).json()
print(results["citation_count"], "citations")