Add citations from your own app

Send an essay or a .docx / .pptx that ends with a References section. Cite-Only returns the text or file with (Author, Year) citations added where a listed source backs the paragraph.

Authentication

Create a key in the app under Account → API keys, then send it on every request:

Authorization: Bearer co_your_key

Base URL: https://…

Keep keys on your server. Never put them in browser or mobile app code. Revoke a key in the app at any time; it stops working immediately.

POST/v1/cite

Adds citations. Send either essay or fileBase64.

Request body (JSON)

Field	Description
`essay`	Plain text, one paragraph per line, ending with a “References” heading and one source per line.
`references`	Optional, with `essay` only: sources as text, one per line, if they aren't at the end of the essay.
`fileBase64`	A .docx or .pptx file, base64-encoded.
`fileName`	Optional original file name, used to name the result (“Essay.docx” → “Essay cited.docx”).
`minCites`	At least this many citations per cited paragraph, 1–3. Default 1.
`maxCites`	At most this many citations per cited paragraph, 1–3. Default 1.
`targetMode`	`every` (default), `every_other` or `random`: which body paragraphs to consider.

Response

Field	Description
`citations_added`	Number of citations inserted.
`cited_text`	Essay requests: the full cited text, paragraphs separated by blank lines.
`cited_file_b64`	File requests: the cited file, base64-encoded. Formatting is unchanged apart from the citations.
`cited_name`, `file_kind`	File requests: suggested file name and `docx` / `pptx`.
`paragraphs`	Each paragraph: `id`, `text`, `eligible`, `cited_text` and `decision.citations` (`citation`, `reference_id`).
`references`	Sources found: `id`, `text`, `citation`.
`skipped_references`	Entries that couldn't be turned into (Author, Year).
`warnings`	Human-readable notes, e.g. partial coverage.

curl -s https://…/v1/cite \
  -H "Authorization: Bearer $CITE_ONLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"essay": "Your paragraph with a claim...\n\nReferences\nSmith, J. (2020) Title. London: Sage."}'

import base64, json, os, urllib.request

BASE = "https://…"
with open("Essay.docx", "rb") as f:
    body = {"fileBase64": base64.b64encode(f.read()).decode(), "fileName": "Essay.docx",
            "minCites": 1, "maxCites": 2, "targetMode": "random"}

req = urllib.request.Request(
    BASE + "/v1/cite", data=json.dumps(body).encode(), method="POST",
    headers={"Authorization": "Bearer " + os.environ["CITE_ONLY_KEY"],
             "Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=300) as resp:
    result = json.load(resp)

with open(result["cited_name"], "wb") as f:
    f.write(base64.b64decode(result["cited_file_b64"]))
print(result["citations_added"], "citations added")

import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://…";
const file = await readFile("Essay.docx");
const res = await fetch(`${BASE}/v1/cite`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CITE_ONLY_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ fileBase64: file.toString("base64"), fileName: "Essay.docx" }),
});
const result = await res.json();
if (!result.ok) throw new Error(result.error);
await writeFile(result.cited_name, Buffer.from(result.cited_file_b64, "base64"));
console.log(result.citations_added, "citations added");

Large documents can take a minute or more; use a generous client timeout.

POST/v1/parse

Same input as /v1/cite. Returns the paragraphs, detected references, skipped_references and warnings without adding citations, so you can check a document first. Doesn't count towards usage.

GET/v1/usage

Returns {"ok": true, "usage": {"docs": 12, "citations": 87}} for the key's account.

Errors

Every response has ok. When it's false, error says why.

Status	Meaning
400	Missing or unreadable input, or no usable References section.
401	`invalid_api_key`: the key is wrong or revoked.
413	Request larger than 12 MB.
429	Too many requests. Wait for the `Retry-After` seconds, then retry.
500 / 503	Temporary problem on our side. Retry after a short wait.

Limits and behaviour

Requests up to 12 MB. The first 400 paragraphs and 80 references are used.
Up to 60 cite requests per 10 minutes per account.
Existing in-text citations in body paragraphs are replaced by fresh ones.
Paragraphs with no fitting source are left without a citation. Titles, headings, introductions, summaries and conclusions never get new citations.