# Feelpy Health Coach — Full API Reference

> Nutrition intelligence REST API. Base URL: https://feelpy.ru/api/v1

## Authentication

All endpoints require an API key except POST /keys/provision.

### Get a free API key (no auth required)

```
POST /keys/provision
Content-Type: application/json

{"email": "agent@yourproject.com", "name": "My Agent"}
```

Response: `{"data": {"apiKey": "a1b2c3...", "dailyLimit": 1000, "isNew": true}}`

If the email already has an active key, the existing key is returned (isNew: false).

### Use the API key

Add to every request: `Authorization: Bearer <your_api_key>`

Rate limits: 1000 req/day (free). Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

---

## Products (Food Database — 17,000+ items)

### GET /products/search
Search food products by name (Russian or English).
Parameters: q (string, min 4), initial (boolean), category_id (int), page, limit, sort, order

### GET /products/:id
Get full product details.

### GET /products/:id/nutrients
Get nutrient composition of a product.

### GET /products/:id/compatibility
Food compatibility analysis — which products pair well based on nutrient synergies/conflicts.
Parameters: percent (1-50, default 10), topBy (count|value), initial (boolean), page, limit

### GET /products/categories
Full product category tree.

### GET /products/categories/:id/products
Products within a category. Supports pagination.

---

## Supplements (13,000+ dietary supplements)

### GET /supplements/search
Search supplements. All iherbUrl fields include referral code automatically.
Parameters: q (string, min 2), type_id (int), brand_id (int), page, limit, sort, order

### GET /supplements/:id
Supplement details with iHerb purchase link.

### GET /supplements/:id/nutrients
Nutrient composition of a supplement.

### GET /supplements/:id/reviews
User reviews for a supplement. Supports pagination.

### GET /supplements/types
All supplement types (Magnesium, Vitamin D, etc.).

### GET /supplements/brands
All supplement brands.

---

## Reviews (936,000+ real iHerb reviews)

### GET /reviews/search
Full-text search with morphological stemming (Russian), sentiment analysis, expert mentions boost, and lab-tested supplement boost.

Query syntax: regular words (AND), "quoted phrases", -exclusion, OR.

Parameters: q (string, min 3, required), type_id (int), page, limit

Without type_id — returns aggregation by supplement type sorted by weightedScore:
```json
{"data": [{"typeId": 5, "typeName": "Magnesium", "count": 342, "weightedScore": 456.2, "positiveCount": 280, "negativeCount": 15, "expertCount": 28, "labTested": true}]}
```

Scoring: positive reviews x1.5, negative x0.3, expert mentions x1.3, lab-tested x1.2.

With type_id — returns individual reviews ranked by relevance.

---

## Health Graph (Symptoms, Diseases, Conditions -> Nutrients)

### GET /symptoms
List all symptoms.

### GET /symptoms/:id/nutrients
Nutrients recommended for a symptom. Includes researchCount (number of scientific studies).

### GET /diseases
List all diseases.

### GET /diseases/:id/nutrients
Nutrients recommended for a disease. Includes researchCount.

### GET /diseases/:id/diets
Recommended diets for a disease.

### GET /conditions
List human conditions (pregnancy, lactation, menopause, intense training, etc.).

### GET /conditions/:id/nutrients
Nutrients for a condition. Includes researchCount.

### GET /health/lookup
Fuzzy search across symptoms, diseases, and conditions. Uses trigram similarity — handles morphological variations (e.g., "болит голову" matches "Головная боль").
Parameters: q (string, required)

---

## Blood Tests

### GET /analyzes
List all available blood test types.

### GET /analyzes/:id
Blood test type details with reference ranges.

### POST /analyzes/interpret
Interpret blood test results against reference ranges.
Body: {"results": [{"analyze_id": 1, "value": 120}], "sex": "m"|"w"}

### POST /patterns/match
Match biochemical patterns — identifies potential conditions from blood test combinations.
Body: same as /analyzes/interpret

---

## Nutrients (487 nutrients)

### GET /nutrients
List nutrients. Parameters: group_id (int), page, limit, sort, order

### GET /nutrients/groups
Nutrient groups (vitamins, minerals, amino acids, fatty acids, etc.).

### GET /nutrients/:id
Nutrient details.

### GET /nutrients/:id/dosages
Recommended daily dosages. Parameters: sex (m|w), age (int), activity (1-5)

### GET /nutrients/:id/relationships
Synergy, incompatibility, and replacement relationships between nutrients.

### GET /nutrients/:id/products
Food products rich in this nutrient. Supports pagination.

---

## Diets

### GET /diets
List all available diets.

### GET /diets/:id/products
Recommended products for a diet. Supports pagination.

---

## Equivalents

### GET /equivalents/unmapped
Unmapped nutrient equivalents (data quality utility).

---

## Response Format

Success: `{"data": <result>, "meta": {"total": 150, "page": 1, "limit": 20}}`
Error: `{"statusCode": 401, "message": "...", "error": "Unauthorized"}`

Pagination: page (default 1), limit (default 20, max 100), sort, order (asc|desc).
Localization: Accept-Language header (ru default, en supported).

---

## Quick Start

1. Get key: POST /keys/provision with {"email": "you@example.com"}
2. Save the apiKey from response
3. Search: GET /products/search?q=авокадо with Authorization: Bearer <key>
4. Check compatibility: GET /products/42/compatibility?percent=15
5. Find supplements for symptom: GET /reviews/search?q=бессонница
6. Look up health conditions: GET /health/lookup?q=усталость