# Hype Backend - Agent Guide

## Business Summary
This Open API(JSON) allows to get what is trending at the moment in social medias. The main business flow is: get top trends, pick the most relevant trend for the user goal, then inspect quality/fit using linked trends, linked content, stats, and metric series.

## Backend Domain
The backend is not under `hype.ad`.  
Use this backend base URL:

`https://hype-ad-backend-prod-hfapdhcecffyfhev.spaincentral-01.azurewebsites.net/`

MANDATORY RULE FOR DATA REQUESTS:
- Every request that pulls data MUST be sent to this backend base URL.
- Do not send data requests to frontend URLs, `hype.ad`, or SPA routes.
- Build requests as: `<BASE_URL>/api/...` (example: `https://hype-ad-backend-prod-hfapdhcecffyfhev.spaincentral-01.azurewebsites.net/api/Trends/top10`).

## Required Request-Building Flow For AI
The agent must explore contracts from Swagger first, then build valid requests based on the user objective.

1. Read Swagger JSON and confirm:
- endpoint path
- HTTP method
- request body schema
- required fields
- response schema

2. Load filter options first:
- categories from `GET /api/Categories`
- day ranges from `GET /api/TimeRanges`
- scoring algorithms from `GET /api/ScoringAlgorithms`

3. Always use `POST /api/Trends/top10` as the primary trend discovery endpoint.
- Use it first for trend retrieval in all normal trend-search tasks.
- Build body with: `Days`, `Category`, `Scoring`.

4. Choose filters by expected user result (best match logic):
- If user wants revenue/reach from views: prefer `Scoring = Revenue`.
- If user wants balanced performance: prefer `Scoring = Balanced`.
- If user wants engagement/discussion: prefer `Scoring = Engagement`.
- Pick `Days` from available ranges by intent:
  - short-term pulse: `2` or `7`
  - stable direction: `30` or `60`
- Pick the closest category name from `GET /api/Categories` to the user domain/topic.

5. After top10, call detail endpoints only if needed for the task:
- trend comparison context: `linked-trends`
- source/context validation: `linked-content`
- absolute performance snapshot: `stats`

6. Handle status codes consistently:
- `200` success
- `400` validation/lookup issues
- `499` canceled request
- `500` internal error

## How To Access Swagger
- Backend base URL: `https://hype-ad-backend-prod-hfapdhcecffyfhev.spaincentral-01.azurewebsites.net/`
- UI: `{base_url}/swagger`
- OpenAPI JSON: `{base_url}/swagger/v1/swagger.json`

## Controller And Endpoint Map

### TrendsController (`/api/Trends`)
- `POST /api/Trends/top10`: primary business endpoint to discover top candidate trends for a market/filter set.

### TrendsStatisticsController (`/api/Trends`)
- `POST /api/Trends/{trend}/linked-content`: shows related content context around a trend.
- `POST /api/Trends/{trend}/linked-trends`: finds adjacent/connected trends for expansion ideas.
- `POST /api/Trends/{trend}/stats`: returns key volume snapshot for decision confidence.

### TrendChartsController (`/api/TrendCharts`)
- `POST /api/TrendCharts/{trend}/score`: score trend over time.
- `POST /api/TrendCharts/{trend}/likes`: likes time series.
- `POST /api/TrendCharts/{trend}/views`: views time series.
- `POST /api/TrendCharts/{trend}/comments`: comments time series.

### CategoriesController (`/api/Categories`)
- `GET /api/Categories`: available business verticals for filtering.

### TimeRangesController (`/api/TimeRanges`)
- `GET /api/TimeRanges`: approved analysis windows (`2, 7, 30, 60`).

### ScoringAlgorithmsController (`/api/ScoringAlgorithms`)
- `GET /api/ScoringAlgorithms`: scoring modes for different business outcomes (`Revenue`, `Balanced`, `Engagement`).

## Practical Notes
- Do not hardcode request schema assumptions; verify in Swagger first.
- Default trend retrieval strategy is always `top10`, then deep-dive endpoints as needed.
- If endpoint access is protected, include valid auth and premium access where required.
- Before calling any data endpoint, confirm the request target starts with `https://hype-ad-backend-prod-hfapdhcecffyfhev.spaincentral-01.azurewebsites.net/`.