REST

Base URL

Public default: https://argand.org. Self-hosters point at their own gateway origin.

GET /api/search

Run a query. Returns ranked hits with URLs, titles, snippets, and scores.

Query params

• q — required. The query.
• page — optional, default 1.
• limit — optional, default 10, server-clamped to [1, 50].
• vertical — optional. general | programming | academic | news.
• freshness — optional. any | day | week | month | year.

Anonymous call

curl 'https://argand.org/api/search?q=rust+async&page=1&limit=10'

With API key

curl 'https://argand.org/api/search?q=rust+async&page=1&limit=10' \
  -H 'X-Argand-Key: your-argand-api-key'

Response shape

{
  "query": "rust async",
  "total_results": 1247,
  "search_time_ms": 84.3,
  "results": [
    {
      "rank": 1,
      "url": "https://doc.rust-lang.org/std/future/",
      "title": "std::future — Rust",
      "snippet": "...asynchronous values and the Future trait...",
      "score": 0.91,
      "kind": "programming"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total_pages": 125 }
}

GET /api/lucky

One-shot redirect: server picks the top hit and 302s you to the /yw/ referral URL for it. Useful for "take me to the docs" flows.

curl -I 'https://argand.org/api/lucky?q=tokio+docs'
# HTTP/2 302
# location: /yw/...?u=https%3A%2F%2Fdocs.rs%2Ftokio

The Location header is what the SDKs return from lucky(). Argand always wraps outgoing clicks through /yw/ — that's how we send traffic to source sites instead of capturing it.

GET /api/code/search

Programming-vertical search. Returns the same shape as /api/search but biased toward source code, READMEs, language docs, and registries.

curl 'https://argand.org/api/code/search?q=tokio::spawn&limit=5'

Auth

The X-Argand-Key header is an opaque key string. Anonymous requests work without it. Higher quotas unlock with a key — request one at /account/api-keys (provisioning UI lands with launch).

The SDKs do not couple to DIDs or Solid Pods — that's a separate provisioning concern. The auth header is just an opaque string.

Rate limits & errors

Anonymous tier: ~100 req/min/IP, soft-limited. Add a key to lift it. When you hit a limit you get a 429 with a Retry-After header (seconds form):

{
  "error": "rate_limited",
  "message": "Anonymous tier exceeded. Add X-Argand-Key for higher quotas.",
  "retry_after_seconds": 12
}

• 401 / 403 — invalid or revoked key. Don't retry.
• 429 — back off per Retry-After. SDKs honor this automatically.
• 5xx — transient. SDKs retry with exponential backoff (3 attempts, 250ms → 8s).