Production API portal

VARADHI backend for hyperlocal news, UGC, ads, notifications, analytics, and AI personalization.

This is the backend handoff page for frontend developers, QA, admins, and deployment checks. Runtime responses use the VARADHI envelope: {"data": ..., "meta": ..., "errors": ...}.

Swagger Redoc OpenAPI Health Django Admin

v1API Contract

PublicRead Before Login

JWTUser/Admin Writes

LGDLocation Master

Platform

Backend Capabilities

VARADHI is an APK-first local news backend with public feeds, authenticated UGC, canonical location personalization, moderation, ads, notifications, analytics, and admin operations.

News

Articles, feed, unified feed, breaking/featured flags, search, recommendations, live news, videos, shorts, polls, CMS, quotes, posters, and e-paper.

UGC

OTP, submission, media upload, moderation queue, branded media, reporter dashboard, rewards hook, trust score, and public UGC feed.

Hyperlocal

Location Master with State, District, Subdistrict/Mandal, Village, aliases, Telugu names, LGD codes, and canonical feed matching.

Growth

Ad booking, ad decisioning, push notifications, analytics events, live trends, and AI personalization layered on current feeds.

Canonical Location Architecture

Location Master

New backend phases use canonical locations internally while keeping existing frontend fields like state, district, subdistrict, and village.

Hierarchy

State -> District -> Subdistrict/Mandal -> Village

English and Telugu names
Aliases and slugs
LGD codes
Pincode and coordinates

Integrated Modules

Articles, users, feed, search, recommendations, notifications, analytics, trends, and UGC now prefer canonical location data where available.

Backward Compatible

Frontend payloads continue returning text fields. Canonical IDs are optional/internal except dedicated location picker/profile APIs.

Public Before Login

Frontend Read APIs

These are safe for APK/home/search/read flows before login.

Method	Endpoint	Purpose
GET	/api/v1/articles/feed/	Main/local article feed with canonical-first location filtering and legacy fallback.
GET	/api/v1/articles/{slug}/	Article detail.
GET	/api/v1/articles/{article_id}/comments/	Public published comments and replies for an article.
GET	/api/v1/feed/	Unified feed combining articles, UGC, and live items.
GET	/api/v1/search/?q=keyword	Article search with canonical location matching.
GET	/api/v1/categories/	News categories.
GET	/api/v1/locations/search/?q=kesaram	Location picker search across states, districts, mandals, villages, aliases, and pincodes.
GET	/api/v1/ugc/feed/	Approved UGC feed, canonical-first local filtering.
GET	/api/v1/ads/	Ad inventory with decision-engine ranking.
GET	/api/v1/ads/areas/	Advertisement booking areas.
GET	/api/v1/ads/pricing/	Advertisement pricing lookup.
GET	/api/v1/polls/	Public polls.
GET	/api/v1/posters/	Poster/info card list.

JWT Required

User and APK APIs

Use Bearer JWT after login. Guest location APIs are public and session-backed.

Article Engagement reactions and comments

PUT	/api/v1/articles/{article_id}/reaction/	Set authenticated or guest article reaction.
DELETE	/api/v1/articles/{article_id}/reaction/	Remove authenticated or guest article reaction.
POST	/api/v1/articles/{article_id}/comments/	Create top-level comment or reply. JWT required.
PATCH	/api/v1/articles/comments/{comment_id}/	Edit own comment. Published edits return to moderation.
DELETE	/api/v1/articles/comments/{comment_id}/	Soft-delete own/admin comment through lifecycle.
POST	/api/v1/articles/comments/{comment_id}/report/	Report a published comment. JWT required.

UGC Flow OTP, submit, media, reporter

POST	/api/v1/ugc/send-otp/	Send mobile OTP.
POST	/api/v1/ugc/verify-otp/	Verify OTP.
POST	/api/v1/ugc/submit/	Create UGC submission. JWT required.
POST	/api/v1/ugc/upload-media/	Upload UGC image/video. JWT required.
GET	/api/v1/ugc/reporter/dashboard/	Reporter stats.
GET	/api/v1/ugc/reporter/submissions/	Own submissions with cursor pagination.

Location Profile personalization

GET	/api/v1/auth/locations/profile/	Current user's canonical home location.
PATCH	/api/v1/auth/locations/profile/	Update user's state/district/subdistrict/village ID.
GET	/api/v1/auth/locations/followed/	Followed locations.
POST	/api/v1/auth/locations/followed/	Follow location.
GET	/api/v1/auth/locations/guest/	Guest location profile.
PATCH	/api/v1/auth/locations/guest/	Set guest location.

Notifications inbox and subscriptions

GET	/api/v1/notifications/preferences/	User notification preferences.
PATCH	/api/v1/notifications/preferences/	Update quiet hours, caps, category flags.
GET	/api/v1/notifications/subscriptions/	List subscriptions.
POST	/api/v1/notifications/subscriptions/	Create/reactivate subscription.
GET	/api/v1/notifications/inbox/	User inbox.
POST	/api/v1/notifications/inbox/{id}/read/	Mark notification read.

Analytics Events non-blocking

POST	/api/v1/analytics/events/	Send impressions, opens, scroll, shares, search, feed refresh, recommendations, and notification events.
POST	/api/v1/ads/event/	Send ad impression/click/viewability/skip/hide events.
POST	/api/v1/polls/{id}/vote/	Public poll vote.

Admin

Admin and Editorial APIs

Admin APIs require staff/admin JWT or Django admin permissions depending on endpoint.

Area	Endpoints	Purpose
Articles	/api/v1/articles/admin/	Create, update, delete, publish articles with optional canonical locations and thumbnail upload/url support.
Article Comments	/admin/api/articles/comments/	Admin-only comment moderation list, detail, publish, hold, reject, hide, restore, and reports list. Not for consumer Flutter.
UGC	/admin/api/ugc/queue/	Moderation queue, detail, approve, reject, flag, OTP delivery audit.
Notifications	/api/v1/notifications/send/	Create/send/schedule push notifications with canonical targeting and target preview.
Analytics	/admin/api/analytics/editorial/*	Editorial overview, location/category analytics, trends, ranking debug, notification/search/feed/recommendation analytics.
Ads	/api/v1/ads/admin/*	Inventory, areas, pricing, bookings, and decision intelligence.
Locations	/admin/locations/*	Manage State, District, Subdistrict, Village, aliases, and import batches.

Handover Documents

Frontend and Admin Integration Docs

Use these repository documents as the source of truth for client and admin portal integration.

Article Engagement

Consumer Flutter handover for article reactions, comments, replies, reports, moderation states, and client behaviour.

docs/frontend/ARTICLE_ENGAGEMENT_HANDOVER.md

Admin Comment Moderation

Admin portal handover for comment moderation APIs, state machine, reports list, counter semantics, and hard-delete safety.

docs/admin/ARTICLE_COMMENT_MODERATION_API_HANDOVER.md

Full API Contract

Project-wide API reference and Postman assets for broader backend integration testing.

fullprojectapidocument.md
docs/postman/

Operations

Deploy and Data Commands

Run these carefully in production. Always dry-run location backfills first.

Location Import

python scripts/transform_lgd.py --input-dir datasets/raw/lgd/2026-07 --output datasets/generated/varadhi_locations.csv --report datasets/generated/varadhi_locations_report.json
python manage.py import_locations datasets/generated/varadhi_locations.csv --source-name lgd-2026-07 --dry-run
python manage.py import_locations datasets/generated/varadhi_locations.csv --source-name lgd-2026-07

Backfills

python manage.py backfill_article_locations --dry-run --only-unresolved --report reports/article_location_backfill
python manage.py backfill_ugc_locations --dry-run --only-unresolved --report reports/ugc_location_backfill.json
After review, rerun without --dry-run.

Validation

python manage.py check --settings ci.test_settings
python manage.py spectacular --file openapi-schema.yml --settings ci.test_settings
pytest -q

Celery Required

Celery worker and beat are required for OTP, media processing, notifications, analytics aggregation, live trends, and interest profile rebuilds.

Production note: keep CORS restricted before launch. Temporary wildcard CORS is okay only for frontend testing and should be disabled before client release.