Jiro Docs

API Reference

Endpoints

Every request is validated against the schemas below — the examples are generated from the same definitions, so they cannot drift. Failed calls are refunded; an empty balance returns 402 INSUFFICIENT_CREDITS. Machine-readable spec: GET /api/openapi.

POST/v1/search1–10 credits

Search the web

Query 9+ engines with filters, freshness, and localization. Cached hits cost 1 credit.

API key or session

curl -X POST http://localhost:3000/v1/search \
  -H "Authorization: Bearer $JIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"q"}'
POST/v1/graph/plan1 credits

Plan a query graph

Dry run. Returns the validated graph, a cost estimate, the rationale for the shape chosen, and alternatives — without touching the network, so a run can be sized before it is paid for.

API key or session

curl http://localhost:3000/v1/graph/plan -H "Authorization: Bearer $JIRO_API_KEY"
POST/v1/graph/search10 credits

Run a query graph

Executes the graph and returns the run plus its evidence packet. Every claim in packet.claims carries the source_ids it rests on, so an answer can be traced back to the pages behind it. Branches that failed are reported in gaps[] with the node, query and reason. Refunded when the engine is unreachable.

API key or session

curl http://localhost:3000/v1/graph/search -H "Authorization: Bearer $JIRO_API_KEY"
POST/v1/scrape2 credits

Scrape a URL

Extract a page as markdown, html, text, json, or links.

API key or session

curl -X POST http://localhost:3000/v1/scrape \
  -H "Authorization: Bearer $JIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'
POST/v1/ai/search8 credits

AI search

An answer grounded in live results, with SSE streaming on /api/search/stream.

API key or session

curl -X POST http://localhost:3000/v1/ai/search \
  -H "Authorization: Bearer $JIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"q"}'
POST/v1/ai/synthesize6 credits

Synthesize

Summaries and reports from context text, a question, or source URLs.

API key or session

curl -X POST http://localhost:3000/v1/ai/synthesize \
  -H "Authorization: Bearer $JIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"q","context":"context","sources":["https://example.com/article"],"format":"summary"}'
POST/v1/agent15 credits

Autonomous research

Multi-step agent task with cited sources. Served by the backend at /v1/ai/agent.

API key or session

curl -X POST http://localhost:3000/v1/agent \
  -H "Authorization: Bearer $JIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"q"}'
POST/v1/search/batch12 credits

Batch search

Up to 10 queries × 5 engines, RRF-merged. Fully refunded when every engine fails.

API key or session

curl -X POST http://localhost:3000/v1/search/batch \
  -H "Authorization: Bearer $JIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries":["queries"]}'
POST/v1/social/{platform}/{action}4–10 credits

Social search and scrape

Search, scrape, or monitor across 12 platforms. Per-platform costs are admin-configurable.

API key or session

curl -X POST http://localhost:3000/v1/social/reddit/search \
  -H "Authorization: Bearer $JIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"platform","action":"search"}'
GET/v1/credits0 credits

Credit balance

Remaining credits for the calling API key. Free.

API key

curl http://localhost:3000/v1/credits -H "Authorization: Bearer $JIRO_API_KEY"
POST/api/keys0 credits

Create an API key

Issue a jsk_live_* key for the signed-in account.

Session

curl -X POST http://localhost:3000/api/keys \
  -H "Cookie: __session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"name"}'
GET/api/credits/balance0 credits

Account balance

Remaining credits for the signed-in account. Free.

Session

curl http://localhost:3000/api/credits/balance -H "Cookie: __session=$SESSION"
POST/api/mcp0–15 credits

MCP endpoint

JSON-RPC 2.0 for AI agents: 18 tools on Cloud (22 self-hosted), docs resources, and task prompts. Billed per tool.

API key

curl http://localhost:3000/api/mcp -H "Authorization: Bearer $JIRO_API_KEY"