---
title: Agent Seek for agents
description: How to call POST /v1/search with a Bearer API key.
canonical: /agents.md
last-updated: 2026-09-20
---

# Agent Seek — how agents should call

Agent Seek is a **search API**, not a chat model. You.com discovers up to 100 web candidates; TypeSafe Jev cascade-ranks them; you receive a small scored JSON list. Synthesize answers yourself from `results`.

This file is the public agent how-to. It is **not** the internal implementer brief (`AGENTS.md` in the repo). For installable host instructions see the [skill](/skills/agent-seek/SKILL.md). For humans see [docs](/docs).

## Install the skill

Efficient path: **skill → [llms.txt](/llms.txt) → [auth.md](/auth.md) → MCP or REST**.

Stable skill URLs (same file):

- [/.well-known/agent-skills/agent-seek/SKILL.md](/.well-known/agent-skills/agent-seek/SKILL.md)
- [/skills/agent-seek/SKILL.md](/skills/agent-seek/SKILL.md)
- Index: [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json)

**Cursor:** save `SKILL.md` as `.cursor/skills/agent-seek/SKILL.md` (project) or `~/.cursor/skills/agent-seek/SKILL.md` (user). Or discover via the agent-skills index.

**Other coding agents:** download `SKILL.md` from the well-known URL, or link it from the index.

Then read [llms.txt](/llms.txt), authenticate via [auth.md](/auth.md), and call `POST /v1/search` or MCP ([/mcp](/mcp), [server card](/.well-known/mcp/server-card.json)).

## When to use this

- Research / RAG: you need relevant **URLs + snippets + scores**, not a written brief.
- Raw SERP quality is poor (SEO republishers, lookalike brands, thin blurbs).
- You can send `Authorization: Bearer $AGENT_SEEK_API_KEY`.

## When not to use

- More than 100 discover candidates (hard cap).
- Unbounded site crawl or full-web extraction as the default path (`mode=deep` fetches Stage A survivors only, cap 12).
- Asking the service to write the answer.

## Auth

Auth is OAuth 2.0 (see [auth.md](/auth.md)) or a shared API key.

```http
Authorization: Bearer $AGENT_SEEK_API_KEY
```

`X-API-Key` is also accepted. Obtain a key from the operator ([contact](/contact)); local default is documented in `.env.example`. Full walkthrough: [auth.md](/auth.md).

## `POST /v1/search`

```json
{
  "q": "Introducing System One Models Jev",
  "k": 10,
  "max_candidates": 50,
  "mode": "deep",
  "nocache": false
}
```

| Field | Rules |
| --- | --- |
| `q` | required, 1–500 characters |
| `k` | 1–25, default 10 |
| `max_candidates` | 1–100, default 50 |
| `mode` | `deep` (default — Stage A survivor fetch, cap 12) or `snip` (cheaper) |
| `nocache` | optional; `true` forces a discover cache miss |

Also: `GET /v1/search?q=…` with the same query parameters.

### Response

Each result includes `rank`, `url`, `title`, `snippet`, `score` (0–1), `flags`, `raw_rank`, `provider`, and optional `signals` (answerability, authority, on_topic, states_sought_fact, subject_match, spam, prompt_injection). UI label for `prompt_injection` is **Injection risk**.

Hard gates (order, fail-open if a parse is missing): `subject_match` < 0.55, then `is_republisher` ≥ 0.55, then `prompt_injection` ≥ 0.55 exclude from `results` (still in `raw_results`). If gates empty the scored list, pre-gate top-k is restored (`gates_relaxed`).

`meta.agent_seek_version` is the service version. `meta.ranking` is `jev`, `raw`, or `raw_fallback` (Jev failed; still HTTP 200).

Prefer high `score` + `on_topic`. `spam_low` soft-demotes (score × 0.75).

## Errors

API 4xx/5xx use RFC 9457 `application/problem+json` (`type`, `title`, `status`, `detail`, `code`, `message`, `hint`):

```json
{
  "type": "https://agentseek.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Unauthorized",
  "code": "UNAUTHORIZED",
  "message": "Unauthorized",
  "hint": "Use OAuth (see /auth.md) or Authorization: Bearer $AGENT_SEEK_API_KEY."
}
```

Rate limit: 60 requests / minute / key (in-memory prototype). `429` includes `Retry-After`. See [OpenAPI](/openapi.json).

## Curl

```bash
curl -sS -X POST "$AGENT_SEEK_BASE/v1/search" \
  -H "Authorization: Bearer $AGENT_SEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Introducing System One Models Jev","k":10,"mode":"deep"}'
```

Live prototype base: `https://agentseek.dev` (alternate: `https://gitmaxd-agent-seek.exe.xyz`)

## Related

- [llms.txt](/llms.txt) · [auth.md](/auth.md) · [pricing.md](/pricing.md)
- [Skill](/skills/agent-seek/SKILL.md) · [Skill index](/.well-known/agent-skills/index.json)
- [MCP Streamable HTTP](/mcp) · [server card](/.well-known/mcp/server-card.json)
- [OAuth authorization server](/.well-known/oauth-authorization-server) · [protected resource](/.well-known/oauth-protected-resource)