# AIConfPaper API

> Semantic search over millions of ACCEPTED AI-conference papers (NeurIPS, ICML, ICLR, CVPR, ECCV, ICCV, ACL, EMNLP, NAACL, COLING, CoRL, ICRA, IROS, RSS, AAAI, IJCAI, AISTATS, UAI; 2015-2026). Search papers by meaning, find similar papers, get citation counts, get LaTeX-source and code links, and build collections (create one and add papers) that save to your account. This is a research-workflow API: an agent can go from a query to a saved collection to downloaded LaTeX/code in a few calls. Every endpoint requires a free API key: send `Authorization: Bearer acp_...`. Create a key at https://aiconfpaper.com/account.

Base URL: https://aiconfpaper.com

## Instructions for LLM Agents
- To learn the whole API in ONE fetch: read https://aiconfpaper.com/developers (human + agent guide) or `curl -fsSL https://aiconfpaper.com/openapi.json`. Do NOT scrape the HTML search UI.
- ALWAYS start with `GET /api/v1/search?q=...`. `q` is free text: keywords, a sentence, or an entire abstract — results are ranked by semantic (embedding) similarity, not keyword matching.
- Carry the `paper_id` from search results into `/papers/{id}` and `/papers/{id}/similar`.
- To build a saved collection: `POST /api/v1/collections` with `{"name":"..."}` to create it, then `POST /api/v1/collections/{id}/papers` with `{"paper_ids":[...]}` (ids from search). It saves to the key owner's account and appears in the website UI. Idempotent; caps: 50 folders, 1000 papers/folder. Unknown ids are counted in `skipped`, not added.
- To save a SPECIFIC paper you know by title: search the exact title (`GET /api/v1/search?q=<the title>&limit=3`), confirm the top result's `title` matches, then add its `paper_id` to your collection.
- To add an arXiv paper that is NOT in the accepted-papers index: first `POST /api/v1/papers/external` with `{"arxiv":"<id or arxiv.org URL>"}` — it resolves the paper (official arXiv metadata) and returns `paper_id` `arxiv:<id>`, which you can then add to a collection like any other id.
- Need many full records? `GET /api/v1/papers?ids=<comma-separated>` returns up to 50 in ONE call — use it instead of looping GET /papers/{id}.
- Collection editing: remove papers with `DELETE /api/v1/collections/{id}/papers` `{"paper_ids":[...]}` (idempotent; no delete-and-rebuild), rename/describe with `PATCH /api/v1/collections/{id}` `{"name":"...","description":"..."}`.
- To hand a reading list to a collaborator: `POST /api/v1/collections/{id}/share` `{"public":true}` returns a read-only URL (they can view/follow/copy on the website; only you can edit).
- To CO-EDIT with a collaborator: `POST /api/v1/collections/{id}/collaborate` `{"enabled":true}` returns an editable invite URL — a logged-in user who opens it joins as an editor. The collection then appears in THEIR `GET /api/v1/collections` (`owned: false`) and they can read/add/remove/export it with their own API key. Manage members with `GET /api/v1/collections/{id}/members` and `DELETE /api/v1/collections/{id}/members/{user_id}`.
- For a bibliography: `GET /api/v1/collections/{id}/export?format=bibtex` returns the WHOLE collection as one references.bib (entries without stored BibTeX are synthesized). `format=csv|json` gives tabular rows.
- Rate limits: 120 requests per rolling minute per client. Every /api/v1 response carries `X-RateLimit-Remaining`; a 429 carries `Retry-After` (seconds) — honor it instead of guessing a backoff. POST /papers/external shares a global arXiv queue (503 = retry in a few seconds).
- For a paper's LaTeX/TeX source, read `links.arxiv_src` from `GET /api/v1/papers/{id}` (it is always null in search results). It may be null; retry once, but some papers have no source link at all (even if an arXiv version exists elsewhere), so fall back to another paper rather than retrying forever. The bundle is a gzip tar (`arXiv-<id>vN.tar.gz`); `tar xzf` extracts it.
- `links.code` is present for roughly a third to half of papers and is best-effort: before trusting a repo, sanity-check its README/title against the paper title (a link can occasionally point to a project page or a different project).
- Errors are RFC 9457 `application/problem+json` with a `detail` recovery hint.
- Auth: every endpoint requires a free API key. Send `Authorization: Bearer acp_...` on every request. Create a key (sign up, then Account) at https://aiconfpaper.com/account. Keys are per-member; the collections endpoints return that member's own saved papers.

## Endpoints
- [Search papers](https://aiconfpaper.com/developers): `GET /api/v1/search` — rank papers by semantic similarity to a query (filters: venue, year, sort).
- [Paper detail](https://aiconfpaper.com/developers): `GET /api/v1/papers/{id}` — full abstract, BibTeX, live citation count, and `links.arxiv_src` (TeX).
- [Similar papers](https://aiconfpaper.com/developers): `GET /api/v1/papers/{id}/similar` — nearest neighbors of a paper in embedding space (filters: venue, year).
- [Facets](https://aiconfpaper.com/developers): `GET /api/v1/facets` — valid `venue`/`tier` filter values and the year range.
- [Create collection](https://aiconfpaper.com/developers): `POST /api/v1/collections` — create a collection (`{"name":"..."}`); returns its id (API key required).
- [Add papers](https://aiconfpaper.com/developers): `POST /api/v1/collections/{id}/papers` — add paper ids (`{"paper_ids":[...]}`, from search or `arxiv:<id>` from /papers/external) to a collection; idempotent (API key required).
- [Register arXiv paper](https://aiconfpaper.com/developers): `POST /api/v1/papers/external` — register an arXiv paper not in the index (`{"arxiv":"2107.02192"}`); returns `paper_id` `arxiv:<id>` to add to collections (API key required).
- [Batch paper detail](https://aiconfpaper.com/developers): `GET /api/v1/papers?ids=...` — full records for up to 50 comma-separated ids in one call.
- [Remove papers](https://aiconfpaper.com/developers): `DELETE /api/v1/collections/{id}/papers` — remove paper ids (`{"paper_ids":[...]}`); idempotent (API key required).
- [Edit collection](https://aiconfpaper.com/developers): `PATCH /api/v1/collections/{id}` — rename and/or set description (`{"name":"...","description":"..."}`) (API key required).
- [Share collection](https://aiconfpaper.com/developers): `POST /api/v1/collections/{id}/share` — toggle the public read-only link (`{"public":true}`); returns the URL (API key required).
- [Collaborate](https://aiconfpaper.com/developers): `POST /api/v1/collections/{id}/collaborate` — toggle an EDITABLE invite link (`{"enabled":true}`); returns the URL (API key required).
- [Members](https://aiconfpaper.com/developers): `GET /api/v1/collections/{id}/members` + `DELETE /api/v1/collections/{id}/members/{user_id}` — list / remove collaborators (API key required).
- [Export collection](https://aiconfpaper.com/developers): `GET /api/v1/collections/{id}/export?format=bibtex|csv|json` — the whole collection as one references.bib or table (API key required).
- [Delete collection](https://aiconfpaper.com/developers): `DELETE /api/v1/collections/{id}` — delete a collection you created, to clean up (API key required).
- [My collections](https://aiconfpaper.com/developers): `GET /api/v1/collections` — list your collections, own and shared-with-you (`owned` flag) (API key required).
- [Collection papers](https://aiconfpaper.com/developers): `GET /api/v1/collections/{id}` — all papers in one of your collections (API key required).

## MCP server
- Streamable HTTP endpoint: `POST https://aiconfpaper.com/mcp` (stateless, single JSON response per call; no SSE stream).
- Read-only tools mirroring the endpoints above: `search_papers`, `get_paper`, `batch_get_papers`, `find_similar_papers`, `list_facets` — same data, same semantics. Collection create/add/share/export stay on the REST API.
- Auth: the SAME free API key, sent as an `Authorization: Bearer acp_...` header on every MCP request. Tool discovery (initialize, tools/list) works without a key; tool calls without a valid key return an in-band error with recovery instructions.
- Claude Code setup: `claude mcp add --transport http aiconfpaper https://aiconfpaper.com/mcp --header "Authorization: Bearer $AICONFPAPER_API_KEY"` — or in `.mcp.json`: `{"mcpServers":{"aiconfpaper":{"type":"http","url":"https://aiconfpaper.com/mcp","headers":{"Authorization":"Bearer ${AICONFPAPER_API_KEY}"}}}}`
- Rate limit: same 120 requests/min budget as /api/v1.

## Specs
- Human + agent guide: https://aiconfpaper.com/developers
- OpenAPI 3.1 (machine contract): /openapi.json
- MCP endpoint (Streamable HTTP): /mcp