Citation Integrity API

Academic citation verification API

Citely’s Citation Integrity API verifies whether scholarly references are real by checking metadata across leading global and Chinese scholarly sources. Submit already-separated citations, then poll the asynchronous job for item-level results.

Open API keys OpenAPI 3.1

Authentication

Create an API key in your Citely account and send it as a Bearer token. Keep the complete sk- value private and revoke exposed keys immediately.

Authorization: Bearer sk-your-citely-api-key

The official Codex plugin uses OAuth. Direct REST API integrations and local Marketplace installs use Citely API keys.

Billing and limits

1 Citely Credit checks up to 4 citations.
Each job accepts 1–80 citations; each citation is at most 5,000 characters.
A user may start up to 3 new jobs per minute.
Technical failures are separate from citation results and are refunded under the existing Citely billing rules.

POST/api/v1/citation-checks

Start a citation check

Submit citation strings only. The response includes a job ID and the recommended polling interval.

Request parameters

AuthorizationBearer tokenrequired

header

Your Citely API key.

Idempotency-Keystringrequired

header

A unique request identifier. Safe retries return the same job without charging twice.

itemsarrayrequired

body

1–80 separated citations. Each item contains a stable id and the complete citation string in content.

localestringoptional

body

Preferred result language, such as en-US or zh-CN.

Code examples

curl https://citely.ai/api/v1/citation-checks \
  -X POST \
  -H "Authorization: Bearer sk-your-citely-api-key" \
  -H "Idempotency-Key: your-unique-request-id" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "ref-1",
        "content": "Vaswani et al. Attention Is All You Need. 2017."
      }
    ],
    "locale": "en-US"
  }'

Responses

200

An existing idempotent job has already completed or failed.

202

Job accepted; returns jobId, status, and pollAfterSeconds.

400

The request body or idempotency key is invalid.

401

The API key is missing, invalid, or revoked.

402

The Citely account does not have enough Credits.

409

The idempotency key was reused with different citation content.

429

The task-start rate limit was exceeded.

503

The service is temporarily unavailable; retry safely with the same idempotency key.

GET/api/v1/citation-checks/{jobId}

Get progress and results

Wait at least pollAfterSeconds before polling. Stop when the task status is completed or failed.

Request parameters

AuthorizationBearer tokenrequired

header

The same Citely account that created the job.

jobIdstringrequired

path

The job identifier returned by the start endpoint.

Code examples

curl https://citely.ai/api/v1/citation-checks/{jobId} \
  -H "Authorization: Bearer sk-your-citely-api-key"

Responses

200

Current job status, item progress, completed results, and technical failures.

400

The job ID is invalid.

401

The API key is missing, invalid, or revoked.

404

No job belonging to this account was found.

503

The service is temporarily unavailable; retry the request later.

Result meanings

Citation results and task status are separate. A completed job may contain any of the three citation result values below.

verified: Reliable evidence supports the citation metadata.
mismatch: A likely publication was found, but important metadata differs.
not_found: No reliable match was found after the required sources completed successfully. This is not proof that a citation is fabricated.
error: An item-level technical failure is not a citation verdict. Retry the item when retryable is true; applicable Credits are refunded under existing Citely rules.

Common errors

authentication_required · 401: Authentication is missing, invalid, or revoked.
insufficient_credits · 402: The account balance is too low.
idempotency_conflict · 409: The same key was used for different content.
rate_limited · 429: Wait for retryAfterSeconds before retrying.
service_unavailable · 503: Retry safely with the same idempotency key.

Data and privacy

Send citation strings only—not full manuscripts, unpublished arguments, local file paths, API keys, or unrelated document metadata.

Review Citely's policies or contact support before integrating sensitive workflows.