<!-- https://pricto.dev/docs/convenciones · Spanish version: https://pricto.dev/docs/convenciones.md -->

# Conventions

## Base URL and format

Every path hangs from `https://pricto.dev/v1`. Responses are JSON with `data` (the result), `meta` (cost, source, language, currency, notices) and, for lists, `pagination`. New fields are added without notice: ignore the ones you don't know.

## Pagination

By cursor. If `pagination.has_more` is `true`, ask for the next page with `cursor=<pagination.next_cursor>` and the same filters. `limit` has a maximum per endpoint (20 for search).

```json
{
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJvIjoyfQ"
  }
}
```

## Common filters

| Parameter | Filters by | Example |
|---|---|---|
| `country` | Country, ISO 3166-1 | `CL` |
| `retailer` | One or more stores, comma separated | `cl-jumbo,cl-unimarc` |
| `category` | Category, including subcategories | `food.dairy` |
| `brand` | Brand, by id or name | `colun` |
| `location` | Comuna, `CL:<CUT code>` or store, for stores that price by location | `Las Condes` |
| `as_of` | Prices in effect on a past date | `2026-10-01` |
| `from`, `to`, `interval` | History range and interval | `interval=week` |
| `min_confidence`, `match_kinds` | Which offers are grouped with the product (see [Data model](/docs/modelo-de-datos#match)) | `identical,pack` |

## Language

`lang=es` or `lang=en` (or the `Accept-Language` header) changes the language of names, categories, messages and errors. An unsupported language answers in English with a notice, never with an error. The store's original title always comes untranslated in `title_original`.

## Currency

Amounts come in the store's currency (CLP, no decimals). With `currency=USD` (or EUR) every price also carries a `converted` block with the amount, the rate, its date and its source. In history, each point is converted at its own date's rate (`fx_policy: point_date`), or with a single rate if you pass `fx_date`.

## Dates and identifiers

- Dates and times in ISO 8601, UTC (`observed_at`); `observed_local_date` is the date in the store's time zone.
- Ids are opaque and carry a type prefix: `prd_` product, `ofr_` offer, `str_` store, `exp_` export. Stores and categories use readable names: `cl-jumbo`, `food.dairy.milk`.
- Wherever a product is asked for, its barcode (GTIN) is accepted too.

## Headers

| Header | What it carries |
|---|---|
| `X-Request-Id` | Request id, for support |
| `X-Credits-Charged`, `X-Credits-Deduplicated`, `X-Credits-Remaining`, `X-Credits-Period-Reset` | Cost and balance |
| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | Request limit |
| `Retry-After` | On `429` and `503`: how many seconds to wait |

## Versioning

The major version is in the path (`/v1`). Within it there are only additive changes: new fields, parameters or operations. An incompatible change creates `/v2`, and `/v1` stays for at least 12 months, announced with the `Deprecation` and `Sunset` headers. In MCP, a tool's name is part of the contract: if it changes incompatibly, it ships under another name. Changes are published in the [changelog](/docs/changelog).

## Status

`GET /v1/status` (no key) says whether the API is up and the date of the data. The [status](/estado) page shows the same for people.