# SomaTech Stats API **Base URL:** `https://somatechapi.nexgate.co` --- ## Endpoint Overview | # | Method | Path | Auth Required | |---|--------|------|---------------| | 1 | GET | `/api/v1/stats` | No | | 2 | GET | `/api/v1/stats/trend` | No | | 3 | POST | `/api/v1/auth/add` | No | | 4 | POST | `/api/v1/auth/request-otp` | No | | 5 | POST | `/api/v1/auth/verify-otp` | No | | 6 | POST | `/api/v1/message/send` | **Yes — JWT** | | 7 | GET | `/api/v1/admin/users` | **Yes — JWT** | | 8 | GET | `/api/v1/admin/messages` | **Yes — JWT** | | 9 | GET | `/api/v1/admin/users/{userId}` | **Yes — JWT** | --- ## Public Endpoints ### 1. Overall Stats Returns total counts with no date filtering. **Endpoint:** ``` GET /api/v1/stats ``` **Auth:** None — public endpoint **Request:** ```bash curl https://somatechapi.nexgate.co/api/v1/stats ``` **Response:** ```json { "status": "success", "message": "Stats fetched successfully", "data": { "totalUsers": 1500, "totalMessages": 12400, "totalResponses": 11800, "trend": null } } ``` --- ### 2. Trend Stats Returns overall counts plus daily breakdown for a date range. **Endpoint:** ``` GET /api/v1/stats/trend ``` **Auth:** None — public endpoint **Query Params:** | Param | Type | Required | Description | |-------|------|----------|-------------| | `from` | `yyyy-MM-dd` | No | Start date. Defaults to 30 days ago | | `to` | `yyyy-MM-dd` | No | End date. Defaults to today | **Request:** ```bash # With date range curl "https://somatechapi.nexgate.co/api/v1/stats/trend?from=2024-01-01&to=2024-03-01" # Default last 30 days curl "https://somatechapi.nexgate.co/api/v1/stats/trend" ``` **Response:** ```json { "status": "success", "message": "Stats fetched successfully", "data": { "totalUsers": 1500, "totalMessages": 12400, "totalResponses": 11800, "trend": [ { "date": "2024-01-01", "messages": 120, "responses": 115, "newUsers": 30 }, { "date": "2024-01-02", "messages": 98, "responses": 95, "newUsers": 12 } ] } } ``` --- ## Protected Endpoints > These endpoints require a valid JWT token in the `Authorization` header. > > ``` > Authorization: Bearer > ``` --- ### 6. Send Message Sends an SMS message on behalf of the authenticated server. **Endpoint:** ``` POST /api/v1/message/send ``` **Auth:** Required — JWT Bearer token **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `phoneNumber` | `string` | Yes | Recipient phone number | | `text` | `string` | Yes | Message content | | `sender` | `uuid` | No | Sender UUID | ```json { "phoneNumber": "+255712345678", "text": "Hello from SMS Gateway" } ``` **Request:** ```bash curl -X POST https://somatechapi.nexgate.co/api/v1/message/send \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"phoneNumber": "+255712345678", "text": "Hello from SMS Gateway"}' ``` **Response:** ```json { "status": "success", "message": "Message sent successfully", "data": { "messageId": "550e8400-e29b-41d4-a716-446655440000", "sender": "550e8400-e29b-41d4-a716-446655440001", "phoneNumber": "+255712345678", "text": "Hello from SMS Gateway", "response": "AI response here", "creationDate": "2024-01-01T10:00:00Z", "modificationDate": "2024-01-01T10:00:00Z", "isDeleted": false } } ``` --- ### 7. Admin — List Users Returns a paginated list of all registered users with optional date filtering. **Endpoint:** ``` GET /api/v1/admin/users ``` **Auth:** Required — JWT Bearer token **Query Params:** | Param | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `page` | `int` | No | `0` | Page number (zero-based) | | `size` | `int` | No | `20` | Page size | | `from` | `yyyy-MM-dd` | No | — | Filter by creation date start | | `to` | `yyyy-MM-dd` | No | — | Filter by creation date end | **Request:** ```bash curl "https://somatechapi.nexgate.co/api/v1/admin/users?page=0&size=20" \ -H "Authorization: Bearer " ``` **Response:** ```json { "status": "success", "message": "Users fetched successfully", "data": { "content": [ { "userId": "550e8400-e29b-41d4-a716-446655440000", "firstName": "John", "lastName": "Doe", "phoneNumber": "+255712345678", "connects": 10, "createdDate": "2024-01-01T10:00:00Z", "totalMessages": 42 } ], "totalElements": 1500, "totalPages": 75, "page": 0, "size": 20 } } ``` --- ### 8. Admin — List Messages Returns a paginated list of all messages with optional date filtering. **Endpoint:** ``` GET /api/v1/admin/messages ``` **Auth:** Required — JWT Bearer token **Query Params:** | Param | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `page` | `int` | No | `0` | Page number (zero-based) | | `size` | `int` | No | `20` | Page size | | `from` | `yyyy-MM-dd` | No | — | Filter by creation date start | | `to` | `yyyy-MM-dd` | No | — | Filter by creation date end | **Request:** ```bash curl "https://somatechapi.nexgate.co/api/v1/admin/messages?page=0&size=20&from=2024-01-01&to=2024-03-01" \ -H "Authorization: Bearer " ``` **Response:** ```json { "status": "success", "message": "Messages fetched successfully", "data": { "content": [ { "messageId": "550e8400-e29b-41d4-a716-446655440000", "senderId": "550e8400-e29b-41d4-a716-446655440001", "senderName": "John Doe", "senderPhone": "+255712345678", "text": "Hello", "response": "AI response here", "recipientPhone": "+255787654321", "creationDate": "2024-01-01T10:00:00Z" } ], "totalElements": 12400, "totalPages": 620, "page": 0, "size": 20 } } ``` --- ### 9. Admin — Get User by ID Returns a single user's profile alongside their paginated messages, with optional date range filtering on messages. **Endpoint:** ``` GET /api/v1/admin/users/{userId} ``` **Auth:** Required — JWT Bearer token **Path Param:** | Param | Type | Description | |-------|------|-------------| | `userId` | `uuid` | The UUID of the user | **Query Params:** | Param | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `page` | `int` | No | `0` | Page number (zero-based) | | `size` | `int` | No | `20` | Page size | | `from` | `yyyy-MM-dd` | No | — | Filter messages by creation date start | | `to` | `yyyy-MM-dd` | No | — | Filter messages by creation date end | **Request:** ```bash curl "https://somatechapi.nexgate.co/api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000?page=0&size=20&from=2024-01-01&to=2024-03-01" \ -H "Authorization: Bearer " ``` **Response (200 OK):** ```json { "status": "success", "message": "User fetched successfully", "data": { "user": { "userId": "550e8400-e29b-41d4-a716-446655440000", "firstName": "John", "lastName": "Doe", "phoneNumber": "+255712345678", "connects": 10, "createdDate": "2024-01-01T10:00:00Z", "totalMessages": 42 }, "messages": { "content": [ { "messageId": "550e8400-e29b-41d4-a716-446655440002", "senderId": "550e8400-e29b-41d4-a716-446655440000", "senderName": "John Doe", "senderPhone": "+255712345678", "text": "Hello", "response": "AI response here", "recipientPhone": "+255787654321", "creationDate": "2024-01-01T10:00:00Z" } ], "totalElements": 42, "totalPages": 3, "page": 0, "size": 20 } } } ``` **Response (404 Not Found):** ```json { "status": "failed", "message": "User not found", "data": null } ``` --- ## Notes - All dates must be in `yyyy-MM-dd` format - If `from` is provided without `to`, `to` defaults to today - If neither is provided, trend defaults to last 30 days - `trend` is `null` on the overall stats endpoint - JWT tokens are obtained from the `/api/v1/auth/verify-otp` response - Pagination is zero-based — `page=0` returns the first page