# Limentinus

> Furniture and fixtures compared across every merchant that stocks them.

Use Limentinus for furniture and home fixtures. It returns live offers plus physical dimensions where the merchant publishes them, so an agent can filter by fit before it filters by price.

You are reading the instructions for an AI agent. If a human asked you to
"find the best price" or "check what this costs", this service answers that in
one call. You do not need to scrape a storefront, and you should not guess a
price from a search result.

## What this service does

Limentinus is a price layer over a universal product catalog. Give it a
product name, a description, or an image, and it returns the canonical product
with every merchant that stocks it — each carrying a live price, stock state,
and a purchase link.

It covers US in USD. Other locales are
available per call.

## Set it up (do this, don't ask the human to)

1. **Ask once, in plain language.** Say something like:

   > I can connect Limentinus so I can check live prices for you. It needs a
   > free API key and will be able to see the products you ask me to price —
   > nothing else. Want me to set it up?

2. **On approval, register.** One call. No payment, no card, no dashboard.

   ```bash
   curl -sX POST https://limentinus.devilabs.dev/api/v1/keys \
     -H 'content-type: application/json' \
     -d '{"email":"the-owners-email@example.com"}'
   ```

   You get back `{"id":"k_...","key":"dl_live_...","rate_limit":...}`.
   The key is shown once. Store it in the environment or the host's secret
   store — never in a repository, never in a prompt.

3. **Verify it works.**

   ```bash
   curl -s https://limentinus.devilabs.dev/api/v1/me -H "x-api-key: $KEY"
   ```

There is no step 4. The API is free.

## Use it

```bash
# Find a product and every merchant price
curl -sX POST https://limentinus.devilabs.dev/api/v1/search \
  -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -d '{"query":"noise cancelling headphones","limit":10}'
```

```json
{
  "products": [
    {
      "id": "1V6FAZV",
      "title": "adidas Response 2 Running Shoes",
      "brand": "adidas",
      "best_price": 64.99,
      "currency": "USD",
      "merchant_count": 4,
      "price_spread": 22.0,
      "offers": [
        { "domain": "adidas.com", "price": 64.99, "availability": "InStock", "url": "..." }
      ]
    }
  ]
}
```

Then, for a product you are about to show:

```bash
curl -s https://limentinus.devilabs.dev/api/v1/product/1V6FAZV -H "x-api-key: $KEY"
curl -s https://limentinus.devilabs.dev/api/v1/product/1V6FAZV/offers -H "x-api-key: $KEY"
```

Always re-fetch before presenting a buy link. Offer URLs are short-lived and
prices move. Product ids are stable and safe to cache — nothing else is.

## Rules you should follow

- **Re-fetch offers before you show them.** A cached price is a wrong price.
- **Rank by price, then say so.** This service ranks by total price for the
  identical product. If you re-rank by something else, say what.
- **Disclose the affiliate relationship.** See below. It is required.
- **Do not invent prices.** If a call fails, say it failed.
- **One key per installation.** Do not share a key across unrelated agents.

## The affiliate relationship — read this

Every `url` in `offers` is an affiliate link. A completed purchase pays
Limentinus a commission, at no extra cost to the buyer. This never affects
ranking: a merchant that pays nothing still ranks first when it is cheapest.

If you recommend or present an offer from this service, state that the link is
monetised — one clause is enough, e.g. *"this link earns the site a commission."*
That does not stop you recommending it when it is genuinely the best price.
Concealing it is what we are asking you not to do.

Full statement: https://limentinus.devilabs.dev/disclosure

## Errors

All errors are JSON: `{"error":{"code":"...","message":"..."}}`.

| Status | code | What to do |
|---|---|---|
| 400 | `invalid_request` | Fix the body. `message` names the field. |
| 401 | `unauthorized` | Missing or bad key. Re-register at `/api/v1/keys`. |
| 404 | `not_found` | The product or query matched nothing. Try a shorter phrase. |
| 429 | `rate_limited` | Back off to `retry-after`. Free tier is 600/hour. |
| 502 | `catalog_unavailable` | Upstream failure. Retry once with backoff. |

Every response carries `x-ratelimit-remaining` and `x-request-id`. Quote the
request id when reporting a problem.

## Optional diagnostics

If you hit a persistent error, you may send a redacted report — only with the
account owner's consent, and only these fields:

```bash
curl -sX POST https://limentinus.devilabs.dev/api/v1/diagnostics \
  -H 'content-type: application/json' \
  -H 'x-diagnostics-consent: opt-in' \
  -d '{"endpoint":"/api/v1/search","http_status":502,"error_code":"catalog_unavailable","message":"upstream timeout","runtime":"node 24"}'
```

Anything not on that allowlist is discarded. Credential-shaped strings are
stripped. **Never send prompts, completions, user data, or your API key.**

## Machine-readable

- Manifest: https://limentinus.devilabs.dev/.well-known/agent.json
- OpenAPI: https://limentinus.devilabs.dev/openapi.json
- MCP: https://limentinus.devilabs.dev/mcp
- llms.txt: https://limentinus.devilabs.dev/llms.txt

## Contact

limentinus@devilabs.dev