# cito API

Semantic + keyword search over ~148M academic papers (Semantic Scholar corpus),
self-hosted to escape the public S2 API's 1 request/second limit.

Base URL: https://api.cito.fim.ai
OpenAPI JSON: https://api.cito.fim.ai/openapi.json
Interactive reference (Swagger UI): https://api.cito.fim.ai/docs

## Authentication

Optional for search. Pass an API key either way:

    Authorization: Bearer sk_...
    X-API-Key: sk_...

Create keys at https://cito.fim.ai/account/keys (GitHub sign-in).
Endpoints under /me always require a key.

## Rate limits

- Anonymous (no key): 15 requests/min per IP.
- With an API key: the key's own per-minute limit; keys created without an
  explicit limit follow the server default (currently 100/min). Your account
  page shows the enforced limit per key.
- 429 with body {"detail": "Rate limit exceeded."} when over.

## MCP

The API is also an MCP server (streamable HTTP) at https://api.cito.fim.ai/mcp, exposing the
tools search_papers and get_paper. Add it to Claude Code:

    claude mcp add --transport http cito https://api.cito.fim.ai/mcp

Optional, for the per-key tier instead of the anonymous per-IP limit:

    claude mcp add --transport http cito https://api.cito.fim.ai/mcp \
      --header "Authorization: Bearer sk_..."

Any MCP client that speaks streamable HTTP works (Claude Desktop, Cursor, ...).
MCP calls share the same rate tiers and metering as /search.

## GET /search

Query parameters:
- q (string, required): natural-language or keyword query.
- mode (string, default "hybrid"): hybrid | semantic | keyword.
- limit (int, default 20, max 100): max results.
- enrich (bool, default true): attach title/abstract/authors from the local metadata store.
- published_before (string, optional, YYYY-MM-DD): leak-safe date gate. Only papers
  published strictly before this date. Filtering happens before the pool is cut to
  limit, so future papers never occupy result slots. Papers with only a year are kept
  iff the year is strictly earlier; same-year and undated papers are excluded.
- include_imprecise (bool, default false): with published_before, also keep papers
  whose date is too coarse to prove precedence (same-year year-granularity, undated).

Ordering is deterministic: same query + same corpus snapshot replays identically
(score ties broken by CorpusID).

Response:

    {
      "query": "attention is all you need",
      "mode": "hybrid",
      "took_ms": 257,
      "hits": [
        {
          "id": "13756489",              // Semantic Scholar CorpusID (string)
          "title": "Attention is All you Need",
          "abstract": "...",
          "authors": ["Ashish Vaswani", "..."],
          "year": 2017,
          "publication_date": "2017-06-12",  // YYYY-MM-DD, or "YYYY" when only the year is known, or null
          "date_granularity": "day",         // "day" | "year" | null
          "venue": "NeurIPS",
          "doi": "...",                   // may be null (~40% of the corpus)
          "url": "https://www.semanticscholar.org/p/13756489",
          "pdf_url": "...",               // open-access PDF when available (via OpenAlex), else null
          "cites": 100000,                // citation count, may be null
          "score": 0.97
        }
      ],
      "corpus_release": "2026-06-24",     // snapshot the candidates came from
      "attribution": "Data from Semantic Scholar"
    }

Errors: 401 (invalid key), 422 (malformed published_before), 429 (rate limit),
503 (search backend temporarily down).

## GET /paper/{corpusid}

One paper's metadata by CorpusID. Same fields as a hit minus "score".
404 if the CorpusID is unknown.

## GET /status

Index and feature status: auth_required, rerank_enabled,
corpus_release (YYYY-MM-DD snapshot date), index counts.

## GET /me and GET /me/usage

Your account, keys, and recent usage. Require an API key.

## Examples

    curl "https://api.cito.fim.ai/search?q=contrastive+learning&limit=5"

    curl -H "Authorization: Bearer sk_..." \
      "https://api.cito.fim.ai/search?q=diffusion+models&mode=semantic"

Python:

    import requests
    r = requests.get(
        "https://api.cito.fim.ai/search",
        params={"q": "attention is all you need", "limit": 5},
        headers={"Authorization": "Bearer sk_..."},  # optional
        timeout=30,
    )
    for hit in r.json()["hits"]:
        print(hit["id"], hit["title"])

## Notes

- IDs are Semantic Scholar CorpusIDs; hit.url resolves to the paper's S2 page.
- Data: Semantic Scholar corpus + OpenAlex open-access enrichment. Synced with
  upstream releases roughly every two weeks; open-access links for recent papers
  re-checked quarterly. corpus_release tells you the snapshot behind a response.
- Licensing: Semantic Scholar (ODC-BY / Apache-2.0), OpenAlex (CC0). Keep the
  attribution string when republishing results.
- Human-readable docs: https://cito.fim.ai/docs (API reference: /docs/api)