Literfy Open API v1 Guide

Literfy Open API v1 exposes authenticated endpoints for credit balance lookup and multi-source paper search, suitable for research automation, review workflows, and external integrations.

Get an API Key

Sign in to Literfy and open your profile page at https://literfy.ai/settings/profile
Click API Keys in the left sidebar
Click Add to create a new key
Enter a name for the key, for example My Research App
Copy the generated key immediately

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer <your_api_key>

Rate Limit

Item	Value
Request rate	1 request per second for each API key

Credit Cost

Endpoint	Credits consumed
`GET /api/open/v1/balance`	0
`GET /api/open/v1/search`	2 credits per selected source

Endpoints

Balance Query

GET /api/open/v1/balance

Return the remaining credit balance for the account bound to the API key.

Response Format

{
  "remainingCredits": 128
}

Examples

cURL

curl "https://literfy.ai/api/open/v1/balance" \
  -H "Authorization: Bearer sk_your_api_key"

JavaScript

const response = await fetch('https://literfy.ai/api/open/v1/balance', {
  headers: {
    Authorization: 'Bearer sk_your_api_key',
  },
});

const data = await response.json();
console.log(data.remainingCredits);

Python

import requests

response = requests.get(
    "https://literfy.ai/api/open/v1/balance",
    headers={"Authorization": "Bearer sk_your_api_key"},
)

data = response.json()
print(data["remainingCredits"])

Paper Search

GET /api/open/v1/search

Search papers across multiple academic databases.

Query Parameters

Parameter	Type	Required	Default	Description
`topic`	string	Yes	-	Search keyword, up to 300 characters
`google-scholar`	number	No	-	Number of papers from Google Scholar, from 1 to 60
`pubmed`	number	No	-	Number of papers from PubMed, from 1 to 100
`wanfang`	number	No	-	Number of papers from Wanfang, from 1 to 100

Notes:

At least one source parameter is required.
Each source returns up to 100 papers per request.
If topic exceeds 300 characters, the API returns INVALID_PARAMS.
When you query multiple sources, Literfy deduplicates results by title automatically.

Response Format

The endpoint returns a Server-Sent Events (SSE) stream.

Event Types

paper: a single paper result

{
  "paperId": "abc123",
  "source": "google-scholar | pubmed | wanfang",
  "title": "Paper title",
  "abstract": "Paper abstract...",
  "authors": [{ "name": "Author Name" }],
  "year": 2024,
  "venue": "Conference or journal",
  "url": "https://...",
  "doi": "10.1234/...",
  "citationCount": 100,
  "influentialCitationCount": 10,
  "volume": "12",
  "issue": "3",
  "pages": "123-456",
  "isOpenAccess": true,
  "pdfUrl": "https://...",
  "resourceType": "Periodical",
  "bibtex": "@article{...}",
  "venueName": "Full venue name",
  "venueType": "conference | journal",
  "venueCCFRank": "A/B/C",
  "venueQuartile": "Q1/Q2/Q3/Q4",
  "venueIf": 8.6,
  "venueCASZone": 1,
  "venueCnTags": ["JCR Q1", "CAS Zone 1"]
}

Available fields vary by source, so not every paper includes every field.

done: search completed

{
  "total": 50
}

error: request failed

{
  "error": "Error message"
}

You can use any of the examples below to validate the stream and handle paper, done, and error events on the client side.

Search Examples

cURL

curl -N "https://literfy.ai/api/open/v1/search?topic=large%20language%20models&google-scholar=50&pubmed=30&wanfang=20" \
  -H "Authorization: Bearer sk_your_api_key"

JavaScript

const response = await fetch(
  'https://literfy.ai/api/open/v1/search?topic=transformer+architecture&google-scholar=50&pubmed=30',
  {
    headers: {
      Authorization: 'Bearer sk_your_api_key',
    },
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const text = decoder.decode(value);
  const lines = text.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data);
    }
  }
}

Python

import requests

url = "https://literfy.ai/api/open/v1/search"
params = {
    "topic": "deep learning",
    "google-scholar": 50,
    "pubmed": 30,
    "wanfang": 20
}
headers = {
    "Authorization": "Bearer sk_your_api_key"
}

response = requests.get(url, params=params, headers=headers, stream=True)

for line in response.iter_lines():
    if line:
        line = line.decode("utf-8")
        if line.startswith("data: "):
            import json
            data = json.loads(line[6:])
            print(data)

Error Codes

Error code	HTTP status	Description
`MISSING_API_KEY`	401	Missing `Authorization` header
`INVALID_API_KEY_FORMAT`	401	Invalid `Authorization` header format
`INVALID_API_KEY`	401	API key is invalid or disabled
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INSUFFICIENT_CREDITS`	402	Not enough credits for search
`INVALID_PARAMS`	400	Missing or invalid parameters

Available Sources

Source	Identifier	Coverage	Notable fields
Google Scholar	`google-scholar`	Comprehensive academic literature	`citationCount`, `summary`
PubMed	`pubmed`	Biomedical research	`volume`, `issue`, `pages`, `bibtex`
Wanfang	`wanfang`	Chinese academic literature	`pdfUrl`, `resourceType`

Table of Contents