---
title: API Docs — Scholar Sidekick
description: Endpoints, parameters, examples, headers, caching and rate limits for Scholar Sidekick.
doc_version: "1.0"
last_updated: "2026-02-13"
---

# API Docs — Scholar Sidekick

> Quick reference for endpoints, parameters, examples, and headers.
> Last updated: 2026-02-13
> HTML version: https://scholar-sidekick.com/docs

## Base URL

```
https://scholar-sidekick.com
```

OpenAPI specs:
- Public: https://scholar-sidekick.com/openapi/openapi.yml
- RapidAPI: https://scholar-sidekick.com/openapi/rapidapi/openapi.yml
- JSON (via API): https://scholar-sidekick.com/api/openapi

## Endpoints

```
GET  /api/health
POST /api/format
POST /api/format/stream   (NDJSON)
POST /api/format-items
POST /api/export
```

---

## POST /api/format

Formats a list of identifiers (DOI, PMID, PMCID, ISBN, arXiv, WHO IRIS). Detects and normalises automatically.

### Request

```http
POST /api/format
Content-Type: application/json

{
  "text": "10.1038/nphys1170\nPMID: 34812345\n9780306406157",
  "style": "vancouver",
  "locale": "en-US",
  "output": "text",
  "footnotes": false
}
```

**Fields:**
- `text` (string) — One identifier per line, or free text containing identifiers. Mixed types OK.
- `style` (string, optional) — Citation style. Builtins: `vancouver`, `ama`, `apa`, `ieee`, `cse`. Also accepts any CSL style ID (e.g. `chicago-author-date`, `nature`, `lancet`). Defaults to `vancouver`.
- `locale` (string, optional) — CSL locale, e.g. `en-US`, `en-GB`. Used for CSL styles only.
- `output` (string, optional) — `"text"` or `"html"`. Defaults to `"text"`.
- `footnotes` (boolean, optional) — When `output=html`, render as footnotes. Default: `false`.

### Response

```http
200 OK
X-Scholar-Cache: ENABLED|BYPASS
X-Scholar-Formatter: builtin|csl
X-Scholar-Style: vancouver
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1736569200

{
  "ok": true,
  "items": [
    {
      "ok": true,
      "formatted": "Doe J, Smith A. Article title. Nature. 2008;452(7186):739-742.",
      "_source": { "id": "10.1038/nphys1170", "fetchedAt": "2026-01-01T00:00:00Z" }
    },
    { "ok": false, "error": "PMID not found" }
  ]
}
```

### cURL example

```bash
curl -sS -X POST "https://scholar-sidekick.com/api/format" \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}'
```

---

## POST /api/format/stream

Streaming NDJSON variant of `/api/format`. Emits one JSON object per line: `start` → `item` (one per identifier) → `done`.

Content-Type: `application/x-ndjson`

### cURL example

```bash
curl -N -sS -X POST "https://scholar-sidekick.com/api/format/stream" \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170\nPMID:34812345","style":"apa","output":"html"}'
```

---

## POST /api/format-items

Like `/api/format` but accepts already-resolved CSL JSON items — skips the resolution step.

### Request

```json
{
  "items": [ /* CSL-JSON bibliographic items */ ],
  "style": "apa",
  "output": "text"
}
```

---

## POST /api/export

Exports citations to a bibliography file format.

### Request

```http
POST /api/export
Content-Type: application/json

{
  "text": "10.1038/nphys1170\n9780306406157",
  "format": "ris",
  "style": "vancouver"
}
```

**Fields:**
- `text` (string) OR `items` (CSL-JSON[]) — Input identifiers or pre-resolved items.
- `format` (string, required) — Export format (see below).
- `style` (string, optional) — Citation style (used for `txt` format).

**Supported formats:**

| format | Description |
|---|---|
| `ris` | Research Information Systems (EndNote, Zotero, Mendeley) |
| `bibtex` | BibTeX (LaTeX, Overleaf, JabRef) |
| `csl-json` | Raw CSL-JSON structured metadata |
| `endnote-xml` | EndNote XML |
| `refworks` | RefWorks tagged format |
| `nbib` | MEDLINE/NBIB |
| `rdf` | Zotero RDF |
| `csv` | Comma-separated values |
| `txt` | Formatted plain-text citations |

Response: plain-text body in the requested format, with appropriate `Content-Type` and `Content-Disposition` headers.

### cURL example

```bash
curl -sS -X POST "https://scholar-sidekick.com/api/export" \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170\n9780306406157","format":"ris","style":"vancouver"}' \
  -o citations.ris
```

---

## GET /api/health

Liveness check. Returns `{ "status": "ok", "time": "<ISO timestamp>" }`.

---

## Headers & Rate Limits

- `X-Scholar-Cache`: `BYPASS` or `ENABLED`
- `X-Scholar-Formatter`: `builtin` or `csl`
- `X-Scholar-Style`: style actually applied
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` — sliding-window rate limit
- `Retry-After` — present on HTTP 429

Plan tiers: anonymous, free, pro, ultra, mega.

### Authentication

Include your API key via:
- `X-Scholar-API-Key: <key>` — direct API
- `X-RapidAPI-Key: <key>` — via RapidAPI

Anonymous access is available with lower rate limits.

---

## Error Format

```json
{ "ok": false, "code": "BAD_REQUEST", "error": "human-readable message" }
```

Common codes: `BAD_REQUEST` (400), `UNAUTHORIZED` (401), `RATE_LIMITED` (429), `MAINTENANCE` (503).

---

## Related

- MCP Server: https://scholar-sidekick.com/mcp
- MCP Server docs (markdown): https://scholar-sidekick.com/mcp.md
- Help & Limits: https://scholar-sidekick.com/help
- RapidAPI: https://rapidapi.com/scholar-sidekick-scholar-sidekick-api/api/scholar-sidekick
- API Terms: https://scholar-sidekick.com/legal/api-terms

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.