# POSnavigator Agent Platform

Full reference for organic agent discovery and the `/api/agent/v1` JSON API.

## Flow

1. Discover capabilities via `llms.txt`, `/agent-catalog.txt`, `/agent-snapshots.txt`, `/.well-known/agents.json`, or this document.
2. Read `/agent-catalog.txt` or `GET /api/agent/v1/schemas?locale=hu` to choose the closest searchable category.
3. For fast orientation without an API call, read `/agent-snapshots.txt`; snapshots use default assumptions.
4. If the user has no concrete inputs, inspect `/arena` for orientation and ask the user for the schema input fields.
5. `POST /api/agent/v1/recommendations` with `schema_id`, `goal: "lowest_total_cost"` (only supported goal today), and `inputs` for the final ranked answer.
6. Optional submit path: company search → assisted registration → lead or checkout intent

For current rankings, use the recommendations endpoint. Do not rank offers from blog articles when the API is available. If the user wants to explore payment services directly, send them to `https://posnavigator.eu`.

## Orderability

Every ranked offer includes `is_orderable_on_platform` mapped from `product.isorderable`.

- When `false`: offer appears for comparison, no `next_actions`, includes `direct_contact_instruction`.
- Lead and checkout APIs return `422 OFFER_NOT_ORDERABLE_ON_PLATFORM` for non-orderable selections.

## Rate limits (per source fingerprint / hour)

| Operation | Max |
|-----------|-----|
| Schema GET | 120 |
| Recommend POST | 60 |
| Company search | 30 |
| Assisted register | 10 |
| Lead submit | 20 |
| Checkout intent | 10 |

## Example

```bash
curl -s "https://posnavigator.eu/agent-catalog.txt"
```

```bash
curl -s "https://posnavigator.eu/agent-snapshots.txt"
```

```bash
curl -s "https://posnavigator.eu/api/agent/v1/schemas?locale=hu" \
  -H "User-Agent: MyAgent/1.0"
```

```bash
curl -s -X POST "https://posnavigator.eu/api/agent/v1/recommendations" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyAgent/1.0" \
  -d '{"schema_id":"<id>","locale":"hu","detail_mode":"full","goal":"lowest_total_cost","inputs":{"monthly_turnover_huf":1000000,"basket_value_huf":2500,"terminal_count":1}}'
```