Documentation

An agent with no key registers itself and searches at once on a small unclaimed tier. One visit by a human to the claim link binds it into their organization; mining enrollment then runs unattended.

1. POST /v1/agents/register with an optional name, client and requested_scopes hint. The response carries the key (shown once), a claim URL and code, and a poll URL.
2. Show the human the claim URL, or the code to type at /claim. They sign in here, see the agent's name and registration time, and grant credits and/or mining. The code is single use and expires with the unclaimed key.
3. Poll GET /v1/agents/{agent_id} with the key until status is claimed. expired means register again. Lost the record but still hold the key? GET /v1/agents/me returns the same body (with agent_id) and rebuilds it.
4. Claimed with the mining scope: POST /v1/agents/enroll with a slot returns the same 15-minute enrollment token the Mining page mints, to redeem with the MINIS server at once.

curl -s -X POST https://agents-v1.jevlin.ai/v1/agents/register \
  -H "Content-Type: application/json" -H "User-Agent: my-tool/1.0" \
  -d '{"name": "my-agent", "client": "my-tool/1.0", "requested_scopes": ["mining"]}'

{"agent_id": "…", "key": "sr-…",
 "claim_url": "https://platform.jevlin.ai/claim/AB12-CD34", "claim_code": "AB12-CD34",
 "claim_expires_at": "…", "poll": {"url": "https://agents-v1.jevlin.ai/v1/agents/…", "interval_s": 5},
 "tier": "unclaimed"}

curl -s https://agents-v1.jevlin.ai/v1/agents/<agent_id> -H "Authorization: Bearer sr-…"   # or /v1/agents/me
{"agent_id": "…", "status": "claimed", "scopes": ["credits", "mining"], "claimed_at": "…",
 "project_id": "…", "console_url": "https://platform.jevlin.ai/projects/…",
 "mining": {"available": true, "slots": ["twilight-slot-3"], "participant_has_other_agent": false}}

curl -s -X POST https://agents-v1.jevlin.ai/v1/agents/enroll -H "Authorization: Bearer sr-…" \
  -H "Content-Type: application/json" -d '{"slot": "twilight-slot-3"}'
{"token": "…", "slot": "twilight-slot-3", "expires_at": "…"}

Refusals are specific: 403 not_claimed, 403 mining_not_granted, 409 attribution_unavailable, 400 unknown_slot, 501 minis_disabled. These hosts sit behind Cloudflare, so send a real User-Agent.

curl -s https://api.jevlin.ai/v1/search \
  -H "Authorization: Bearer $SEARCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "state of grid-scale battery storage 2026", "tier": "balanced"}'

# tiers: fast (three fast indexes, one per index group; the only tier for an unclaimed agent) · balanced (default)
# · max (15 results per arm, a 24-page merged window and 2,000-character excerpts; deep-research arms,
#   where the deployment runs them, may keep working after the response — watch the trace)

Every field a caller shapes a query with — only query is required. The complete request and response schema (every field, enum and error) is in the OpenAPI spec.

domain_filter and recency are enforced by the router. Each is sent to every arm that takes it, and a result that fails the check is dropped before the merge, so a host outside your list or a page dated before your window does not come back. With either filter the response carries filters_applied: per filter, the arms it was sent to (sent_to), the arms it was not (not_sent) and how many results the router's own check removed (dropped).

The core indexes, which run on every balanced and max request, are exa, telem, brave, serper, parallel-search, perplexity-search and tinyfish. serpapi (a Google read, slow lane) is extended: it fires only when named in providers and lands on the trace after the response. exa-lite (a lighter Exa read) is extended too where the deployment runs it: one of the fast tier's three arms, and on balanced or max fired only when named. On this deployment, which routes through Telem, the research arms (parallel, tavily-research, pplx-agent, octen) are not configured, and naming one is a 400. Omit providers to let the tier choose the fan-out; pass a subset on balanced or max to restrict it (it is refused on fast).

curl -s https://api.jevlin.ai/v1/search \
  -H "Authorization: Bearer $SEARCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "state of grid-scale battery storage 2026",
       "tier": "balanced",
       "providers": ["exa", "brave", "parallel-search"]}'

• Core arms fire on every request; extended arms only when your providers list names them.
• A slow-lane arm is dispatched with the request but not waited for: it returns pending, lands on the trace afterwards and is billed under the same request id, so usage.cost_micros is a floor until it does. Here that arm is serpapi, which lands within 20 seconds. On a direct-key deployment the research arms (parallel, tavily-research, pplx-agent, octen) take about 30 seconds to 4 minutes; their thinking streams as agent events and is readable mid-run as live_thinking.
• Cost estimates are checked before dispatch: a set over the tier's ceiling is trimmed (see decision.trimmed), not refused. The daily ceiling refuses with 402.
• cost_source: "reported" means cost_micros already carries the provider's own number; ignore cost figures inside agent.raw.
• Bodies over 64 KiB and queries over 4096 characters are refused with 400 before dispatch.

A search gives about 1,200 characters per page. When the fact you need — a parameter, a limit, a signature — is on a page but not in its excerpt, fetch that page: POST /v1/fetch returns the text of up to five pages per call, each named by the source_id from a merged view or by a URL a search returned. Only pages your own searches returned in the last 24 hours can be fetched; anything else comes back not_recent, free. It is not a general fetcher.

curl -s https://api.jevlin.ai/v1/fetch \
  -H "Authorization: Bearer $SEARCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pages": [{"source_id": "s_…"}], "max_chars": 10000, "query": "what you are looking for"}'

{"request_id": "…",
 "pages": [{"source_id": "s_…", "url": "…", "title": "…", "status": "ok",
            "content": "…", "offset": 0, "next_offset": 9874, "content_length": 171842,
            "provider": "tavily", "cached": false, "cost_micros": 2000}],
 "usage": {"cost_micros": 2000, "latency_ms": 812}}

• Each page comes back as at most max_chars characters (default 10,000; 1,000–50,000) from offset. next_offset is where to read on from, null once the page is exhausted; reading on within 15 minutes is served from the fetch cache. An optional query starts the first slice at the paragraph that matches it best (experimental).
• Links are removed from the text (a link keeps its words, loses its target) and markdown escapes are undone; code blocks are kept as they are. A page the upstream cut says truncated: true with its real full_length.
• Per page: ok; failed with a reason (upstream_failed, worth one retry, or unrendered, an app shell that needs a browser — use another source); not_recent; invalid. The call is 200 whatever the pages say.
• Each ok page costs 2,000 µ$ ($0.002), against the same ceilings and rate windows as a search; failed, not_recent and invalid pages are free. A fetched page is recorded as result.fetched on the trace of the search that returned it, so no feedback post is needed for it.
• Needs a claimed account that keeps content: an unclaimed agent, a zero-retention account or one with no credit to bill gets 403 fetch_unavailable; where fetch is not offered, 503 fetch_disabled.

Cap what a project can spend per day, week, or month — on top of the credit balance, whichever is lowest. Set them here (owner or admin) on the project's Spend limits page, or from any key over the API. Amounts are micro-dollars (1000000 = $1); 0 or an omitted field means no cap on that window. Windows are calendar UTC (day from 00:00, week from Monday, month from the 1st).

# read current caps + spend today (against the ceiling), this week and this month (against their caps)
curl -s https://api.jevlin.ai/v1/limits -H "Authorization: Bearer $SEARCHROUTER_API_KEY"

# set a $5/day and $50/month cap (partial update: omit a window to leave it)
curl -s https://api.jevlin.ai/v1/limits \
  -H "Authorization: Bearer $SEARCHROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"daily_micros": 5000000, "monthly_micros": 50000000}'

A cap set through this endpoint binds on the next control-plane sweep, up to a minute later; one set in the Limits tab of the console binds within seconds. Hitting one returns 402 spend_ceiling. Reading or setting limits spends nothing and works even at the ceiling or out of credit, so a capped account can always raise its own budget.

Every metered response carries the rate windows as they stand after it was charged: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds) for the per-minute bucket, and the same three with -Hour for the hourly one. A window with no limit sends no header. A 429 carries Retry-After; wait that long. GET /v1/account returns the same numbers without spending anything.

Send Idempotency-Key: <uuid> on POST /v1/search to make a retry safe: the same key with the same body within 24 hours returns the first response (marked Idempotent-Replayed: true) and nothing runs or is billed twice. While the first is still running you get 409 idempotency_in_progress (retry after Retry-After); the same key with a different body is 422 idempotency_key_reused. Ignored on the stream route.

Pick scopes when you issue a key on the API keys page; a key with no scopes may do everything. A call outside a key's scopes is 403 scope, naming the missing scope. Keys can also expire (1–365 days), carry rate limits of their own, and be rotated with an overlap during which the old key still works.

Research arms can land after the response went out. Set a webhook on the project's Limits page (owner or admin: an https URL on a public host and a 16–256 byte secret) and the gateway POSTs one search.slow_lane.landed event per landed arm: request_id, tenant_id, provider, status, cost_micros, landed_at — no query and no results; read those from the trace.

Each delivery has X-Jevlin-Event, X-Jevlin-Timestamp (unix seconds) and X-Jevlin-Signature: sha256=<hex>. Before trusting it: compute HMAC-SHA256 of timestamp + "." + raw body with your secret, compare in constant time, and reject a timestamp more than a few minutes old. Answer 2xx quickly and de-duplicate on request_id + provider: a delivery can arrive more than once, and is retried up to three times on a 5xx, 408, 429 or a timeout.

mac = hmac.new(secret, f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest("sha256=" + mac, request.headers["X-Jevlin-Signature"])

The trace is the record; the webhook is the nudge. A client that must not miss a landing reads the trace back.

Where the fan-out spends across the platform, by category — retrieval indexes, answer engines, and slow-lane research agents. Aggregated across all projects through 2026-09-14. Your own project's spend and provider mix are on its Reports page in the console.