Reference data
Geo data (countries, states, cities), currencies, and the public platform config.
Lookup data that storefronts, order forms and apps read constantly: geo (countries → states/wilayas → cities), currencies, and the assembled platform config. Reads are public — no token needed — which is what lets anonymous storefront visitors fill shipping forms. Writes exist on the same resources but are restricted to platform admins.
Countries
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /v1/countries | List, ordered by name (default limit 1000) | Public |
| GET | /v1/countries/{code} | One country — code is ISO 3166-1 alpha-2, case-insensitive | Public |
| POST | /v1/countries | Create (platform admin) | Bearer |
| PUT | /v1/countries/{code} | Update (platform admin) | Bearer |
| DELETE | /v1/countries/{code} | Delete (platform admin) | Bearer |
States
States (wilayas in Algeria) key on country_code + code. The flat list is the everyday read;
the nested routes under a country exist for compatibility and for mutations.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /v1/states | Flat list — filter with country_code (or countryCode), ordered by code | Public |
| GET | /v1/countries/{country_code}/states | Nested list (same data) | Public |
| GET | /v1/countries/{country_code}/states/{code} | One state | Public |
| POST | /v1/countries/{country_code}/states | Create (platform admin) | Bearer |
| PUT | /v1/countries/{country_code}/states/{code} | Update (platform admin) | Bearer |
| DELETE | /v1/countries/{country_code}/states/{code} | Delete (platform admin) | Bearer |
# the 58 Algerian wilayas for a shipping form
curl "https://api.feeef.org/v1/states?country_code=DZ"Cities
Cities key on country_code + state_code + name (the name is the identifier in nested
routes). For type-ahead inputs use the dedicated search endpoint.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /v1/cities | Flat list — filter with country_code, state_code; ordered by name | Public |
| GET | /v1/cities/search | Autocomplete — q plus optional country_code, state_code; max 20 rows | Public |
| GET | /v1/countries/{country_code}/states/{state_code}/cities | Nested list | Public |
| GET | /v1/countries/{country_code}/states/{state_code}/cities/{name} | One city | Public |
| POST | /v1/countries/{country_code}/states/{state_code}/cities | Create (platform admin) | Bearer |
| PUT | /v1/countries/{country_code}/states/{state_code}/cities/{name} | Update (platform admin) | Bearer |
| DELETE | /v1/countries/{country_code}/states/{state_code}/cities/{name} | Delete (platform admin) | Bearer |
Search returns slim rows (country_code, state_code, name, metadata) — enough to fill an
order's shipping fields.
curl "https://api.feeef.org/v1/cities/search?q=bab&country_code=DZ&state_code=16"Currencies
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /v1/currencies | List, ordered by name (default limit 50) | Public |
| GET | /v1/currencies/{code} | One currency — code is the ISO code, case-insensitive | Public |
| POST | /v1/currencies | Create (platform admin) | Bearer |
| PUT | /v1/currencies/{code} | Update (platform admin) | Bearer |
| DELETE | /v1/currencies/{code} | Delete (platform admin) | Bearer |
Both SDKs wrap this as a standard resource: ff.currencies.list() /
ff.currencies.find({ id: 'DZD' }) in JavaScript, ff.currencies.list() /
ff.currencies.find(id: 'DZD') in Dart. Note that per-store display currencies and exchange
rates live on the store itself — this table is the platform-wide catalog.
Platform config
One public endpoint assembles the whole platform configuration that apps read at startup. The
values are managed by platform admins through an internal options store; GET /v1/configs
exposes the merged, read-only result.
| Method | Path | Description | Auth |
|---|---|---|---|
| GET | /v1/configs | Assembled app config (see fields below) | Public |
| Field | Contents |
|---|---|
update | Minimum / forced app versions + release notes |
popups | In-app announcement popups with display strategy |
features | Feature flags — each has active and a platform rules expression |
plans | Active subscription plans |
payments | Wallet top-up methods (automatic gateways + manual instructions) |
storePaymentMethods | Payment methods stores can offer their customers |
currencies | Currency display configs (code, symbol, precision, defaultRate) |
languages | Supported languages (with RTL flags) |
aiModels, models | AI model catalog + pricing used for AI billing |
integrations | Integration catalog pricing + billing rules |
extra | Misc platform limits (e.g. max due, support contact) |
curl "https://api.feeef.org/v1/configs"Caching
These endpoints don't emit cache-control headers, but the data is quasi-static:
- Geo and currencies change only when platform admins edit them — safe to cache client-side (or in your own edge cache) for hours and refresh lazily. Ship the DZ wilaya list with your app if you want zero-latency shipping forms, and reconcile in the background.
- Configs change on ops updates (feature flags, pricing). Fetch once per app session; the
Dart SDK's
ff.configsdoes exactly that (in-memory cache,fetch()returns the cached value on later calls). Poll or re-fetch on app foreground if you gate features on it. image_prompt_templatesreads (see AI) are cached server-side as well.
For conventions shared by every endpoint — pagination envelopes, filtering, errors — see API conventions.