# Quick start

> Make your first request to the Haszno API in under two minutes. No credentials required — the public demo endpoints are open.

## Before you begin

You need nothing except a terminal or a browser. The public demo endpoints at `https://haszno.com` return synthetic sample data without any credentials. All prices and products are for demonstration purposes only.

## First request — list categories

The `/api/categories` endpoint returns the full category taxonomy. It is unauthenticated and always works.

```bash
curl --fail-with-body \
  'https://haszno.com/api/categories'
```

You will receive an array of 14 category objects. Each object looks like this (abbreviated):

```json
[
  {
    "key": "auto",
    "label": "Autó, gumi és motor",
    "emoji": "🛞",
    "partnerCount": 0,
    "exampleCount": 1,
    "productCount": 100
  },
  {
    "key": "kert",
    "label": "Kert és növény",
    "emoji": "🌿",
    "partnerCount": 0,
    "exampleCount": 1,
    "productCount": 100
  }
]
```

> [!NOTE]
> `partnerCount` is `0` for every category on the public demo. The demo contains example (synthetic) partners only, counted separately in `exampleCount`.

## Filter products by category

The `/api/products` endpoint accepts a `cats` query parameter with a comma-separated list of category keys.

```bash
curl --fail-with-body \
  'https://haszno.com/api/products?cats=kert&shippingMarkets=HU'
```

Each product in the response includes the current selling price, the net wholesale cost, and a `recommended` pricing object computed by the Haszno pricing engine:

```json
{
  "id": 101,
  "category": "kert",
  "name": "Kerti napernyő · 1. változat",
  "sku": "DEMO-101",
  "priceGross": 2190,
  "costNet": 1121,
  "stock": 0,
  "listed": true,
  "recommended": {
    "priceGross": 2090,
    "floorGross": 1590,
    "status": "versenykepes",
    "marginNet": 525,
    "marginPct": 31.9
  },
  "marketByCountry": {
    "hu": {
      "minGross": 2124,
      "shop": "Példa-bolt · HU",
      "source": "mock",
      "isCheapest": true
    },
    "sk": null,
    "eu": null
  }
}
```

All prices are whole integers in Hungarian Forints (HUF). `null` on a price field means unknown, not zero. See [Conventions](conventions.md) for the full currency and field reference.

## The same request in JavaScript

```js
const response = await fetch(
  'https://haszno.com/api/products?cats=kert&shippingMarkets=HU'
);

if (!response.ok) {
  throw new Error(`API error: ${response.status}`);
}

const products = await response.json();

for (const p of products) {
  console.log(p.name, p.recommended.priceGross, 'HUF');
}
```

No dependencies. The API returns `Content-Type: application/json` on all data routes.

## The same request with the CLI

You can run the CLI without installing it permanently using `npx` directly from GitHub:

```bash
npx -y github:haszno-labs/haszno-cli products list --json
```

This prints a JSON array of product objects. Pipe to `jq` to filter:

```bash
npx -y github:haszno-labs/haszno-cli products list --json \
  | jq '.[] | select(.recommended.status == "versenykepes") | .name'
```

> [!TIP]
> `npx` downloads the package from GitHub and installs its dependencies (the built `dist/` is committed in the repo, so nothing is compiled), so the first run is slower.

For the full CLI reference including install, configuration, and all commands, see [CLI reference](cli.md).

## Next steps

- [Authentication](authentication.md) — how to access protected endpoints with HTTP Basic or Bearer tokens.
- [API reference](api-reference.md) — complete endpoint documentation with all parameters and response fields.
- [Errors and rate limits](errors.md) — error response shape and HTTP status codes.
- [Agents overview and quick start](agents.md) — install the CLI, MCP server, or agent skill.