# Stats

# SomaTech Stats API

**Base URL:** `https://somatechapi.nexgate.co`

---

## Endpoint Overview

<table id="bkmrk-%23-method-path-auth-r"><thead><tr><th>\#</th><th>Method</th><th>Path</th><th>Auth Required</th></tr></thead><tbody><tr><td>1</td><td>GET</td><td>`/api/v1/stats`</td><td>No</td></tr><tr><td>2</td><td>GET</td><td>`/api/v1/stats/trend`</td><td>No</td></tr><tr><td>3</td><td>POST</td><td>`/api/v1/auth/add`</td><td>No</td></tr><tr><td>4</td><td>POST</td><td>`/api/v1/auth/request-otp`</td><td>No</td></tr><tr><td>5</td><td>POST</td><td>`/api/v1/auth/verify-otp`</td><td>No</td></tr><tr><td>6</td><td>POST</td><td>`/api/v1/message/send`</td><td>**Yes — JWT**</td></tr><tr><td>7</td><td>GET</td><td>`/api/v1/admin/users`</td><td>**Yes — JWT**</td></tr><tr><td>8</td><td>GET</td><td>`/api/v1/admin/messages`</td><td>**Yes — JWT**</td></tr><tr><td>9</td><td>GET</td><td>`/api/v1/admin/users/{userId}`</td><td>**Yes — JWT**</td></tr></tbody></table>

---

## 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:**

<table id="bkmrk-param-type-required-"><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>`from`</td><td>`yyyy-MM-dd`</td><td>No</td><td>Start date. Defaults to 30 days ago</td></tr><tr><td>`to`</td><td>`yyyy-MM-dd`</td><td>No</td><td>End date. Defaults to today</td></tr></tbody></table>

**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 <your_access_token>
> 
> ```

---

### 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:**

<table id="bkmrk-field-type-required-"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>`phoneNumber`</td><td>`string`</td><td>Yes</td><td>Recipient phone number</td></tr><tr><td>`text`</td><td>`string`</td><td>Yes</td><td>Message content</td></tr><tr><td>`sender`</td><td>`uuid`</td><td>No</td><td>Sender UUID</td></tr></tbody></table>

```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 <your_access_token>" \
  -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:**

<table id="bkmrk-param-type-required--1"><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>`page`</td><td>`int`</td><td>No</td><td>`0`</td><td>Page number (zero-based)</td></tr><tr><td>`size`</td><td>`int`</td><td>No</td><td>`20`</td><td>Page size</td></tr><tr><td>`from`</td><td>`yyyy-MM-dd`</td><td>No</td><td>—</td><td>Filter by creation date start</td></tr><tr><td>`to`</td><td>`yyyy-MM-dd`</td><td>No</td><td>—</td><td>Filter by creation date end</td></tr></tbody></table>

**Request:**

```bash
curl "https://somatechapi.nexgate.co/api/v1/admin/users?page=0&size=20" \
  -H "Authorization: Bearer <your_access_token>"

```

**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:**

<table id="bkmrk-param-type-required--2"><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>`page`</td><td>`int`</td><td>No</td><td>`0`</td><td>Page number (zero-based)</td></tr><tr><td>`size`</td><td>`int`</td><td>No</td><td>`20`</td><td>Page size</td></tr><tr><td>`from`</td><td>`yyyy-MM-dd`</td><td>No</td><td>—</td><td>Filter by creation date start</td></tr><tr><td>`to`</td><td>`yyyy-MM-dd`</td><td>No</td><td>—</td><td>Filter by creation date end</td></tr></tbody></table>

**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 <your_access_token>"

```

**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:**

<table id="bkmrk-param-type-descripti"><thead><tr><th>Param</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`userId`</td><td>`uuid`</td><td>The UUID of the user</td></tr></tbody></table>

**Query Params:**

<table id="bkmrk-param-type-required--3"><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>`page`</td><td>`int`</td><td>No</td><td>`0`</td><td>Page number (zero-based)</td></tr><tr><td>`size`</td><td>`int`</td><td>No</td><td>`20`</td><td>Page size</td></tr><tr><td>`from`</td><td>`yyyy-MM-dd`</td><td>No</td><td>—</td><td>Filter messages by creation date start</td></tr><tr><td>`to`</td><td>`yyyy-MM-dd`</td><td>No</td><td>—</td><td>Filter messages by creation date end</td></tr></tbody></table>

**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 <your_access_token>"

```

**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