API overview¶

The API is a read-oriented JSON interface over the analytics database. Two endpoints change state: one updates a cost price, one triggers a data import. Everything else returns data.

Base URL¶

http://<your-server>/api

Behind the shipped Nginx configuration the API listens on port 8000 and is proxied at /api. Calling it directly during development works the same way:

http://localhost:8000/api

Authentication¶

There is none. The API is single-tenant and expects to run on a private network behind a reverse proxy that handles access control. See Restrict access.

CORS is open to all origins, with GET, POST and PATCH allowed.

Interactive documentation¶

FastAPI's generated /docs and /redoc pages are disabled in this application. This reference is the API documentation.

Conventions¶

Response format. Every endpoint returns JSON. Collection endpoints return an array of objects, one per row. Single-value endpoints return one object. There is no envelope, no pagination metadata and no data wrapper.

Empty results. An empty collection is an empty array, not a 404. A query that matches nothing is a valid answer, not an error.

Numbers. Monetary values are rounded server-side, generally to whole units for totals and to one or two decimal places for percentages. They arrive as JSON numbers, not strings.

Nulls. A null means the value is undefined rather than zero, and the distinction carries information. A null ROI means no cost price is recorded; a null week-on-week change means there is no preceding week to compare against. Rendering these as 0 misrepresents them.

Dates. Dates are ISO 8601 (YYYY-MM-DD). Relative windows are calculated from the server's local time, not UTC, so a server in a different timezone to your marketplace account will shift day boundaries.

Common parameters¶

Many endpoints accept the same two filters.

Parameter	Type	Default	Description
`days`	integer	`30`	Size of the lookback window, counted back from now
`source`	string	`all`	`wb`, `ozon`, or `all` for both

An unrecognised source value is treated as all rather than rejected. Endpoints that deviate from these defaults say so in their own reference.

Errors¶

Status	When
`200`	Success, including an empty result set
`400`	Invalid path parameter. Currently only `PATCH .../cost` returns this, when `source` is not `wb` or `ozon`
`422`	A query parameter could not be coerced to its declared type, for example `days=abc`
`500`	Database error

Error bodies follow FastAPI's default shape:

{ "detail": "source must be wb or ozon" }

There are no application-specific error codes.

Rate limits¶

None are enforced. Analytics endpoints run non-trivial aggregate queries against PostgreSQL, so a caller polling several of them in a tight loop will be limited by the database rather than by the API. Treat one request per endpoint per page load as the intended usage pattern.

Endpoint groups¶

Group	Contents
Analytics	Headline figures, profit over time, trends, comparisons, seasonality
Catalogue	Products, cost prices, profitability, ABC classification, rankings
Inventory and listings	Stock levels, reorder status, listing statistics, conversion funnel
Operations	Triggering a sync, checking its status, CSV exports