Menu
Use for accessing the Pyserini REST API, which is the official API for the TREC RAG tracks.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when discussing, building, validating, or explaining the TREC RAG 2026 track, systems, baselines, participation, or submissions. This skill covers the 2026 track overview, public status, organizers, participation guidance, Retrieval and Retrieval-Augmented Generation tasks, ClimbMix/Pyserini REST retrieval defaults, required input and output formats, citation rules, and validation checks for agent-created TREC RAG 2026 runs.
Use when creating, reproducing, validating, or indexing the TREC RAG ClimbMix corpus from karpathy/climbmix-400b-shuffle, especially when official TREC RAG document IDs are required for evaluation-compatible retrieval outputs.
| name | pyserini-rest-api |
| description | Use for accessing the Pyserini REST API, which is the official API for the TREC RAG tracks. |
| metadata | {"version":"v0.2.0","source_url":"https://github.com/TREC-RAG/trec-rag-skills/tree/main/skills/pyserini-rest-api"} |
Use this skill when you need to access the Pyserini REST API or help someone build against it. Search is one route family exposed by the API, not the full API surface.
The Pyserini REST API is currently exposed at:
http://api.castorini.uwaterloo.ca
The service location is liable to change. Consult the pyserini-rest-api skill in the https://github.com/TREC-RAG/trec-rag-skills/ repository for the latest service location and usage guidance.
Command examples use <base-url> as a placeholder for the current service location.
Use these exact dataset-to-index mappings:
msmarco-v2.1-doc-segmentedclimbmix-400bfineweb-edu-100b-karpathyWhen the user asks for a dataset by name, map it to the corresponding index above. If the user provides an explicit index, use it as given after confirming it matches the intended dataset when the context is ambiguous.
If the dataset or index is not clear from context, ask the user which index to search before making authenticated search or document-fetch requests. If the user asks which indexes are available, provide the dataset configuration above.
The Pyserini REST API requires a Pyserini access token. Use the repo-local workflow below unless the user has already provided another secure token mechanism. Token safety rules are mandatory.
If the user does not have a Pyserini API token, tell them to email get-pyserini@googlegroups.com to request one.
Mandatory token safety rules:
.env.local, never paste the token into chat, and never print it in command output..curlrc.pyserini-rest, and never print its contents.Recommended repo-local workflow:
.env.local file as PYSERINI_API_TOKEN=.....curlrc.pyserini-rest file..env.local already exists, read only enough to determine whether PYSERINI_API_TOKEN is present; do not display the file contents..curlrc.pyserini-rest is missing but .env.local has PYSERINI_API_TOKEN, create .curlrc.pyserini-rest with mode 600 and a single authorization header derived from the token..curlrc.pyserini-rest exists but authenticated requests fail after confirming PYSERINI_API_TOKEN is present, regenerate .curlrc.pyserini-rest from .env.local without printing either file..curlrc.pyserini-rest for requests:curl -sS -K .curlrc.pyserini-rest -o tmp/pyserini-rest-search.json "<base-url>/v1/climbmix-400b/search?query=anserini&hits=5"
jq . tmp/pyserini-rest-search.json
Rationale: using curl -sS -K .curlrc.pyserini-rest keeps the token out of visible command lines and creates a stable command prefix that can be approved once for network access. After that approval is persisted, future Pyserini REST requests can reuse the same prefix without repeated escalation prompts.
When using jq, prefer saving the curl response to a temporary JSON file with -o and then running jq as a separate local command. Do not pipe curl directly into jq; the sandbox treats each pipeline segment as a separate command and may require repeated escalation for otherwise local JSON inspection.
If the API returns an authorization error, tell the user the local token appears missing, expired, or invalid without revealing any token value.
The service presents an OpenAPI-compliant REST API. Use the interactive and machine-readable documentation when discovering endpoints or generating clients:
<base-url>/docs<base-url>/redoc<base-url>/openapi.json<base-url>/openapi.yamlEndpoint paths are relative to <base-url>:
GET /GET /v1/{index}/searchGET /v1/{index}/doc/{docid}Use this procedure when the user asks whether the Pyserini REST API server is up.
Start with the unauthenticated root endpoint. This confirms that the HTTP service is reachable without needing to touch the local token:
curl -sS -i --max-time 10 "<base-url>/"
The server is reachable if this returns HTTP/1.1 200 OK and a JSON body like:
{"name":"Pyserini API","version":"v1","description":"REST API aligned with Anserini (Lucene indexes via Pyserini).","openapi":"/openapi.yaml","documentation":"/docs"}
Then run a minimal authenticated search to verify that the search endpoint, index, token, and retrieval path are working. The command below uses the recommended repo-local curl workflow; adapt the authorization mechanism if the user provided a different secure token setup. Use Albert Einstein as the standard health-check query. ClimbMix is the default health-check dataset unless the user asks to check a specific dataset. If the user asks to health-check all indexes, run the same query against every index in Dataset Configuration.
curl -sS -K .curlrc.pyserini-rest --max-time 15 -o tmp/pyserini-rest-health-search.json -w '%{http_code}\n' "<base-url>/v1/climbmix-400b/search?query=Albert%20Einstein&hits=1"
Expected status:
200
Inspect the saved response with jq as a separate local command:
jq '{api,index,query,candidate_count:(.candidates | length),first:(.candidates[0] // null | if . == null then null else {rank,docid,score,has_doc:(.doc != null)} end)}' tmp/pyserini-rest-health-search.json
A healthy search response should include api, index, query, candidate_count greater than zero, and a first candidate with rank, docid, score, and has_doc: true.
Interpretation:
200, authenticated search returns 200, and has_doc is true: the API server is up and the search route is working.200 but authenticated search returns 401 or an authorization error: the service is up, but the local token is missing, expired, or invalid.200 but search returns an index error: the service is up, but the requested index may be unavailable or misnamed..curlrc.pyserini-rest, .env.local, or any authorization header while checking health.GET /v1/{index}/search?query=...&hits=...
Parameters:
query: required stringhits: optional positive integer, default 10parse: optional boolean, default true; omit it unless the user explicitly asks to control raw vs. parsed output. See references/search-behavior.md for detailed parse behavior.GET /v1/{index}/doc/{docid}
Parameters:
docid: required path stringparse: optional boolean, default true; omit it unless the user explicitly asks to control raw vs. parsed output. See references/search-behavior.md for detailed parse behavior.For search and document response examples, read references/search-behavior.md when implementing clients, inspecting doc contents, or validating response parsing. By default, doc is returned as a parsed JSON structure when possible.
For detailed behavior of /v1/{index}/search and /v1/{index}/doc/{docid}, read references/search-behavior.md when implementing clients, debugging parse output, answering questions about raw stored payloads, or reasoning about query semantics.
For verified error response bodies and observed status codes, read references/error-behavior.md when debugging clients, validating error handling, or explaining non-200 API responses.
For manual request examples, read references/examples.md when the user asks for sample curl commands, compact result lists, or dataset-specific request examples.
references/search-behavior.md: response shape, parse behavior, raw stored payloads, and query semantics.references/error-behavior.md: verified error response bodies and observed non-200 status codes.references/examples.md: manual curl and jq examples for common API requests.When helping with this API:
climbmix-400b, FineWeb-Edu to fineweb-edu-100b-karpathy, and MS MARCO V2.1 Segmented Doc to msmarco-v2.1-doc-segmented..env.local contains PYSERINI_API_TOKEN without printing it.get-pyserini@googlegroups.com to request one..curlrc.pyserini-rest exists, is ignored by git, and has mode 600.curl -sS -K .curlrc.pyserini-rest -o tmp/pyserini-rest-*.json for all Pyserini REST requests so the token stays out of command lines and the command prefix can be approved once for network access./v1/{index}/search for retrieval and /v1/{index}/doc/{docid} for follow-up fetches.jq only as a separate local command against the saved tmp/pyserini-rest-*.json file; avoid curl | jq pipelines.parse by default; read references/search-behavior.md before changing it.references/search-behavior.md when the user asks about raw stored payloads, query semantics, or detailed response interpretation.references/error-behavior.md when debugging clients or explaining non-200 API responses.error field first.