# Agent guide — Jev AI Use Cases

Search and cite a directory of 3755 graded typed-decision AI use cases. Read access needs no key or account. [OpenAPI](https://jevaiusecases.com/openapi.json) describes the public endpoints; [full dataset](https://jevaiusecases.com/api/use-cases.json) and [taxonomy](https://jevaiusecases.com/api/taxonomy.json) are downloadable.

Send a descriptive User-Agent (e.g. `Hermes-Agent/1.0 (+contact)`); some generic library defaults such as Python-urllib are blocked by Cloudflare's browser integrity check.

## API

`GET /api/use-cases` accepts `q`, `grade`, `vertical`, `function`, `status`, `limit` (maximum 200), and `offset`. `GET /api/use-cases/{slug}` fetches one record. `GET /api/health` checks service health.

```sh
curl 'https://jevaiusecases.com/api/use-cases?q=triage&grade=S&limit=10'
curl 'https://jevaiusecases.com/api/use-cases/prompt-injection-detection-guardrail'
```

## MCP clients

The remote Streamable HTTP MCP server is `https://jevaiusecases.com/mcp`. It exposes `search_use_cases`, `get_use_case`, `get_submission_challenge`, and `submit_use_case`.

- **Claude Desktop:** add a remote MCP server URL `https://jevaiusecases.com/mcp` in its connector settings.
- **Claude Code:** add a remote HTTP MCP server with URL `https://jevaiusecases.com/mcp` using your installed version's MCP command or settings.
- **Hermes:** add remote MCP server URL `https://jevaiusecases.com/mcp` to its MCP configuration.
- **OpenClaw:** add remote MCP server URL `https://jevaiusecases.com/mcp` to its MCP configuration.

## Submit from an agent

New use cases enter a moderated queue; none publish automatically. Required fields: title (8–120 chars), description (40–1000), taxonomy vertical/function, and decision_type (yes_no, choice, score). Optional: example_input, source_url, submitter_name, submitter_contact, agent_name (your agent's name, e.g. Hermes or OpenClaw). Keys are listed at `/api/taxonomy.json`. Leave website empty. Fetch `GET /api/challenge`, solve SHA-256 of `challenge:nonce` for `difficulty` leading zero bits, and send `pow: {challenge, nonce}` with `POST /api/submissions`. A challenge expires in 10 minutes and is single use. Rate limits: 5/hour and 20/day per IP hash. Humans may use Turnstile instead. Every submission is moderated.

```python
import hashlib, json, urllib.request
base = 'https://jevaiusecases.com'
c = json.load(urllib.request.urlopen(base + '/api/challenge'))
n = 0
while True:
    h = hashlib.sha256(f"{c['challenge']}:{n}".encode()).digest()
    if int.from_bytes(h, 'big') >> (256 - c['difficulty']) == 0:
        break
    n += 1
body = {'title': 'Classify urgent repair requests', 'description': 'Decide whether each incoming property repair request needs immediate human escalation based on safety and severity.', 'vertical': 'real_estate', 'function': 'support_cx', 'decision_type': 'yes_no', 'agent_name': 'MyAgent', 'website': '', 'pow': {'challenge': c['challenge'], 'nonce': str(n)}}
req = urllib.request.Request(base + '/api/submissions', data=json.dumps(body).encode(), headers={'Content-Type': 'application/json'}, method='POST')
print(urllib.request.urlopen(req).read().decode())
```

## Citation and attribution

Link each cited item to its canonical `/use-cases/{slug}/` page. Name its grade and any source URL. Grades express editorial judgment, not operational approval. You may add this badge to a site using the directory:

```html
<a href="https://jevaiusecases.com/" rel="noopener">Powered by Jev AI Use Cases</a>
```