Skills › Scientific Agent Skills › citation-management › api_contracts.md
api_contracts.md
55 lines · skills/citation-management/references/api_contracts.md at 5f2bc03
1# Citation API contracts
3Reviewed 2026-09-30 against official documentation. The bundled clients use
4read-only requests; no registration, account mutation, or full-text bulk
5harvesting is part of this skill.
7| Service | Request and authentication | Response and paging |
8|---|---|---|
9| OpenAlex | `GET https://api.openalex.org/works`; `search`, optional `filter` and `sort=cited_by_count:desc`; optional `Authorization: Bearer` from `OPENALEX_API_KEY`. Keyless casual use is supported. `mailto` is a contact identifier, not a quota upgrade. | `results[]` and `meta.next_cursor`. Start `cursor=*`, follow returned cursors; supported `per_page` maximum is 100 (`per-page` is accepted). Stop at the requested limit or terminal cursor. Any failed page aborts the export. |
10| PubMed search | `GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi`; `db=pubmed`, `term`, `retmax`, `retmode=json`, `tool`, optional `email` and `api_key`. | `esearchresult.count` and `idlist`. Only the first 10,000 matches are accessible; `retstart` cannot bypass this ceiling. The bundled command caps the request and reports that limit. |
11| PubMed records | `GET .../efetch.fcgi`; `db=pubmed`, comma-separated `id`, `retmode=xml`, same caller parameters. | `PubmedArticleSet/PubmedArticle`; the client batches 200 IDs and verifies that all requested IDs were parsed. PubmedBookArticle is not implemented and produces an explicit incomplete-retrieval failure. |
12| PMC conversion | `GET https://pmc.ncbi.nlm.nih.gov/tools/idconv/api/v1/articles/`; `ids`, `format=json`, `tool`, optional `email`. No NCBI API key is sent here. | `records[]` maps PMID/PMCID/DOI only for PMC-held articles. `pmid` may be numeric. This helper sends one ID; the service accepts 200 same-type IDs per request, without paging. The ID converter remains distinct from the retired OA download service. |
13| Crossref | `GET https://api.crossref.org/works/{encoded-doi}`; public metadata needs no key. | Singleton JSON `message`; author/title/container/date fields can be incomplete. Extract the publication date, not `created`, `deposited`, or `indexed`. No pagination. Public single-record limit is 5/s; list requests are 1/s. Polite equivalents are 10/s and 3/s; respect response headers. |
14| DataCite | `GET https://api.datacite.org/dois/{encoded-doi}`; public findable records need no credentials. | Singleton `data.id` and `data.attributes`, not Crossref's schema. Used by the DOI validator after Crossref 404. The general metadata extractor currently has no DataCite mapper; use DOI-to-BibTeX conversion instead. |
15| DOI negotiation | `GET https://doi.org/{encoded-doi}` with `Accept: application/x-bibtex`; redirects are followed to the registration agency. No key. | One BibTeX record; the converter rejects non-BibTeX responses and generates its shared citation key. No pagination. Supports participating agencies beyond Crossref. |
16| DOI resolver validation | Same DOI URL, GET without following redirects after both Crossref and DataCite lack a record. | A redirect with a Location confirms registration; 404 indicates missing DOI. Timeouts, throttling, malformed responses, or other statuses remain inconclusive warnings, never a successful verification. Publisher accessibility and bibliographic identity still need manual review. |
17| arXiv | `GET https://export.arxiv.org/api/query`; `id_list`, `max_results=1`; no key. One connection, at most one request per three seconds across all workers. | Atom feed with optional DOI/journal reference. Reject API error entries; preserve requested `vN` versions. Single-ID lookup has no paging. A DOI alone does not prove journal publication. |
19PubMed's ESummary (`esummary.fcgi`, `retmode=json`) returns `result.uids` and
20UID-keyed records. ELink (`elink.fcgi`, `cmd=neighbor`) returns link sets;
21`pubmed_pmc` requires target `db=pmc`, whereas related/cited-in PubMed links use
22`db=pubmed`. EInfo (`einfo.fcgi`) describes database fields and links. These
23manual alternatives in the PubMed reference are illustrative, not used by the
24bundled client. NCBI E-utilities limits are 3 requests/s without a key or 10/s
25with a key; account for other processes sharing the same IP/key.
27Google Scholar has no supported bulk API. `scholarly.search_pubs` is an unofficial
28iterator with `year_low`/`year_high`; `--sort-by citations` only sorts the returned
29sample. Google caps displayed results at 1,000 per query. Follow robots.txt and
30stop on blocking. Proxy support is optional and was not exercised.
Citation API contracts
Reviewed 2026-09-30 against official documentation. The bundled clients use read-only requests; no registration, account mutation, or full-text bulk harvesting is part of this skill.
| Service | Request and authentication | Response and paging |
|---|---|---|
| OpenAlex | GET https://api.openalex.org/works; search, optional filter and sort=cited_by_count:desc; optional Authorization: Bearer from OPENALEX_API_KEY. Keyless casual use is supported. mailto is a contact identifier, not a quota upgrade. | results[] and meta.next_cursor. Start cursor=*, follow returned cursors; supported per_page maximum is 100 (per-page is accepted). Stop at the requested limit or terminal cursor. Any failed page aborts the export. |
| PubMed search | GET https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi; db=pubmed, term, retmax, retmode=json, tool, optional email and api_key. | esearchresult.count and idlist. Only the first 10,000 matches are accessible; retstart cannot bypass this ceiling. The bundled command caps the request and reports that limit. |
| PubMed records | GET .../efetch.fcgi; db=pubmed, comma-separated id, retmode=xml, same caller parameters. | PubmedArticleSet/PubmedArticle; the client batches 200 IDs and verifies that all requested IDs were parsed. PubmedBookArticle is not implemented and produces an explicit incomplete-retrieval failure. |
| PMC conversion | GET https://pmc.ncbi.nlm.nih.gov/tools/idconv/api/v1/articles/; ids, format=json, tool, optional email. No NCBI API key is sent here. | records[] maps PMID/PMCID/DOI only for PMC-held articles. pmid may be numeric. This helper sends one ID; the service accepts 200 same-type IDs per request, without paging. The ID converter remains distinct from the retired OA download service. |
| Crossref | GET https://api.crossref.org/works/{encoded-doi}; public metadata needs no key. | Singleton JSON message; author/title/container/date fields can be incomplete. Extract the publication date, not created, deposited, or indexed. No pagination. Public single-record limit is 5/s; list requests are 1/s. Polite equivalents are 10/s and 3/s; respect response headers. |
| DataCite | GET https://api.datacite.org/dois/{encoded-doi}; public findable records need no credentials. | Singleton data.id and data.attributes, not Crossref's schema. Used by the DOI validator after Crossref 404. The general metadata extractor currently has no DataCite mapper; use DOI-to-BibTeX conversion instead. |
| DOI negotiation | GET https://doi.org/{encoded-doi} with Accept: application/x-bibtex; redirects are followed to the registration agency. No key. | One BibTeX record; the converter rejects non-BibTeX responses and generates its shared citation key. No pagination. Supports participating agencies beyond Crossref. |
| DOI resolver validation | Same DOI URL, GET without following redirects after both Crossref and DataCite lack a record. | A redirect with a Location confirms registration; 404 indicates missing DOI. Timeouts, throttling, malformed responses, or other statuses remain inconclusive warnings, never a successful verification. Publisher accessibility and bibliographic identity still need manual review. |
| arXiv | GET https://export.arxiv.org/api/query; id_list, max_results=1; no key. One connection, at most one request per three seconds across all workers. | Atom feed with optional DOI/journal reference. Reject API error entries; preserve requested vN versions. Single-ID lookup has no paging. A DOI alone does not prove journal publication. |
PubMed's ESummary (esummary.fcgi, retmode=json) returns result.uids and UID-keyed records. ELink (elink.fcgi, cmd=neighbor) returns link sets; pubmed_pmc requires target db=pmc, whereas related/cited-in PubMed links use db=pubmed. EInfo (einfo.fcgi) describes database fields and links. These manual alternatives in the PubMed reference are illustrative, not used by the bundled client. NCBI E-utilities limits are 3 requests/s without a key or 10/s with a key; account for other processes sharing the same IP/key.
Google Scholar has no supported bulk API. scholarly.search_pubs is an unofficial iterator with year_low/year_high; --sort-by citations only sorts the returned sample. Google caps displayed results at 1,000 per query. Follow robots.txt and stop on blocking. Proxy support is optional and was not exercised.
32## Verification evidence and limits
34Credential-free read-only smoke checks on 2026-09-30 returned HTTP 200 and the
35expected parsed shapes for PMC conversion (PMC7611378 returned numeric PMID
3627102758), ESearch/EFetch (PMID 34265844), Crossref and DOI BibTeX negotiation
37(10.1038/s41586-021-03819-2), DataCite (10.14454/qdd3-ps68), arXiv
38(1706.03762 returned the v7 Atom entry), and OpenAlex (one work plus cursor).
39These checks confirm those responses at that time, not uptime or bulk coverage.
41Regression tests mock pagination failures, missing PubMed batches, arXiv error
42feeds/pacing, DOI transport failures, numeric PMC IDs, and CLI input contracts.
43Authenticated quota handling, Scholar/proxies, arbitrary publisher-page metadata,
44Zotero exports, and all illustrative search queries were not exercised live.
Verification evidence and limits
Credential-free read-only smoke checks on 2026-09-30 returned HTTP 200 and the expected parsed shapes for PMC conversion (PMC7611378 returned numeric PMID 27102758), ESearch/EFetch (PMID 34265844), Crossref and DOI BibTeX negotiation (10.1038/s41586-021-03819-2), DataCite (10.14454/qdd3-ps68), arXiv (1706.03762 returned the v7 Atom entry), and OpenAlex (one work plus cursor). These checks confirm those responses at that time, not uptime or bulk coverage.
Regression tests mock pagination failures, missing PubMed batches, arXiv error feeds/pacing, DOI transport failures, numeric PMC IDs, and CLI input contracts. Authenticated quota handling, Scholar/proxies, arbitrary publisher-page metadata, Zotero exports, and all illustrative search queries were not exercised live.
Raw lines 32 to 4546## Official sources
48- [OpenAlex authentication](https://help.openalex.org/api/authentication/), [pagination](https://help.openalex.org/api/paging/), and [search](https://help.openalex.org/api/searching/).
49- [NCBI E-utilities reference](https://www.ncbi.nlm.nih.gov/books/NBK25499/), [NLM API parameter guide](https://www.nlm.nih.gov/dataguide/eutilities/utilities.html), and [PubMed result-window change](https://ncbiinsights.ncbi.nlm.nih.gov/2021/10/05/updated-pubmed-api/).
50- [PMC ID Converter API](https://pmc.ncbi.nlm.nih.gov/tools/id-converter-api/).
51- [Crossref REST API](https://github.com/CrossRef/rest-api-doc), [current rate-limit distinction](https://community.crossref.org/t/refining-rest-api-limits-for-improved-stability-and-reliability/16137), and [content negotiation](https://www.crossref.org/documentation/retrieve-metadata/content-negotiation/).
52- [DataCite public API](https://support.datacite.org/docs/rest-api) and [singleton schema](https://support.datacite.org/docs/api-get-doi).
53- [arXiv API manual](https://info.arxiv.org/help/api/user-manual.html) and [usage limits](https://info.arxiv.org/help/api/tou.html).
54- [Google Scholar Help](https://scholar.google.com/intl/en/scholar/help.html) and [scholarly API](https://scholarly.readthedocs.io/en/stable/scholarly_user.html).
55- [Pyzotero export types and pagination](https://pyzotero.readthedocs.io/en/latest/).
Official sources
- OpenAlex authentication, pagination, and search.
- NCBI E-utilities reference, NLM API parameter guide, and PubMed result-window change.
- PMC ID Converter API.
- Crossref REST API, current rate-limit distinction, and content negotiation.
- DataCite public API and singleton schema.
- arXiv API manual and usage limits.
- Google Scholar Help and scholarly API.
- Pyzotero export types and pagination.