# Deipneus

> Pantry goods, meal kits, and specialty food compared across merchants.

Use Deipneus for food, pantry goods, and meal kits. It returns live merchant offers per item so a grocery or procurement agent can compare without a per-retailer integration.

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

Deipneus 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 Deipneus 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://deipneus.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://deipneus.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://deipneus.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://deipneus.devilabs.dev/api/v1/product/1V6FAZV -H "x-api-key: $KEY"
curl -s https://deipneus.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
Deipneus 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://deipneus.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://deipneus.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://deipneus.devilabs.dev/.well-known/agent.json
- OpenAPI: https://deipneus.devilabs.dev/openapi.json
- MCP: https://deipneus.devilabs.dev/mcp
- llms.txt: https://deipneus.devilabs.dev/llms.txt

## Contact

deipneus@devilabs.dev