API reference

Every endpoint of the Data API, generated from its OpenAPI document. Each answer is JSON unless it says otherwise.

Base URL: https://pricana.io/api/v1
Authentication: Your API key as a bearer token: Authorization: Bearer prc_live_…. Live keys read your datasets, test keys only the sample datasets. Create keys in the portal (API).
OpenAPI document: OpenAPI 3.1.0 (Pricana Data API v1)

API key

Requests go to this server with your key. The key stays in this page’s memory only.

Datasets

What you can read: your datasets and the values to filter them by.

GET `/api/v1/datasets`

Your datasets

The datasets your plan lets you read, with how many items and websites each has and when its sources were last read. Their id is the dataset filter of the other requests.

Responses

200 Your datasets. application/json Dataset[]
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

[
  {
    "description": "Laptops and notebooks from shops in Germany, Austria and Switzerland.",
    "healthyModels": 14,
    "id": 12,
    "items": 18342,
    "models": 14,
    "name": "Laptops DACH",
    "newestScrapeAt": "2026-10-07T09:12:00Z",
    "oldestScrapeAt": "2026-10-07T05:40:00Z",
    "sites": 9
  }
]

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/datasets"

Try it

GET `/api/v1/facets`

Websites, categories and currencies to filter by

The values the items can be filtered by, each with the number of items listed now.

Parameters

Name	Type	Description
`dataset` query	integer	One of your datasets (its `id` from `/datasets`); without it, all of them. Example: `12`

Responses

200 The facets. application/json Facets
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
404 No such dataset of yours. application/json Error
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "categories": [
    {
      "id": 8,
      "items": 1804,
      "name": "Laptops",
      "parentId": 2,
      "path": "Computers > Laptops",
      "slug": "computers-laptops"
    }
  ],
  "currencies": [
    {
      "code": "EUR",
      "items": 17920
    }
  ],
  "sites": [
    {
      "host": "www.notebookshop.example",
      "id": 4,
      "items": 2310,
      "name": "Notebookshop"
    }
  ]
}

Try it

Items

Listings as they are now, and their history.

GET `/api/v1/items`

Find items

Items of your datasets, filtered and sorted, a page at a time (up to 500). To keep a copy in sync, use the change feed (/changes) or changedSince.

Parameters

Name	Type	Description
`dataset` query	integer	One of your datasets (its `id` from `/datasets`); without it, all of them. Example: `12`
`site` query	integer	Only items of this website (`id` from `/facets`). Example: `4`
`category` query	string	A category's slug (from `/facets`), with its subcategories. Example: `computers-laptops`
`q` query	string	Words to look for (all of them, in any order) in the title, brand, codes and other values of the item; parts of words count. Example: `thinkpad x1`
`minPrice` query	number	Lowest price, in the item's currency. Example: `500`
`maxPrice` query	number	Highest price, in the item's currency. Example: `1500`
`currency` query	string	ISO 4217 code. Example: `EUR`
`status` query	string, one of active, removed, all	`active` (listed now, the default), `removed` (no longer listed) or `all`.
`changedSince` query	string (date-time)	Only items with a change after this time (ISO 8601), e.g. the start of your last sync. Example: `2026-10-01T00:00:00Z`
`gtin` query	string	EAN/UPC/ISBN-13: the same product in every shop (leading zeros may be left out). Example: `0196802123456`
`sort` query	string, one of price, -price, -lastChanged, -lastSeen, -firstSeen, title	`price`, `-price` (highest first), `-lastChanged` (the default), `-lastSeen`, `-firstSeen` (newest listings first) or `title`.
`page` query	integer	The page, from 0. Example: `0` default: `0`
`size` query	integer	Items per page, 1 to 500. Example: `100` default: `50`

Responses

200 A page of items. application/json PageDtoItem
400 A parameter is not valid; message says which. application/json Error
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "content": [
    {
      "attributes": {
        "availability": "in stock",
        "shipping": 0
      },
      "brand": "Lenovo",
      "category": {
        "name": null,
        "path": null,
        "slug": null,
        "source": null
      },
      "currency": "EUR",
      "datasets": [
        "Laptops DACH"
      ],
      "firstSeenAt": "2026-09-01T10:00:00Z",
      "gtin": "0196802123456",
      "id": 77,
      "image": "https://www.notebookshop.example/img/thinkpad-x1.jpg",
      "lastChangedAt": "2026-10-06T21:03:00Z",
      "lastSeenAt": "2026-10-07T09:12:00Z",
      "mpn": "21KC004MGE",
      "previousPrice": 1499,
      "price": 1399,
      "priceChangedAt": "2026-10-06T21:03:00Z",
      "removedAt": "2026-10-07T03:30:00Z",
      "site": {
        "attribution": null,
        "host": null,
        "id": null,
        "name": null
      },
      "source": {
        "modelId": null,
        "name": null
      },
      "title": "Lenovo ThinkPad X1 Carbon Gen 12",
      "url": "https://www.notebookshop.example/p/thinkpad-x1"
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1804,
  "totalPages": 37
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/items"

Try it

GET `/api/v1/items/{id}`

One item

The item as it is now (as /items shows it), also once it is no longer listed.

Parameters

Name	Type	Description
`id` path, required	integer	The item's `id`. Example: `77`

Responses

200 The item. application/json Item
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
404 Not found among the items you can see. application/json Error
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "attributes": {
    "availability": "in stock",
    "shipping": 0
  },
  "brand": "Lenovo",
  "category": {
    "name": "Laptops",
    "path": "Computers > Laptops",
    "slug": "computers-laptops",
    "source": "AI"
  },
  "currency": "EUR",
  "datasets": [
    "Laptops DACH"
  ],
  "firstSeenAt": "2026-09-01T10:00:00Z",
  "gtin": "0196802123456",
  "id": 77,
  "image": "https://www.notebookshop.example/img/thinkpad-x1.jpg",
  "lastChangedAt": "2026-10-06T21:03:00Z",
  "lastSeenAt": "2026-10-07T09:12:00Z",
  "mpn": "21KC004MGE",
  "previousPrice": 1499,
  "price": 1399,
  "priceChangedAt": "2026-10-06T21:03:00Z",
  "removedAt": "2026-10-07T03:30:00Z",
  "site": {
    "attribution": "Source: European Commission, Weekly Oil Bulletin, CC BY 4.0",
    "host": "www.notebookshop.example",
    "id": 4,
    "name": "Notebookshop"
  },
  "source": {
    "modelId": 31,
    "name": "Notebookshop – Laptops"
  },
  "title": "Lenovo ThinkPad X1 Carbon Gen 12",
  "url": "https://www.notebookshop.example/p/thinkpad-x1"
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/items/77"

Try it

GET `/api/v1/items/{id}/history`

An item's history

Every change of the item within your plan's history, oldest first: its prices over time.

Parameters

Name	Type	Description
`id` path, required	integer	The item's `id`. Example: `77`

Responses

200 The item's history. application/json HistoryEntry[]
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
404 Not found among the items you can see. application/json Error
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

[
  {
    "changes": {
      "availability": [
        "2-3 days",
        "in stock"
      ]
    },
    "id": 812,
    "kind": "NEW",
    "observedAt": "2026-10-06T21:03:00Z",
    "previousPrice": 1499,
    "price": 1399
  }
]

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/items/77/history"

Try it

Changes

Every new item, change and removal, in order: to keep a copy in sync.

GET `/api/v1/changes`

The change feed

Everything that happened after after, oldest first. Start with after=0, then pass each answer's nextCursor as after; repeat while hasMore is true. Store the last cursor and go on from it next time: you get each change exactly once. Changes show here about 30 seconds after they happen. Paid plans (on Free it answers 402).

Parameters

Name	Type	Description
`dataset` query	integer	One of your datasets (its `id` from `/datasets`); without it, all of them. Example: `12`
`after` query	integer	The cursor: the `nextCursor` of the last answer (0 = from the beginning of your plan's history). Example: `0` default: `0`
`limit` query	integer	Changes per answer, 1 to 1000. Example: `1000` default: `500`

Responses

200 The next changes. application/json ChangePage
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "changes": [
    {
      "changes": {
        "price": [
          1499,
          1399
        ]
      },
      "id": 812,
      "item": {
        "currency": null,
        "id": null,
        "site": null,
        "title": null,
        "url": null
      },
      "kind": "NEW",
      "observedAt": "2026-10-06T21:03:00Z",
      "previousPrice": 1499,
      "price": 1399
    }
  ],
  "hasMore": true,
  "nextCursor": 1811
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/changes"

Try it

GET `/api/v1/changes/recent`

Recent changes, newest first

For people: the latest changes, newest first, optionally only of one kind. Page back with before. To sync a copy, use /changes. A change shows here when it shows in /changes (within about 30 seconds), so the id of the newest one is a safe place to start /changes?after= from.

Parameters

Name	Type	Description
`dataset` query	integer	One of your datasets (its `id` from `/datasets`); without it, all of them. Example: `12`
`kind` query	string, one of NEW, CHANGED, REMOVED, RELISTED, PRICE_DROP, PRICE_RISE	NEW, CHANGED, REMOVED, RELISTED, PRICE_DROP or PRICE_RISE.
`before` query	integer	The last `id` of the previous page. Example: `1811`
`limit` query	integer	Changes per answer, 1 to 200. Example: `50` default: `50`

Responses

200 The changes. application/json ChangePage
400 A parameter is not valid; message says which. application/json Error
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "changes": [
    {
      "changes": {
        "price": [
          1499,
          1399
        ]
      },
      "id": 812,
      "item": {
        "currency": null,
        "id": null,
        "site": null,
        "title": null,
        "url": null
      },
      "kind": "NEW",
      "observedAt": "2026-10-06T21:03:00Z",
      "previousPrice": 1499,
      "price": 1399
    }
  ],
  "hasMore": true,
  "nextCursor": 1811
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/changes/recent"

Try it

Products

The same product across shops: compare its prices.

GET `/api/v1/products`

Find products across shops

Products with offers in your datasets: the same product in several shops, matched by GTIN, else by brand and part number, with its price range and how many shops sell it.

Parameters

Name	Type	Description
`dataset` query	integer	One of your datasets (its `id` from `/datasets`); without it, all of them. Example: `12`
`q` query	string	Words to look for (all of them, in any order) in the title, brand, codes and other values of the item; parts of words count. Example: `thinkpad`
`category` query	string	A category's slug (from `/facets`), with its subcategories. Example: `computers-laptops`
`brand` query	string	The brand, as the shops name it. Example: `Lenovo`
`gtin` query	string	EAN/UPC/ISBN-13: the same product in every shop (leading zeros may be left out). Example: `0196802123456`
`currency` query	string	ISO 4217 code. Example: `EUR`
`minShops` query	integer	Sold by at least this many websites (2: products to compare). Example: `2` default: `1`
`sort` query	string, one of -offers, -shops, price, -price	`-offers` (the default), `-shops`, `price` (lowest first) or `-price`.
`page` query	integer	The page, from 0. Example: `0` default: `0`
`size` query	integer	Products per page, 1 to 200. Example: `50` default: `50`

Responses

200 A page of products. application/json PageDtoProduct
400 A parameter is not valid; message says which. application/json Error
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "content": [
    {
      "brand": "Lenovo",
      "category": {
        "name": null,
        "path": null,
        "slug": null,
        "source": null
      },
      "gtin": "0196802123456",
      "id": "0196802123456",
      "mpn": "21KC004MGE",
      "offers": 6,
      "prices": [
        null
      ],
      "shops": 5,
      "title": "Lenovo ThinkPad X1 Carbon Gen 12"
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1804,
  "totalPages": 37
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/products"

Try it

GET `/api/v1/products/{id}`

One product with its offers

A product by its id (a GTIN, or a brand-MPN key) with all its offers you can see, cheapest first.

Parameters

Name	Type	Description
`id` path, required	string	The product's `id`: a GTIN (any of its forms) or a brand-MPN key. Example: `0196802123456`
`dataset` query	integer	One of your datasets (its `id` from `/datasets`); without it, all of them. Example: `12`
`currency` query	string	Only offers in this currency (ISO 4217). Example: `EUR`

Responses

200 The product and its offers. application/json ProductDetail
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
404 No offers of this product among the items you can see. application/json Error
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "offers": [
    {
      "attributes": {
        "availability": "in stock",
        "shipping": 0
      },
      "brand": "Lenovo",
      "category": {
        "name": null,
        "path": null,
        "slug": null,
        "source": null
      },
      "currency": "EUR",
      "datasets": [
        "Laptops DACH"
      ],
      "firstSeenAt": "2026-09-01T10:00:00Z",
      "gtin": "0196802123456",
      "id": 77,
      "image": "https://www.notebookshop.example/img/thinkpad-x1.jpg",
      "lastChangedAt": "2026-10-06T21:03:00Z",
      "lastSeenAt": "2026-10-07T09:12:00Z",
      "mpn": "21KC004MGE",
      "previousPrice": 1499,
      "price": 1399,
      "priceChangedAt": "2026-10-06T21:03:00Z",
      "removedAt": "2026-10-07T03:30:00Z",
      "site": {
        "attribution": null,
        "host": null,
        "id": null,
        "name": null
      },
      "source": {
        "modelId": null,
        "name": null
      },
      "title": "Lenovo ThinkPad X1 Carbon Gen 12",
      "url": "https://www.notebookshop.example/p/thinkpad-x1"
    }
  ],
  "product": {
    "brand": "Lenovo",
    "category": {
      "name": "Laptops",
      "path": "Computers > Laptops",
      "slug": "computers-laptops",
      "source": "AI"
    },
    "gtin": "0196802123456",
    "id": "0196802123456",
    "mpn": "21KC004MGE",
    "offers": 6,
    "prices": [
      {
        "currency": null,
        "max": null,
        "min": null,
        "offers": null
      }
    ],
    "shops": 5,
    "title": "Lenovo ThinkPad X1 Carbon Gen 12"
  }
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/products/0196802123456"

Try it

Export

Everything at once, as CSV or NDJSON.

GET `/api/v1/export`

Export items

All matching items, streamed as CSV (UTF-8, a header row) or NDJSON (one JSON object per line), with the filters of /items. Rows count against your plan's export rows per month. On paid plans, rows beyond them are billed as overage per started 10,000 and the export is complete (X-Export-Overage); on Free, in the trial, or with overage switched off, an export that would go beyond them ends at the limit and says so in X-Export-Truncated.

Parameters

Name	Type	Description
`format` query	string, one of csv, ndjson	`csv` (the default) or `ndjson`.
`dataset` query	integer	One of your datasets (its `id` from `/datasets`); without it, all of them. Example: `12`
`site` query	integer	Only items of this website (`id` from `/facets`). Example: `4`
`category` query	string	A category's slug (from `/facets`), with its subcategories. Example: `computers-laptops`
`q` query	string	Words to look for (all of them, in any order) in the title, brand, codes and other values of the item; parts of words count. Example: `thinkpad`
`minPrice` query	number	Lowest price, in the item's currency. Example: `500`
`maxPrice` query	number	Highest price, in the item's currency. Example: `1500`
`currency` query	string	ISO 4217 code. Example: `EUR`
`status` query	string, one of active, removed, all	`active` (listed now, the default), `removed` (no longer listed) or `all`.
`changedSince` query	string (date-time)	Only items with a change after this time (ISO 8601), e.g. the start of your last sync. Example: `2026-10-01T00:00:00Z`
`gtin` query	string	EAN/UPC/ISBN-13: the same product in every shop (leading zeros may be left out). Example: `0196802123456`

Responses

200 The rows, streamed. application/x-ndjson string text/csv string
- X-Export-Matching: With X-Export-Truncated: how many rows matched.
- X-Export-Overage: true if rows beyond the month's quota are in it, billed as overage.
- X-Export-Rows: Rows in this export.
- X-Export-Rows-Remaining: Export rows left this month after it.
- X-Export-Truncated: true if the export ended at the monthly limit.
400 A parameter is not valid; message says which. application/json Error
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/export"

Try it

Only the start of the answer is read and shown, and the export stops there; the rows it wrote still count against your month’s export rows. Filters keep it small.

Plan

Your plan, its limits and this month's use.

GET `/api/v1/plan`

Your plan and this month's use

The plan in effect, its limits (null is unlimited), the calls and export rows used this month and when they start over. Every answer also carries RateLimit-* and X-Quota-* headers.

Responses

200 Your plan. application/json PlanInfo
401 No API key, or one that is invalid or revoked. application/json Error
402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Example

{
  "limits": {
    "datasets": 10,
    "apiCallsPerMonth": 250000,
    "ratePerSecond": 20,
    "delayHours": 0,
    "historyDays": 365,
    "exportRowsPerMonth": 1000000,
    "changeFeed": true,
    "webhooks": true
  },
  "lockedDatasets": 0,
  "name": "Pro",
  "plan": "pro",
  "status": "ACTIVE",
  "trialEndsAt": "2026-10-21T09:00:00Z",
  "upgradeUrl": "https://pricana.io/pricing",
  "usage": {
    "apiCalls": 48211,
    "exportRows": 12000,
    "resetsAt": "2026-11-01T00:00:00Z"
  }
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/plan"

Try it

Webhooks

Pricana sends these to your endpoint. Set endpoints up in the portal (API); the guide explains the signature. Webhooks guide

POST `https://your-server.example/…`

New changes of the change feed (sent by Pricana)

Pricana posts the next changes of your datasets to your endpoint, in order, up to 100 at a time, as the change feed lists them (type: changes), and a test when you send one from the portal (type: ping). Check the signature before you use the body: HMAC-SHA256 with your endpoint's secret over <t>.<body>, compared with each v1 value. Answer with any 2xx within 10 seconds; anything else is tried again after 1, 5, 15 and 30 minutes, then 1, 2 and every 4 hours, and later changes wait. After 24 hours of failures the endpoint is turned off and your team gets an email.

Parameters

Name	Type	Description
`Pricana-Signature` header, required	string	`t=<unix seconds>,v1=<hex HMAC-SHA256>`; a second `v1` while a rolled secret's old one is still valid. Example: `t=1791374400,v1=26ff918ca24488a1a2aa21935c219eaed5c31c721399ca4d400ebecf2784fdf4`
`Pricana-Event-Id` header, required	string	The event's id, as `id` in the body. Example: `evt_5f1c0b2a9d7e4c3b8a6f0e1d`
`Pricana-Event-Type` header, required	string	`changes` or `ping`. Example: `changes`
`Pricana-Delivery-Attempt` header, required	integer	1 for the first attempt, then 2, 3 … Example: `1`

Body Pricana sends: WebhookEvent

{
  "changes": [
    {
      "changes": {
        "price": [
          1499,
          1399
        ]
      },
      "id": 812,
      "item": {
        "currency": null,
        "id": null,
        "site": null,
        "title": null,
        "url": null
      },
      "kind": "NEW",
      "observedAt": "2026-10-06T21:03:00Z",
      "previousPrice": 1499,
      "price": 1399
    }
  ],
  "createdAt": "2026-10-07T09:12:31Z",
  "cursor": 1811,
  "id": "evt_5f1c0b2a9d7e4c3b8a6f0e1d",
  "type": "changes"
}

Responses

200 Received (any 2xx will do; the body is ignored).
default Anything else (and no answer in 10 seconds): tried again later.

Data model

CategoryRef

The item's category in Pricana's taxonomy.

Name	Type	Description
`name`	string	Example: `"Laptops"`
`path`	string	Example: `"Computers > Laptops"`
`slug`	string	Example: `"computers-laptops"`
`source`	string, one of AI, MANUAL	Who chose it (EU AI Act transparency): AI, or MANUAL (a person). Example: `"AI"`

Change

One entry of the change feed: an item appeared (NEW), changed (CHANGED), was no longer listed (REMOVED) or came back (RELISTED). id is the cursor.

Name	Type	Description
`changes`	object	Values that changed, by name: [old, new]. Example: `{"price":[1499,1399]}`
`id`	integer	Increasing: pass the last one you have as `after`. Example: `812`
`item`	ChangeItem	Null if the item is gone from your data meanwhile.
`kind`	string, one of NEW, CHANGED, REMOVED, RELISTED
`observedAt`	string (date-time)	Example: `"2026-10-06T21:03:00Z"`
`previousPrice`	number \| null	Set when the price changed. Example: `1499`
`price`	number \| null	Example: `1399`

ChangeItem

The item a change belongs to (its title and link then).

Name	Type	Description
`currency`	string \| null	Example: `"EUR"`
`id`	integer	Example: `77`
`site`	SiteRef
`title`	string	Example: `"Lenovo ThinkPad X1 Carbon Gen 12"`
`url`	string \| null	Example: `"https://www.notebookshop.example/p/thinkpad-x1"`

ChangePage

A page of changes. Pass nextCursor on to get the next entries: as after to /changes, as before to /changes/recent.

Name	Type	Description
`changes`	Change[]
`hasMore`	boolean	More changes are waiting now: ask again at once. Example: `true`
`nextCursor`	integer	Store it, and continue from it next time (`after` for `/changes`, `before` for `/changes/recent`). Example: `1811`

Dataset

A dataset: the listings of a set of websites on one topic, as your plan shows them.

Name	Type	Description
`description`	string \| null	Example: `"Laptops and notebooks from shops in Germany, Austria and Switzerland."`
`healthyModels`	integer	Sources collecting without problems; the others are being repaired. Example: `14`
`id`	integer	Use it as `dataset` in other requests. Example: `12`
`items`	integer	Items listed now. Example: `18342`
`models`	integer	Sources: one listing of one website each. Example: `14`
`name`	string	Example: `"Laptops DACH"`
`newestScrapeAt`	string (date-time) \| null	When a source of the dataset was last read; null before the first. Example: `"2026-10-07T09:12:00Z"`
`oldestScrapeAt`	string (date-time) \| null	When the source read longest ago was read. Example: `"2026-10-07T05:40:00Z"`
`sites`	integer	Websites the items come from. Example: `9`

Error

Every error answer.

Name	Type	Description
`docsUrl`	string	The docs' page about this error. Example: `"https://pricana.io/docs/errors#not-found"`
`error`	string	Example: `"Not Found"`
`message`	string	Example: `"Item 77 not found"`
`status`	integer	Example: `404`

FacetCategory

A category among the facets, with its items (subcategories included).

Name	Type	Description
`id`	integer	Example: `8`
`items`	integer	Example: `1804`
`name`	string	Example: `"Laptops"`
`parentId`	integer \| null	Null for a top category. Example: `2`
`path`	string	Example: `"Computers > Laptops"`
`slug`	string	Example: `"computers-laptops"`

FacetCurrency

A currency among the facets, with its items.

Name	Type	Description
`code`	string	Example: `"EUR"`
`items`	integer	Example: `17920`

What the items can be filtered by, with counts.

Name	Type	Description
`categories`	FacetCategory[]
`currencies`	FacetCurrency[]
`sites`	FacetSite[]

FacetSite

A website among the facets, with its items.

Name	Type	Description
`host`	string	Example: `"www.notebookshop.example"`
`id`	integer	Example: `4`
`items`	integer	Example: `2310`
`name`	string	Example: `"Notebookshop"`

HistoryEntry

One step in an item's history.

Name	Type	Description
`changes`	object	Values that changed, by name: [old, new]. Example: `{"availability":["2-3 days","in stock"]}`
`id`	integer	Example: `812`
`kind`	string, one of NEW, CHANGED, REMOVED, RELISTED
`observedAt`	string (date-time)	Example: `"2026-10-06T21:03:00Z"`
`previousPrice`	number \| null	Set when the price changed. Example: `1499`
`price`	number \| null	Example: `1399`

Item

A listing (an offer of a product in a shop), as it is now: the shop's own values, with Pricana's category and the product codes that identify it across shops.

Name	Type	Description
`attributes`	object	Further values the shop shows (stock, shipping, ratings …), by name. Example: `{"availability":"in stock","shipping":0}`
`brand`	string \| null	Example: `"Lenovo"`
`category`	CategoryRef	Null while it has none.
`currency`	string \| null	Example: `"EUR"`
`datasets`	string[]	Your datasets the item is in. Example: `["Laptops DACH"]`
`firstSeenAt`	string (date-time)	Example: `"2026-09-01T10:00:00Z"`
`gtin`	string \| null	EAN/UPC/ISBN-13 (8, 13 or 14 digits): the same product in every shop. Null when the shop doesn't name it. Example: `"0196802123456"`
`id`	integer	Example: `77`
`image`	string \| null	The shop's product image, if it shows one. Example: `"https://www.notebookshop.example/img/thinkpad-x1.jpg"`
`lastChangedAt`	string (date-time)	The last time a value changed (use it with `changedSince`). Example: `"2026-10-06T21:03:00Z"`
`lastSeenAt`	string (date-time)	The last time a scrape found it. Example: `"2026-10-07T09:12:00Z"`
`mpn`	string \| null	The manufacturer's part number. Example: `"21KC004MGE"`
`previousPrice`	number \| null	The price before the last price change; null if it never changed. Example: `1499`
`price`	number \| null	Null when the shop shows none. Example: `1399`
`priceChangedAt`	string (date-time) \| null	When the price last changed. Example: `"2026-10-06T21:03:00Z"`
`removedAt`	string (date-time) \| null	When the shop stopped listing it; null while it is listed. Example: `"2026-10-07T03:30:00Z"`
`site`	SiteRef
`source`	Source
`title`	string \| null	Example: `"Lenovo ThinkPad X1 Carbon Gen 12"`
`url`	string \| null	The item's page in the shop. Example: `"https://www.notebookshop.example/p/thinkpad-x1"`

LimitError

A plan limit (402) or a rate or monthly limit (429): which one, its value in your plan, and where to upgrade.

Name	Type	Description
`allowed`	object	Its value in your plan. Example: `100000`
`docsUrl`	string	Example: `"https://pricana.io/docs/errors#apiCallsPerMonth"`
`error`	string	Example: `"Too Many Requests"`
`limit`	string	The limit: datasets, changeFeed, apiCallsPerMonth, ratePerSecond, exportRowsPerMonth or paymentOverdue. Example: `"apiCallsPerMonth"`
`message`	string	Example: `"The monthly quota of 100,000 calls is used up; it starts over on 1 November"`
`plan`	string	Example: `"pro"`
`status`	integer	Example: `429`
`upgradeUrl`	string	Example: `"https://pricana.io/pricing"`

PageDtoItem

A page of results.

Name	Type	Description
`content`	Item[]
`page`	integer	This page, from 0. Example: `0`
`size`	integer	Results per page. Example: `50`
`totalElements`	integer	All results. Example: `1804`
`totalPages`	integer	Pages in all. Example: `37`

PageDtoProduct

A page of results.

Name	Type	Description
`content`	Product[]
`page`	integer	This page, from 0. Example: `0`
`size`	integer	Results per page. Example: `50`
`totalElements`	integer	All results. Example: `1804`
`totalPages`	integer	Pages in all. Example: `37`

PlanInfo

Your plan in effect (Free once a trial ended), its limits and this month's use.

Name	Type	Description
`limits`	object	The limits by name; null is unlimited. Example: `{"datasets":10,"apiCallsPerMonth":250000,"ratePerSecond":20,"delayHours":0,"historyDays":365,"exportRowsPerMonth":1000000,"changeFeed":true,"webhooks":true}`
`lockedDatasets`	integer	Your datasets beyond what the plan includes: they answer 402. Example: `0`
`name`	string	Example: `"Pro"`
`plan`	string	Example: `"pro"`
`status`	string \| null	TRIALING, ACTIVE, PAST_DUE or CANCELED; null without a subscription. Example: `"ACTIVE"`
`trialEndsAt`	string (date-time) \| null	When the trial ends (status TRIALING). Example: `"2026-10-21T09:00:00Z"`
`upgradeUrl`	string	Where to get more: the plans and their prices. Example: `"https://pricana.io/pricing"`
`usage`	PlanUsage	This month's use; null for an operator's token.

PlanUsage

Calls with API keys or tokens and exported rows this calendar month (UTC).

Name	Type	Description
`apiCalls`	integer	Example: `48211`
`exportRows`	integer	Example: `12000`
`resetsAt`	string (date-time)	When both start over (the first of next month, 00:00 UTC). Example: `"2026-11-01T00:00:00Z"`

PriceRange

The lowest and highest price of a product's offers in one currency.

Name	Type	Description
`currency`	string	Example: `"EUR"`
`max`	number	Example: `1529`
`min`	number	Example: `1349`
`offers`	integer	Example: `6`

Product

A product across shops: the offers of the same product, matched by GTIN, else by brand and part number.

Name	Type	Description
`brand`	string \| null	Example: `"Lenovo"`
`category`	CategoryRef	Null while it has none.
`gtin`	string \| null	Example: `"0196802123456"`
`id`	string	Its GTIN (digits), else its brand-MPN key. Example: `"0196802123456"`
`mpn`	string \| null	Example: `"21KC004MGE"`
`offers`	integer	Offers (items) of it you can see. Example: `6`
`prices`	PriceRange[]	The price range per currency.
`shops`	integer	Different websites selling it. Example: `5`
`title`	string \| null	Example: `"Lenovo ThinkPad X1 Carbon Gen 12"`

ProductDetail

A product with all its offers, cheapest first.

Name	Type	Description
`offers`	Item[]
`product`	Product

SiteRef

The website an item comes from.

Name	Type	Description
`attribution`	string \| null	The source's licence and credit (open data, e.g. CC BY 4.0): pass it on with its data. Null for other sources. Example: `"Source: European Commission, Weekly Oil Bulletin, CC BY 4.0"`
`host`	string	Example: `"www.notebookshop.example"`
`id`	integer	Example: `4`
`name`	string	Example: `"Notebookshop"`

Source

The source (one listing of one website) an item was read from.

Name	Type	Description
`modelId`	integer	Example: `31`
`name`	string	Example: `"Notebookshop – Laptops"`

WebhookEvent

What your webhook endpoint receives: the next changes of the change feed, in order, up to 100 at a time (type changes), or a test from the portal (type ping, no changes).

Name	Type	Description
`changes`	Change[]
`createdAt`	string (date-time)	Example: `"2026-10-07T09:12:31Z"`
`cursor`	integer \| null	The id of the last change in it (null for a ping): `/changes?after=` goes on from it. Example: `1811`
`id`	string	The same on every attempt and when sent again: drop repeats by it. Example: `"evt_5f1c0b2a9d7e4c3b8a6f0e1d"`
`type`	string, one of changes, ping	Example: `"changes"`

API reference

Datasets

GET /api/v1/datasets

Responses

Example

GET /api/v1/facets

Parameters

Responses

Example

Items

GET /api/v1/items

Parameters

Responses

Example

GET /api/v1/items/{id}

Parameters

Responses

Example

GET /api/v1/items/{id}/history

Parameters

Responses

Example

Changes

GET /api/v1/changes

Parameters

Responses

Example

GET /api/v1/changes/recent

Parameters

Responses

Example

Products

GET /api/v1/products

Parameters

Responses

Example

GET /api/v1/products/{id}

Parameters

Responses

Example

Export

GET /api/v1/export

Parameters

Responses

Plan

GET /api/v1/plan

Responses

Example

Webhooks

POST https://your-server.example/…

Parameters

Body Pricana sends: WebhookEvent

Responses

Data model

CategoryRef

Change

ChangeItem

ChangePage

Dataset

Error

FacetCategory

FacetCurrency

Facets

FacetSite

HistoryEntry

Item

LimitError

PageDtoItem

PageDtoProduct

PlanInfo

PlanUsage

PriceRange

Product

ProductDetail

SiteRef

Source

WebhookEvent

GET `/api/v1/datasets`

GET `/api/v1/facets`

GET `/api/v1/items`

GET `/api/v1/items/{id}`

GET `/api/v1/items/{id}/history`

GET `/api/v1/changes`

GET `/api/v1/changes/recent`

GET `/api/v1/products`

GET `/api/v1/products/{id}`

GET `/api/v1/export`

GET `/api/v1/plan`

POST `https://your-server.example/…`