Getting Started with scrolljar

scrolljar provides AI-powered corpus search for ancient texts. This guide walks you through authentication, making your first API call, bulk export of large result sets, and integrating with MCP-compatible AI agents.

Prerequisites

• A scrolljar account — sign up at scrolljar.ai
• An API key — generate one from the dashboard

Authentication

All API requests require a bearer token. Use the API key from your dashboard:

curl https://api.scrolljar.ai/v1/health \
  -H "Authorization: Bearer sj_live_your_key_here"

Bulk export

When a search match set is large, prefer a CSV export over paginating every page.

1. Count first — call search with return_type="count" to size the match set.
2. Analyze when needed — use tabulate for distributions, crosstabs, and keyness without materializing every hit.
3. Export for bulk — call search with return_type="file" to receive a short-lived download URL for the full match set as CSV (not the CSV inlined in the tool response).

The file payload looks like:

{
  "file": {
    "url": "https://api.scrolljar.ai/v1/exports/<token>.csv",
    "expires_at": "2026-07-12T12:00:00+00:00",
    "row_count": 12500,
    "byte_size": 1048576
  }
}

Export shaping (file only)

This parameter is valid only with return_type="file":

Parameter	Purpose
feature_columns	Extra feature columns per capture label (for example {"w": ["sp", "gloss"]})

CSV text cells are populated automatically for node types approved by each corpus's serving configuration. Use describe_corpus to inspect the approved types. Individual text cells are capped at 64 KiB, and one export is capped at 200 MiB.

Lazy bolt-on downloads

Large paginated return_type="results" responses may include a file block for lazy download of the full set. The CSV is generated on first download; use this when you already peeped a page and want the rest as a file.

Download URL

• file.url is a public, unauthenticated token URL (GET /v1/exports/{token}.csv).
• Default lifetime is 24 hours (expires_at is authoritative).
• The API streams the version-pinned CSV directly without redirecting to an object-storage hostname, so clients only need to allowlist the API domain.
• If bulk export is not configured on the deployment, return_type="file" reports exports_not_configured.

When to stay inline

Keep return_type="results" / search_continue (and "passages") for small peeks and for sandboxes that cannot fetch an egress download URL.

Next Steps

• API Reference — full endpoint documentation with try-it-out
• MCP Integration — connect scrolljar to Claude, Cursor, and other AI agents