REST API
Use this page to orient an integration, then open the domain guide for endpoint details and examples. The registered routes in the API source (opens in a new tab) define what the service supports.
Start with the integration walkthrough, browse the complete endpoint catalog, or open interactive Swagger UI.
Base URL
| Environment | Base URL |
|---|---|
| Local default | http://localhost:8080/api/v1 |
| Other environments | <API origin><API_BASE_PATH> |
The API listens on port 8080 and uses /api/v1 by default. Both are configurable (PORT, API_BASE_PATH); confirm the deployed origin and configuration with the service operator. Endpoint paths on this site are relative to that base URL.
Authentication
Most business routes require a bearer access token:
Authorization: Bearer <access_token>Register or log in using the authentication endpoints. Public routes include health checks, onboarding metadata, public reviews, and subscription plan reads. Some authenticated routes also require owner permissions, pharmacy personnel access, or admin MFA; each guide calls out those restrictions.
Common conventions
| Convention | Behavior |
|---|---|
| Response | Standard JSON response envelope; see authentication and security (opens in a new tab). |
| IDs | UUIDs for persisted records. |
| Money | Integer values in Tanzanian shillings (TZS). |
| Dates | Date-only inputs generally use YYYY-MM-DD; timestamp fields are RFC 3339. Check the endpoint contract. |
| Pagination | Many list routes accept page and page_size; defaults and maximums can differ by route. |
| Scope | Authenticated requests use organisation and active-store context from the token. |
Do not assume every resource uses identical filters, pagination limits, or CRUD behavior. Read the domain guide before relying on a field or side effect.
Domain map
| Domain | Guide | What it covers |
|---|---|---|
| Accounts and authentication | Authentication | Registration, OTP, login, token refresh, profile, organisation, users, store switching, MFA. |
| Inventory | Inventory | Products, categories, units, stock adjustments, batches, pharmacy inventory. |
| Point of sale | Transactions | Checkout, transaction history, refunds, voids, receipts, summaries. |
| Customers | Customers | Customer records, credit customer listing, SMS. |
| Credit tabs | Credits | Balances, payments, reminders, notes, write-offs. |
| Suppliers | Suppliers | Suppliers, deliveries, payments, purchase orders, reorder suggestions. |
| Expenses | Expenses | Expense records, categories, summaries. |
| Staff | Staff | Staff management, permissions, activity, statistics. |
| Stores | Stores | Store management, status, staff, performance. |
| Analytics | Analytics | Sales, products, customers, cash flow, dashboard. |
| Reports | Reports | Generated exports and scheduled reports. |
| Subscriptions | Subscriptions | Plans, payments, subscription status, store limits. |
| AI conversations | AI | Chat, conversation history, suggestions, usage. |
| Notifications | Notifications | In-app notifications and read status. |
| Notebook | Notebook | Store notes. |
| File uploads | Uploads | Authenticated object upload and deletion. |
| Public reviews | Reviews | Public review listing and authenticated submission. |
| Onboarding metadata | Meta | Business types, regions, districts, outlet types. |
| Health checks | Health checks | Public liveness and dependency checks. |
| Platform administration | Admin API | Admin and monitoring routes protected by MFA. |
Source documentation
For the complete route index and implementation notes, see the API repository’s API reference (opens in a new tab), business workflows (opens in a new tab), and configuration guide (opens in a new tab).
The downloadable OpenAPI JSON contract provides route and method discovery in Swagger UI. Domain guides remain the detailed source for request fields, validation, role requirements, side effects, and response behavior.