Hosted API + CLI Manual

SciAtlas API & CLI Documentation

Use this page when you want to run SciAtlas from the terminal: install the CLI, configure your token, choose a command, understand every parameter, and copy a ready-to-run example.

Start with CLI API Setup Browse Commands Parameter Guide

Overview

SciAtlas is designed to be used from the command line first. The CLI turns your topic, idea, author, keyword anchors, paper-title anchors, and retrieval preferences into a structured request, calls the hosted SciAtlas knowledge-graph backend, and saves reproducible artifacts under a run directory.

Most users do not need to write JSON by hand. Start with expert parameters for stable results, or use natural-language input for fast exploration.

Structured but friendly

Use flags such as --query, --keyword, --time-range, and --top-k instead of hand-writing API payloads.

Report-ready outputs

Every workflow can save request, response, metadata, and Markdown reports for review or reproduction.

Optional LLM help

If you configure your own LLM provider, SciAtlas can improve keyword extraction. If not, it keeps running with deterministic extraction.

API Configuration

The CLI is the recommended entry point, but it still calls the hosted SciAtlas API. Configure the base URL and your personal token once, then reuse them across all CLI commands and client code.

Direct Links

Base URL and Runtime Variables

Authentication Headers

Most hosted endpoints require a valid SciAtlas token. The CLI sends both headers for compatibility.

Authorization: Bearer YOUR_SCIATLAS_TOKEN
X-API-Key: YOUR_SCIATLAS_TOKEN

Browser Registration

Open the registration page, complete email verification, and copy the returned sciatlas_xxx token. The token is shown only once, so store it securely.

http://scinet.openkg.cn/register

Token Status and Usage

curl -H "Authorization: Bearer $SCIATLAS_API_KEY" \
  http://scinet.openkg.cn/v1/auth/token/status

curl -H "Authorization: Bearer $SCIATLAS_API_KEY" \
  "http://scinet.openkg.cn/v1/auth/usage?days=7"

Useful API Routes

Errors and Limits

Errors use regular HTTP status codes plus a short error type in the response body. Each personal token has a daily quota; heavier retrieval routes may consume more units than status checks.

How the CLI Works

A SciAtlas command usually has four parts: global connection options, one task command, input or anchor parameters, and output controls. The CLI then builds a plan, calls the proper backend route, and writes files for later review.

Mental model: use expert parameters when the topic matters, use natural language when you are still exploring, and use command-specific help when you are unsure about one command.

Quick Start

1. Install

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ./sciatlas

2. Configure your token

Register a personal token, then expose it to the CLI. The CLI sends it as Authorization and X-API-Key headers when it calls the hosted SciAtlas backend.

Open token registration

export SCIATLAS_API_BASE_URL="http://scinet.openkg.cn"
export SCIATLAS_API_KEY="your-personal-sciatlas-token"

3. Check the setup

sciatlas health
sciatlas config
sciatlas search-papers -h

4. Run a first retrieval

Start with a small result set. Once the topic and anchors look right, increase --top-k or adjust ranking preferences.

sciatlas search-papers \
  --query "open world agent" \
  --domain "artificial intelligence" \
  --time-range 2020-2024 \
  --keyword "high:open world agent" \
  --top-k 3 \
  --top-keywords 0 \
  --max-titles 0 \
  --max-refs 0

After the command finishes, check the new folder under runs/. It keeps the request, response, metadata, and report so the result can be shared or reproduced.

Windows PowerShell users can use setx or $env:SCIATLAS_API_KEY="..." for the current session.

Input Styles

Recommended: expert parameters

Best for formal use. You state the topic, domain, time range, keywords, title anchors, and ranking preference explicitly.

Compatible: natural language

Best for quick exploration. Put your intent in --text; SciAtlas extracts a plan and can also read structured hints inside the text.

Anchor Levels

Anchors tell SciAtlas which signals should pull the graph closer to your real intent. Use high for must-match ideas, middle for helpful context, and low for weak hints.

Expert example

sciatlas --timeout 900 search-papers \
  --retrieval-mode hybrid \
  --query "open world agent" \
  --domain "artificial intelligence" \
  --time-range 2020-2024 \
  --keyword "high:open world agent" \
  --keyword "middle:embodied agent" \
  --title "middle:Voyager: An Open-Ended Embodied Agent with Large Language Models" \
  --reference "low:JARVIS-1: Open-World Multi-task Agents with Memory-Augmented Multimodal Language Models" \
  --top-k 5 \
  --top-keywords 0 \
  --max-titles 0 \
  --max-refs 0 \
  --bias-keyword high \
  --bias-related high \
  --bias-exploration low \
  --ranking-profile precision \
  --report-max-items 5

Natural-language example

sciatlas --timeout 900 search-papers \
  --retrieval-mode hybrid \
  --text "Find papers about open world agent in artificial intelligence after 2020. Return 3 papers.

Keywords[high]: open world agent" \
  --top-k 3 \
  --top-keywords 1 \
  --max-titles 0 \
  --max-refs 0

Parameter Guide

These parameter groups are reused by most SciAtlas commands. Command-specific parameters are listed in the command cards below.

Global options

Input options

Plan and anchor options

Retrieval options

Retrieval and Ranking Choices

Output options

Command Reference

Use the search box to find a workflow or parameter. Each card includes what the command does, the parameter groups it accepts, command-specific options, and a working example.

Command Map

Use this table when you know the task but are not sure which command to start from.

Common Examples