NiyanthaNiyanthaBack to Home
Global Backend

Integrate with api.niyantha.in and build on the open logistics backend.

Niyantha is a platform: session APIs, S2S APIs, and realtime messaging designed to help builders launch startups on top of Bharat's physical-economy infrastructure.

Open S2S GuidePlatform Overview

Platform Defaults

1

HTTP base: https://api.niyantha.in

2

Realtime base: wss://api.niyantha.in/ws

3

Stable, production-ready contracts for builders.

4

Auto-deployed platform updates without downtime.

Open

Public Access

Start with unauthenticated platform entry points and public-facing workflows.

GET /api/v1/accounts/apps/settings

Global backend at api.niyantha.in

Session

Account Session APIs

Authenticate an account, issue keys, and manage operational data across the platform.

Identity, keys, wallet, locations, stores, files

Orders, shipments, drivers, AI characters

Designed for secure browser and server use

Builder

S2S + WebSocket

Use API-key based REST and realtime messaging to build startups on top of Niyantha.

REST base: /api/v1/s2s/accounts

Realtime gateway: /ws

Production-ready APIs for building on top of Niyantha

Quickstart

Sample payloads for real platform flows

Use these as the baseline for production integrations on top of Niyantha's public, session, and realtime surfaces.

Account Login

Returns a bearer token for session APIs

curl -X POST https://api.niyantha.in/api/v1/accounts/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "account@example.com",
    "password": "StrongPassword@123"
  }'

S2S WebSocket Auth

Use on wss://api.niyantha.in/ws

{
  "type": "auth.login",
  "requestId": "s2s-auth-1",
  "payload": {
    "authType": "s2s",
    "token": "<public_key>",
    "metadata": {
      "secret": "<secret>",
      "app": "anystore",
      "storeId": "12"
    }
  }
}

Domain Guides

Deep payload coverage by business domain

Use these dedicated pages when you need exact request bodies, response samples, and route groupings for production integrations.

Reference

Stores

Store creation, settings, and store-product payloads for account and S2S apps.

Open guide

Reference

Orders

Order listing, detail, acceptance, decline, and settlement flows.

Open guide

Reference

Shipments

Network creation, shipment creation, filtering, and deep shipment detail models.

Open guide

Reference

Drivers

Driver profile, license updates, location updates, and shipment assignment lifecycle.

Open guide

Start Here

Public + Bootstrap APIs

These routes are the public entry layer and account bootstrap layer for apps integrating with Niyantha.

Public APIs

GET
/api/v1/accounts/apps/settings

Fetch account app settings bootstrap payload.

App Settings Bootstrap

{
  "apps": ["BermerStoresApp", "BermerRidersApp"],
  "locale": "en-IN"
}

Account Bootstrap

POST
/api/v1/accounts/afas

Create account OTP/AFA for register, login, or forgot password.

POST
/api/v1/accounts

Create an account.

POST
/api/v1/accounts/login

Log in with password or OTP/AFA.

POST
/api/v1/accounts/is_exists

Check if an account already exists.

POST
/api/v1/accounts/verify_forgot_password_afa

Verify forgot-password OTP and set a new password.

Account OTP Request

{
  "type": "otp",
  "purpose": "account_register",
  "email": "founder@startup.in",
  "sender": "niyantha"
}
Bearer Token

Account Session APIs

After account login, use these authenticated routes to run your application on top of Niyantha.

Identity + Keys + Wallet

GET
/api/v1/session

Get current account profile.

POST
/api/v1/session/logout

End the current account session.

POST
/api/v1/session/update

Update account profile data.

POST
/api/v1/session/update_password

Update account password.

POST
/api/v1/session/initiate_contact_update

Start contact change flow.

POST
/api/v1/session/update_contact

Complete contact change flow.

POST
/api/v1/session/initiate_email_update

Start email change flow.

POST
/api/v1/session/update_email

Complete email change flow.

POST
/api/v1/session/keys

Create an S2S API key pair.

GET
/api/v1/session/keys

List issued API keys.

PATCH
/api/v1/session/keys/:id/expire

Expire an API key immediately.

GET
/api/v1/session/wallet

Get account wallet.

POST
/api/v1/session/wallet

Create account wallet.

Create API Key

{
  "name": "production-primary",
  "ttl_seconds": 86400
}

Apps + Networks + Files

POST
/api/v1/session/apps

Create an account app.

GET
/api/v1/session/apps

List account apps.

POST
/api/v1/session/apps/logo

Upload account app logo.

GET
/api/v1/session/apps/:id

Get an account app.

POST
/api/v1/session/apps/:id

Update an account app.

POST
/api/v1/session/networks

Create a network.

GET
/api/v1/session/networks

List networks.

GET
/api/v1/session/networks/:id

Get a network.

POST
/api/v1/session/files

Create/upload a file.

GET
/api/v1/session/files/:id

Get a file.

Create Account App

{
  "name": "Niyantha Dispatch OS",
  "description": "Control panel for dispatch, fleet operations, and account orchestration",
  "primary_color": "#f59e0b"
}

Locations + Stores + Base Products

POST
/api/v1/session/locations/estimate

Estimate travel distance and time.

POST
/api/v1/session/locations/address/coordinates

Geocode an address.

POST
/api/v1/session/locations/coordinates/address

Reverse geocode coordinates.

POST
/api/v1/session/locations

Create a location.

GET
/api/v1/session/locations

List locations.

GET
/api/v1/session/locations/:id

Get a location.

POST
/api/v1/session/locations/:id

Update a location.

GET
/api/v1/session/base-products

List base products.

POST
/api/v1/session/stores

Create a store.

GET
/api/v1/session/stores

List account stores.

GET
/api/v1/session/stores/:id

Get a store.

GET
/api/v1/session/stores/:id/settings

Get store settings.

POST
/api/v1/session/stores/:id

Update a store.

POST
/api/v1/session/stores/:id/products

Create a store product.

GET
/api/v1/session/stores/:id/products

List store products.

GET
/api/v1/session/stores/:id/products/:product_id

Get a store product.

PATCH
/api/v1/session/stores/:id/products/:product_id

Update a store product.

DELETE
/api/v1/session/stores/:id/products/:product_id

Delete a store product.

Create Store

{
  "type": "grocery",
  "name": "Fresh Mart Hub",
  "description": "Neighborhood store connected to Niyantha logistics",
  "location_id": 101,
  "owner_aadhaar_front_file_id": 12,
  "owner_aadhaar_back_file_id": 13,
  "shop_body_type": "stationary_shop"
}

Orders + Shipments + Drivers + AI Characters

GET
/api/v1/session/orders

List account orders.

GET
/api/v1/session/orders/:id

Get an account order.

POST
/api/v1/session/orders/:id/accept

Accept an order.

POST
/api/v1/session/orders/:id/decline

Decline an order.

PATCH
/api/v1/session/orders/:id/mark-paid-and-delivered

Mark an order paid and delivered.

GET
/api/v1/session/stores/:store_id/orders

List store-scoped orders.

POST
/api/v1/session/shipments

Create a shipment.

GET
/api/v1/session/shipments

List shipments.

GET
/api/v1/session/shipments/:id

Get a shipment.

GET
/api/v1/session/drivers

Get driver profile.

POST
/api/v1/session/drivers/update-licenses

Update driver licenses.

POST
/api/v1/session/drivers/location

Update driver location.

GET
/api/v1/session/drivers/shipments

List assigned shipments.

POST
/api/v1/session/drivers/shipments/:id/accept

Accept assigned shipment.

POST
/api/v1/session/drivers/shipments/:id/reject

Reject assigned shipment.

PUT
/api/v1/session/drivers/shipments/:id/complete

Complete assigned shipment.

GET
/api/v1/session/stores/:store_id/characters

List store AI characters.

POST
/api/v1/session/stores/:store_id/characters

Create store AI character.

PATCH
/api/v1/session/characters/:character_id

Patch AI character.

GET
/api/v1/session/characters

List account-owned AI characters.

Create Shipment

{
  "from_location_id": 101,
  "to_location_id": 205,
  "vehicle_type": "truck",
  "load_weight": 1250,
  "notes": "Handle with care"
}
Production Integration

S2S REST + Realtime

The same operational primitives are exposed for API-key based server integrations and realtime applications.

S2S REST Base

GET
/api/v1/s2s/accounts

Get account profile with S2S key auth.

POST
/api/v1/s2s/accounts/update

Update account profile.

POST
/api/v1/s2s/accounts/update_password

Update password.

POST
/api/v1/s2s/accounts/initiate_contact_update

Start contact update flow.

POST
/api/v1/s2s/accounts/update_contact

Complete contact update flow.

POST
/api/v1/s2s/accounts/initiate_email_update

Start email update flow.

POST
/api/v1/s2s/accounts/update_email

Complete email update flow.

GET
/api/v1/s2s/accounts/wallet

Get wallet.

POST
/api/v1/s2s/accounts/wallet

Create wallet.

POST
/api/v1/s2s/accounts/afas

Create AFA/OTP flow for parity scenarios.

Header-Based S2S Auth

X-API-Key: <public_key>
X-API-Secret: <secret>

S2S Operational Domains

GET
/api/v1/s2s/accounts/apps

List apps.

POST
/api/v1/s2s/accounts/apps

Create app.

POST
/api/v1/s2s/accounts/networks

Create network.

POST
/api/v1/s2s/accounts/files

Upload file.

POST
/api/v1/s2s/accounts/locations

Create location.

POST
/api/v1/s2s/accounts/stores

Create store.

POST
/api/v1/s2s/accounts/stores/:id/products

Create store product.

POST
/api/v1/s2s/accounts/products

Create catalog product.

POST
/api/v1/s2s/accounts/shipments

Create shipment.

GET
/api/v1/s2s/accounts/orders

List account orders.

GET
/api/v1/s2s/accounts/drivers/shipments

List assigned driver shipments.

GET
/api/v1/s2s/accounts/characters

List account AI characters.

GET
/api/v1/s2s/accounts/base-products

List base products.

Create Store Product

{
  "store_item_id": 501,
  "name": "Tomato Crate",
  "type": "vegetable",
  "unit": "kg",
  "price_per_unit": 24,
  "min_order_unit": 1,
  "max_order_unit": 100,
  "stock_type": "limited",
  "stock": 400
}

Realtime Gateway

WS
/ws

Authenticate with auth.login and then use account, store, product, order, location, file, network, vehicle, shipment, AI, and review message types.

Realtime Auth Envelope

{
  "type": "auth.login",
  "requestId": "account-live-1",
  "payload": {
    "authType": "s2s",
    "token": "<public_key>",
    "metadata": {
      "secret": "<secret>",
      "app": "niyantha",
      "storeId": "12"
    }
  }
}

Build on Niyantha APIs.

Start with public and session APIs, graduate to S2S and realtime. The platform runs at api.niyantha.in with production-ready contracts for startups and enterprise teams.

See Production Integration GuidePlatform Overview