x49 Scholar Search

Use this skill when a task needs scholarly paper, author, or metadata data from https://scholar.x49.ai.

Operating Rules

• Treat the public x49 Scholar API response as the source of truth for paper, author, facet, and count claims.
• Make a live API call for current or user-specific scholarly answers; do not answer from memory when the user expects x49 Scholar data.
• Prefer the smallest request that can answer the question, then expand with /papers/batch or author endpoints only when needed.
• Use only public v1 fields documented in this skill and references/api.md; do not send legacy frontend or internal fields.
• Keep scope explicit: report meta.returned_count, meta.total_results, filters, and whether semantic or standard mode was used.
• Treat paper search as limited-window retrieval. The API can report a large meta.total_results, but public v1 has no cursor pagination, so a response is not a complete literature corpus or systematic review.
• Treat /search/suggestions as an auxiliary UI autocomplete helper only. It is not a research, author, year, discovery, or recall surface, and some concept or all prefixes can return empty or delayed results under index load.
• Do not fabricate papers, authors, venues, DOI values, citation counts, abstracts, or availability. Say when a field is absent.
• Include stable identifiers in useful answers: paper_ref for papers and author_ref for authors.
• On API errors, surface the status, useful error.details, and request_id when present.

Defaults

• Base URL: https://scholar.x49.ai/api/v1
• Override base URL with X49_SCHOLAR_API_BASE_URL only when the user explicitly points you at another deployment.
• API key environment variable: X49_SCHOLAR_API_KEY
• Backward-compatible key variable: SCHOLAR_API_KEY
• Public trial API key: psk_tLzPCmJdUw5oAHGeXL2H_fMrDdSyiF_SBJfn2p5uCO4
• Auth header: Authorization: Bearer <API_KEY>
• Recommended headers: Accept: application/json and a non-empty User-Agent.
• Optional language header: Accept-Language, using the requested answer language or conversation language when it matters. Do not send lang as a query parameter.
• GET /health does not require auth.
• Search limit: 1..100
• Suggestion limit: default 8, maximum 20
• Public v1 does not expose cursor pagination.
• Useful response headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Bucket, and when quota applies, X-Usage-*.

Resolve the key in this order: X49_SCHOLAR_API_KEY, SCHOLAR_API_KEY, then the public trial key. The public trial key is intended for low-frequency public testing. For production, higher quota, or private quota, tell the user to create their own API key.

Do not invent, print, log, or store private API keys. The public trial key may appear in examples.

Choose The Call

• Topic, keyword, title, abstract, venue, concept, institution, open-access, or year search: call POST /papers/search.
• Discovery or natural-language research questions: call POST /papers/search with mode: "semantic".
• Exact terms, known phrases, broad recall, newest papers, or most-cited lists: call POST /papers/search with mode: "standard".
• More metadata for known papers: call POST /papers/batch with paper_refs returned by search.
• Optional UI autocomplete or filter candidates for venues, concepts, institutions, paper types, or mixed non-author/non-year suggestions: call GET /search/suggestions with query, type, and limit. Do not depend on suggestions for completeness.
• Find an author by name: call GET /authors/search, then use the returned author_ref.
• Do not use GET /search/suggestions for author discovery. type=author is not part of the public v1 suggestions contract; use GET /authors/search.
• Do not use GET /search/suggestions for years. type=year is not part of the public v1 suggestions contract; set filters.year_from and filters.year_to directly.
• Author profile: call GET /authors/{author_ref}.
• Representative or recent papers by an author: call GET /authors/{author_ref}/papers.
• Author-constrained paper search: pass filters.author_refs to POST /papers/search.

Request Rules

Paper search body fields:

• query is required unless filters.author_refs has at least one value.
• mode: standard or semantic.
• limit: 1..100.
• sort: relevance, most_cited, newest, or oldest.
• When using oldest or newest for modern topics, set a reasonable filters.year_from and set filters.year_to to the current calendar year unless the user explicitly asks for future-dated records. This prevents future-year metadata noise from dominating date sorting.
• filters.year_from and filters.year_to: integer publication years.
• filters.paper_types: array such as ["article", "review"].
• filters.venues: journal or conference display names.
• filters.concepts: topic or concept labels.
• filters.institutions: institution display names.
• filters.author_refs: public author references returned by author search.
• filters.open_access: boolean.

Suggestion query parameters:

• query: required typed prefix or candidate text.
• type: all, venue, concept, institution, or paper_type.
• limit: 1..20.
• Suggestions are convenience hints only. If a suggestion call is slow, empty, or inconsistent, proceed with /papers/search using known filters or ask for a narrower prefix.
• For author names, use /authors/search; public v1 suggestions do not expose author suggestions.
• For publication years, set filters.year_from and filters.year_to directly; public v1 suggestions do not expose year suggestions.

Author papers query parameters:

• limit: requested number of papers. The API accepts up to 100, but the service may return fewer than requested; live checks currently cap author-paper pages around 50.
• sort: most_cited, newest, or oldest.

Do not send old frontend or legacy fields such as q, field, authors, page, page_size, cursor, or lang. Public v1 rejects unsupported request fields and unsupported query parameters.

Quick API Patterns

Before any authenticated call:

X49_KEY="${X49_SCHOLAR_API_KEY:-${SCHOLAR_API_KEY:-psk_tLzPCmJdUw5oAHGeXL2H_fMrDdSyiF_SBJfn2p5uCO4}}"
BASE="${X49_SCHOLAR_API_BASE_URL:-https://scholar.x49.ai/api/v1}"
UA="${X49_SCHOLAR_USER_AGENT:-x49-scholar-search-skill/0.0.5}"

Topic search:

curl -sS "${BASE}/papers/search" \
  --max-time 30 \
  -H "Accept: application/json" \
  -H "User-Agent: ${UA}" \
  -H "Authorization: Bearer ${X49_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "retrieval augmented generation evaluation",
    "mode": "semantic",
    "limit": 10,
    "sort": "relevance",
    "filters": {
      "year_from": 2022,
      "paper_types": ["article", "review"],
      "open_access": true
    }
  }'

Paper detail expansion:

PAPER_REF="pap_from_search_result"
curl -sS "${BASE}/papers/batch" \
  -H "Accept: application/json" \
  -H "User-Agent: ${UA}" \
  -H "Authorization: Bearer ${X49_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"paper_refs\":[\"${PAPER_REF}\"]}"

Author workflow:

curl -G "${BASE}/authors/search" \
  -H "Accept: application/json" \
  -H "User-Agent: ${UA}" \
  -H "Authorization: Bearer ${X49_KEY}" \
  --data-urlencode "query=Yann LeCun" \
  --data-urlencode "limit=5"

Suggestions:

curl -G "${BASE}/search/suggestions" \
  -H "Accept: application/json" \
  -H "User-Agent: ${UA}" \
  -H "Authorization: Bearer ${X49_KEY}" \
  --data-urlencode "query=rna" \
  --data-urlencode "type=concept" \
  --data-urlencode "limit=5"

Local API Check

When validating installation or connectivity, run this from the installed skill folder:

python scripts/api_check.py

For a broader workflow check that also exercises suggestions, author lookup, author papers, and paper batch:

python scripts/api_check.py --full

Common user-level install locations are ~/.agents/skills/x49-scholar-search, $CODEX_HOME/skills/x49-scholar-search or ~/.codex/skills/x49-scholar-search, ~/.claude/skills/x49-scholar-search, ~/.openclaw/skills/x49-scholar-search, and ~/.hermes/skills/x49-scholar-search.

The default script checks GET /health and one authenticated POST /papers/search request that is expected to return zero results. It validates the public API boundary without depending on a particular live paper. It does not prove that every broad real-world query will be fast; if a real query times out, retry once with mode: "standard", limit: 1, and fewer filters before reporting the timeout.

Common Workflows

1. Quick topic search: use mode: "standard", sort: "newest" or sort: "most_cited", then present title, authors, year, venue, citations, and paper_ref.
2. Semantic discovery: use mode: "semantic" for natural-language questions, compare the returned papers before making a synthesis claim.
3. Filtered search: put year, type, venue, institution, concept, author, and open-access constraints inside filters.
4. Author workflow: search authors by name, pick the best candidate, fetch the profile, then fetch author papers or search with filters.author_refs.
5. Detail workflow: collect paper_ref values from search, call /papers/batch, then present fuller metadata.
6. Suggestion workflow: use /search/suggestions only as optional non-author, non-year UI autocomplete hints before a narrow filtered search; if it is slow or empty, proceed with known filters or ask for a narrower prefix.
7. Report handoff: if the user wants a synthesized literature review instead of a list, validate the query with search first, then use x49-scholar-report when installed.

Response Handling

For POST /papers/search, read:

• data.items[]: paper cards in the current response.
• data.items[].paper_ref: stable public paper reference for follow-up calls.
• data.items[].authors[].author_ref: stable public author reference when available.
• data.facets: aggregate filter values when returned.
• meta.limit, meta.returned_count, and meta.total_results: explain scope honestly.

Paper search and paper batch share a core public paper-card shape: paper_ref, title, year, authors, venue, metrics, identifiers, and links. Batch may add fuller metadata such as abstract, access, or PDF links when available, but optional fields can still be absent.

For citation counts, read metrics.citation_count. Do not expect a top-level citation_count; if metrics.citation_count is null or absent, say the citation count is not available.

For paper answers, include title, authors, year, venue, citation count when present, DOI or landing page when present, and paper_ref. Do not claim that a response is exhaustive. For review or synthesis-style answers, explicitly say the answer is based on a limited search window, not a complete systematic review.

For author answers, include name, last known institution when present, paper count, citation count, ORCID when present, and author_ref.

Error And Edge Handling

• 400 invalid_request: inspect error.details; fix unsupported fields, wrong parameter names, or invalid mode, sort, or type.
• 401: check that the Bearer header is present and that the key is not empty.
• 404: a paper_ref or author_ref may be invalid or no longer accessible; search again and use a fresh public ref.
• 429: respect rate limits and retry later; reduce unnecessary repeated calls.
• 429 quota_exceeded: the monthly API quota is exhausted; report the metric and remaining count when present.
• 503: service dependency unavailable; report the request_id if present.
• Timeout or slow response: retry once with a smaller limit, mode: "standard", and fewer filters. Do not silently switch to unrelated web search unless the user allows it.
• Empty results: relax filters first, then try semantic mode for discovery queries.

References

Read references/api.md when you need full endpoint details, response-shape notes, exact rejected legacy shapes, or more examples.