Machine-readable CiteLink

1 · What this is, and is not

CiteLink’s own pages read their data from a public PostgREST endpoint using a read-only key shipped in assets/js/data.js. Anyone who opened the developer tools already had it. This page documents those routes, because our development plan holds that “belgesiz bir iç API kamuya açık sayılmaz” — an undocumented internal API does not count as public.

That principle cuts both ways, and the second half matters more than the first:

• Everything listed here is documented, and we will not remove it without notice on this page.
• Anything reachable but not listed here is not an interface. It is an internal detail that happens to answer, and the correct response to finding one is for us to document it or close it — which is what we did in August 2026 when an archive table was found answering that no page read.

This page is generated by hand but not maintained by hand: every route named below is called on every commit by tools/check-routes.js, and a name that stops answering fails the build. That is the only reason to believe a page like this.

Two exceptions, added 19 September 2026, and they are named here rather than left for you to discover. That gate reads this page’s own data-route markup and calls each name against the PostgREST base in §2. The two routes at the foot of §5 — /api/extra/{id} and /api/view/{id} — are not PostgREST and carry no such marking, so they are documented here without being checked here. One of them writes, which is the other reason a build-time gate does not call it. Everything else on this page is checked.

2 · Base URL

The interface is PostgREST in front of PostgreSQL 17, on CiteLink’s own server in Berlin. One base URL, and nothing else to send:

Base URL   https://www.citelink.org/rest/v1/

There is no key any more, and that is a change from what this page said before. Until 18 September 2026 the API lived on Supabase, where every request carried an apikey header and an identical Authorization: Bearer header, and this page published that key. On 18 September 2026 the database moved to CiteLink’s own server and the API moved with it; PostgREST here runs with no token at all, so those headers are not needed and the published key no longer opens anything. §2 promised the key would not be removed without a note on this page, and this paragraph is that note. Requests that still send the old headers are answered normally — they are ignored, not rejected — so anything written against the old address needs only its host changed.

The key grants the anon role, which holds SELECT on the 24 relations in §4 and EXECUTE on the functions in §5. It holds no write privilege on anything you can read.

That sentence was false when this page was published on 3 September 2026, and an adversarial check of the page caught it rather than a reader. Three write privileges nobody had meant to grant were sitting under it: author_facets_mv carried INSERT, UPDATE, DELETE and TRUNCATE for this role, and catalog_sig_refresh() and catalog_sig_touch() were executable by everyone. None of the three could be used — each was stopped by a different accident, and not one of them by an intended grant — so the page stated the exception instead of the sentence, which was honest and worse than not needing to. They were revoked on 11 September 2026 (etl/v11/close-anon-writes.sql), and the sentence is true again. The read on author_facets_mv was deliberately kept; the three intake tables in §6 still take INSERT and refuse SELECT, which is what they are for; and the trigger on journals still fires, measured against the live trigger rather than assumed, because PostgreSQL checks EXECUTE when a trigger is created and not when it runs.

CORS is open. A preflight from an unrelated origin returns Access-Control-Allow-Origin: *, so a page on your own domain can call these routes directly. That is the difference between “usable from a notebook” and “usable from a web page”, and both work.

The API describes itself, as of 18 September 2026. GET /rest/v1/ returns PostgREST’s own OpenAPI document, and it follows the grants — it lists what anon may actually reach, not everything that exists. This page said the opposite until that date, and the reason was true while it lasted: Supabase answered that route with 401, “Only the service_role API key can be used for this endpoint”, so a machine-readable schema was not available at all. It is now. This page remains the one written for people — what a column means, what it does not mean, and which figures are derived — which a schema cannot tell you.

3 · Limits, measured

Each of these was measured against the live instance, not read off a plan.

One route still crosses the ceiling for a handful of names, and it used to do it for many. rpc/search_authors failed for nine of sixty-four test terms on an idle instance until 5 September 2026; it now fails for one. The cause was not the size of the table but a blind query planner: this table carries a row-security policy that grants everyone access to every row, and the presence of that policy is enough to stop the planner reading its own statistics for a substring match. It fell back to guessing from the length of what you typed. The guess was wrong in the expensive direction, and worst for the rarest names — ayvaz, which matches 58 people in the whole table, took over two minutes, and three-letter strings matching almost nothing failed too. Turkish surnames were hit hardest. Two changes fixed it: the statistics on the name index were made ten times finer, because at the old resolution a surname held by 0.57% of authors did not appear in the sample at all and was estimated at 737 rows against 42,101; and the search now plans with those statistics visible to it. What remains is a memory limit, not a planning one: a search matching tens of thousands of authors has to read tens of thousands of scattered pages, and this instance can cache only a fifth of the table, so the same query can take two seconds or seven depending on what happens to be in memory. That is listed in §5 rather than left out, because a list that quietly omits the flaky route is worse than one that names it.

4 · Tables and views

All 24 relations the anonymous key can read, each fetched to confirm it answers. Call them as GET /rest/v1/{name}?select=*&limit=1 and filter with PostgREST’s operators.

Ten of them are read directly by this site’s pages. The other fourteen answer and no page fetches them by name; they are listed anyway, because under the principle in §1 the alternative to documenting a reachable route is closing it.

The last five are our view-model, not a data product. The four materialized views and catalog_sig_cache exist to make particular pages of ours fast. Their shape follows our layout and will change when the layout does. Read them if they help; do not build on their columns.

5 · Functions

Called as POST /rest/v1/rpc/{name} with a JSON body of named arguments. Every argument has a default, so {} is a valid body for all of them. These are the 21 that serve data; a further 31 executable names in the same schema belong to the pg_trgm extension and are Postgres, not CiteLink.

A worked call, and its answer:

curl -s https://www.citelink.org/rest/v1/rpc/catalog_sig \
  -H "Content-Type: application/json" -d '{}'

{
  "n": 58392,
  "scopus": 30244,
  "wos": 22869,
  "doaj": 23227,
  "pubmed": 15215,
  "pmc": 4190,
  "clv": 0
}

Two further functions in the same schema write to a cache table and are not part of this interface. They are not listed because listing a write route on a documentation page is an invitation, and because they should not be reachable with this key at all; withdrawing that is an open item on our side.

Two routes that are not PostgREST — /api/extra/{id} and /api/view/{id}

Everything above this line is PostgREST under /rest/v1/. These two are answered by a small service of our own, on the same origin as the base URL in §2, and it went up on 19 September 2026. It exists because an article page needs two things our own tables do not hold: an author list split into given and family names with ORCID iDs, and the volume, issue and pages an article appeared on. They are given the same three columns as the table above, because they are the same kind of thing — a name you call, what you send it, and what comes back.

The first route is a cache over Crossref and OpenAlex, and it tells you so in the answer. On a miss our server looks the article up at Crossref by its DOI and at OpenAlex by its work id, stores what comes back and returns it; on a hit nothing leaves the building. source says which of the two the record in front of you came from and fetched_at when it was taken, so a field that looks wrong can be traced to whoever published it and to the day we read it. A stored copy is treated as good for 90 days and fetched again after that, which makes fetched_at readable as an age but still not as an expiry: nothing is deleted at 90 days, the next request for that article simply goes out to the source again. Whether 90 is the right number is an open decision on our side and not a promise to you — if you need to know that a field is current, re-read it rather than trusting the stamp.

views is a count of page opens, and it is the whole of what this site counts. One integer per article, raised by the second route and never by the first — a GET of /api/extra/{id} reads the number and changes nothing, so you can poll it without moving it. Behind it there is no IP address, no cookie, no user agent and no per-visitor record anywhere; the only other thing stored beside the number is the moment that article was last opened by anybody, overwritten each time. The row keys on the article, and there is nothing about a visitor anywhere on this site for it to be joined to. The article page calls the write route once per article per browsing session rather than on every view, so the number counts openings rather than people, and a crawler is counted exactly like a reader: treat it as a floor on attention, not as an audience figure. The article page prints it under the authors. The privacy notice says the same thing from the reader’s side, including what is deliberately not attached to it.

Two things follow for anyone building on it. The author names here are split into given and family, which the articles table’s own author string is not: that string is written by etl/articles-a.sql from the first five authorships only, as display names with no given/family boundary, while n_authors beside it carries the real count — so a row saying 23 authors and listing five is truncation, not disagreement. That string stays the fallback, and it is the one you get when this route answers with an empty authors. And neither route is covered by the commit-time gate described in §1: they are documented, but a reader who finds one unresponsive is telling us something our own build is not.

6 · Endpoints that refuse reads

Three tables accept POST and refuse GET. That is deliberate: the forms on this site work, and nobody — including anyone holding the key above — can read what somebody else submitted.

An applicant reads their own record back through rpc/get_application_status, which requires the reference and the e-mail address together.

7 · Files at the site root

Four static files, no key needed.

About the errata feed. It carries 58 of the 66 entries in the record: eight of the oldest carry no date in their own heading, and rather than date them from the repository’s history — which would assert dates the record itself contradicts — they are left out and the omission is stated in the file. Entries carry a title, a date and a first paragraph, and they are in Turkish, because the record is. Every entry links to the known-defects section rather than to itself; the errata is not rendered as HTML yet, so there is no per-entry page to link to. Each entry is written to stand on its own until there is.

Content types are the host’s business, not ours. Both XML files are served with whatever the static host maps .xml to, which is text/xml by default. Every feed reader accepts that. application/atom+xml and application/opensearchdescription+xml would be more correct and are a one-line host configuration; we do not currently guarantee them. The extension is .xml rather than .atom for exactly this reason — a default host serves an unknown extension as a download.

8 · Which licence covers what

Four different regimes reach you through one endpoint, and the boundary runs down the middle of the tables in §4 — since 6 September 2026 down the middle of a single row of journals, and since 19 September 2026 down the middle of a single column of articles. This paragraph said “three” until that date, when the abstract text stopped being covered by the row it used to sit in. The full text is here.

The methodology prose behind those metrics — including the errata feed — is not covered by either, which is why the feed carries no licence element. Ask if you want to redistribute it.

Where each index flag comes from, and what its source says

Twelve indexes, and they do not arrive under one regime. This table exists because until 7 September 2026 this page said the whole journals table was CC0 from OpenAlex, and that stopped being true as flags from other operators were added to it. Each row names the endpoint we actually read — which is not always the index’s own site — and what that operator publishes about reuse, quoted where it is short enough to quote. Where we could not find a statement, the row says so instead of guessing.

What we store, and what the endpoint will actually give you

Until 7 September 2026 this section said “we store whether a journal is in an index, and never the index”. That was a description of a table, offered as if it were a description of the service, and as a description of the service it was false. The correction matters more than the wording, so here it is plainly:

• The flags are filterable on the public route. GET /journals?select=issn_l&in_scopus=is.true answers with the anon key printed in §2, and the response header carries the exact total. Paged at the 1,000-row cap documented in §4, any of these lists comes out in tens of requests.
• The bulk snapshot ships them too. assets/data/catalog.json is one file carrying every flag for all 63,664 records, and the site downloads it on a first visit.
• Four of the flags are more than one value. scopus_source_id on 30,239 journals; wos_editions, wos_categories and wos_abbrev; ebsco_dbs; kci_tier.

So a reader who wants a reconstruction of somebody’s index can get close to one from this API, and any restriction in the rows above reaches that reader as much as it reaches us. Whether the access itself should change is a separate question and an open one; what is not open is whether this page gets to describe it accurately.

Acknowledgements

Courtesy of the U.S. National Library of Medicine (PubMed, PubMed Central). Journal accreditation data from 한국연구재단 — the National Research Foundation of Korea, Korea Citation Index. ERIH PLUS data from the deposit by ERIH-PLUS, HK-dir. Bibliographic records from OpenAlex. DOI deposit metadata from Crossref. None of these organisations has reviewed, approved or endorsed CiteLink, and nothing here implies that they have.

9 · What is not built

Named here so nobody has to discover it by trying.

If one of these is the thing standing between you and using this data, say so. The order we build them in should be decided by someone who needs them, not by us guessing.