API Quick Reference

Frontier API (default port 8090)

POST /seeds

Seed the frontier with URLs to crawl.

curl -X POST http://localhost:8090/seeds \
  -H 'Content-Type: application/json' \
  -d '{"urls": ["https://example.com/", "https://docs.example.com/"]}'

Response: {"accepted": 2}

POST /pop

Pop the next URL from the frontier.

curl -X POST http://localhost:8090/pop \
  -H 'Content-Type: application/json' \
  -d '{}'

Response: {"url": "https://example.com/", "depth": 0, "priority": 0}

Returns {"url": null} when the frontier is empty.

POST /discovered

Push discovered URLs back to the frontier.

curl -X POST http://localhost:8090/discovered \
  -H 'Content-Type: application/json' \
  -d '{"urls": [{"url": "https://example.com/page", "depth": 1, "parent_hash": "af1349b9..."}]}'

Response: {"accepted": 1}

GET /status

curl http://localhost:8090/status

Response: {"queue_size": 1234, "seen_count": 5678, "host_count": 42, "seed_value": 42}

GET /health

curl http://localhost:8090/health

Response: "ok"

Retrieval API (default port 8080)

GET /v1/content

curl "http://localhost:8080/v1/content?url=https://example.com/"

Returns raw captured content.

GET /v1/chunks

curl "http://localhost:8080/v1/chunks?url=https://example.com/"

Returns RAG chunks with provenance (chunk_hash, source_hash, captured_at, char_offset).

GET /v1/history

curl "http://localhost:8080/v1/history?url=https://example.com/"

Returns all captures with timestamps and content hashes.

GET /v1/search

curl "http://localhost:8080/v1/search?q=example+domain"

Returns matching content across all captured pages.

GET /metrics

curl http://localhost:8080/metrics

Returns Prometheus text exposition format.

GET /health

curl http://localhost:8080/health

Response: "ok"