Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/floriansalvi/HEIG-VD_Ocha-api/llms.txt

Use this file to discover all available pages before exploring further.

The Ocha API uses query parameters for pagination and filtering across listing endpoints. All paginated responses share a consistent shape — page, totalPages, a total-count field, and an array of items — making it straightforward to build paginated UIs or iterate through results programmatically.

​
Pagination

Pagination is supported on GET /api/v1/products, GET /api/v1/stores, and GET /api/v1/users/orders. Two query parameters control it:
ParameterTypeDefaultDescription
pageinteger1Page number to retrieve
limitinteger10Number of items returned per page

​
Paginated response shape

All paginated listing endpoints return the same envelope structure: 
{
  "message": "List of products",
  "page": 2,
  "totalPages": 5,
  "totalProducts": 47,
  "products": [ ]
}
For stores the count field is totalStores; for orders it is totalOrders.

​
Example: paginate products

curl "https://api.example.com/api/v1/products?page=2&limit=5"

{
  "message": "List of products",
  "page": 2,
  "totalPages": 10,
  "totalProducts": 98,
  "products": [
    {
      "_id": "64f1c2e9a1b2c3d4e5f12345",
      "name": "Matcha Latte",
      "basePriceCHF": 5.00,
      "isActive": true
    }
  ]
}

​
Example: paginate stores

curl "https://api.example.com/api/v1/stores?page=1&limit=5"

​
Example: paginate the authenticated user’s orders

curl "https://api.example.com/api/v1/users/orders?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Filtering products by active status

Pass ?active=true to restrict the product listing to active products only. The filter maps to the isActive field on the product document.
Only active=true has an effect. Omitting the parameter — or passing active=false — returns all products regardless of their active status.
curl "https://api.example.com/api/v1/products?active=true"

{
  "message": "List of products",
  "page": 1,
  "totalPages": 3,
  "totalProducts": 24,
  "products": [
    {
      "_id": "64f1c2e9a1b2c3d4e5f12345",
      "name": "Matcha Latte",
      "isActive": true
    }
  ]
}
GET /api/v1/stores accepts a near parameter to return stores sorted by proximity to a given coordinate. When near is present, pagination parameters are ignored and the response contains all matching stores up to the specified radius.
ParameterTypeDefaultDescription
nearstring—Coordinates in lng,lat format (e.g. 6.93,46.99)
radiusinteger10000Maximum distance in meters from the target point
Longitude comes before latitude in the near value, matching the GeoJSON coordinate order. Swapping them returns incorrect results.
# Stores within 5 km of coordinates 6.93, 46.99
curl "https://api.example.com/api/v1/stores?near=6.93,46.99&radius=5000"

{
  "message": "Nearby stores",
  "totalStores": 2,
  "stores": [
    {
      "_id": "64f1c2e9a1b2c3d4e5f67890",
      "name": "Ocha Neuchâtel",
      "location": {
        "type": "Point",
        "coordinates": [6.93, 46.99]
      }
    }
  ]
}
Geolocation queries do not return page or totalPages in the response — only totalStores and the stores array.

​
Combining parameters

You can combine the active filter with page and limit on the products endpoint: 
# Active products, page 2, 3 items per page
curl "https://api.example.com/api/v1/products?active=true&page=2&limit=3"

{
  "message": "List of products",
  "page": 2,
  "totalPages": 8,
  "totalProducts": 24,
  "products": [ ]
}

​
Next steps

Products API

Full reference for the products listing endpoint and its query parameters.

Stores API

Full reference for the stores listing endpoint including geolocation search.

User orders

Reference for the authenticated user’s paginated order history.

Roles and permissions

Understand which endpoints require authentication or admin access.

Build docs developers (and LLMs) love

Get started for freeTalk to us