Logs API

Activity logs for database operations and user authentication events

The Logs API provides admin endpoints to retrieve and manage activity logs for your InsForge backend. Track database operations (INSERT, UPDATE, DELETE) and authentication events (LOGIN) across all tables and users.

List Activity Logs

Retrieve paginated activity logs with optional filtering by action type or table name.

Authentication

Requires:

• Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Query Parameters

limit · integer · default: "100"

Maximum number of logs to return per page

offset · integer · default: "0"

Number of logs to skip for pagination

action · string

Filter by action type. Valid values:

• INSERT - Record creation events
• UPDATE - Record modification events
• DELETE - Record deletion events
• LOGIN - User authentication events

table · string

Filter by table name (e.g., posts, comments). Not applicable for LOGIN actions.

Response Headers

X-Total-Count · integer

Total number of logs matching the query

X-Page · integer

Current page number (calculated from offset and limit)

X-Page-Size · integer

Number of items per page (same as limit parameter)

X-Total-Pages · integer

Total number of pages available

Response Body

id · string

Unique log entry identifier

timestamp · string

When the action occurred (ISO 8601 format)

action · string

Type of action: INSERT, UPDATE, DELETE, or LOGIN

table · string | null

Table name affected by the action (null for LOGIN actions)

record_id · string | null

ID of the affected record (null for LOGIN actions)

user_id · string

ID of the user who performed the action

details · object | null

Additional context about the action (structure varies by action type)

Example Request

# Get all logs with pagination
curl -X GET "https://your-app.region.insforge.app/api/logs?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# Filter by action type
curl -X GET "https://your-app.region.insforge.app/api/logs?action=INSERT" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# Filter by table name
curl -X GET "https://your-app.region.insforge.app/api/logs?table=posts&limit=100" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

[
  {
    "id": "log-123",
    "timestamp": "2024-01-21T10:30:00Z",
    "action": "INSERT",
    "table": "posts",
    "record_id": "post-456",
    "user_id": "user-789",
    "details": {
      "title": "New Post",
      "author": "John Doe"
    }
  },
  {
    "id": "log-124",
    "timestamp": "2024-01-21T10:31:00Z",
    "action": "LOGIN",
    "table": null,
    "record_id": null,
    "user_id": "user-789",
    "details": {
      "ip": "192.168.1.1",
      "user_agent": "Mozilla/5.0..."
    }
  }
]

---

Clear Logs

Delete activity logs, optionally filtering by date. Use this endpoint to manage log storage and comply with data retention policies.

Authentication

Requires:

• Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Query Parameters

before · string

Delete logs before this timestamp (ISO 8601 format). If not provided, all logs will be deleted.

Example: 2024-01-21T10:30:00Z

Response

message · string

Success message confirming logs were cleared

deleted_count · integer

Number of log entries deleted

Example Request

# Delete all logs older than a specific date
curl -X DELETE "https://your-app.region.insforge.app/api/logs?before=2024-01-20T00:00:00Z" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# Delete all logs (use with caution!)
curl -X DELETE "https://your-app.region.insforge.app/api/logs" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "message": "Logs cleared successfully",
  "deleted_count": 150
}

Error Responses

400 Bad Request - Invalid date format:

{
  "error": "INVALID_DATE",
  "message": "Invalid date format for 'before' parameter",
  "statusCode": 400,
  "nextAction": "Use ISO 8601 date format (YYYY-MM-DDTHH:mm:ssZ)"
}

---

Get Logs Statistics

Retrieve aggregated statistics about activity logs including action counts, table activity, and recent activity metrics.

Authentication

Requires:

• Bearer Token: Admin JWT token in Authorization: Bearer <token> header

Response

actionStats · array

Breakdown of logs by action type

actionStats[].action · string

Action type: INSERT, UPDATE, DELETE, or LOGIN

actionStats[].count · integer

Number of logs for this action type

tableStats · array

Breakdown of logs by table name

tableStats[].table_name · string

Table name

tableStats[].count · integer

Number of logs for this table

recentActivity · integer

Count of logs created in the last 24 hours

totalLogs · integer

Total number of logs in the system

Example Request

curl -X GET https://your-app.region.insforge.app/api/logs/stats \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "actionStats": [
    {
      "action": "INSERT",
      "count": 245
    },
    {
      "action": "UPDATE",
      "count": 189
    },
    {
      "action": "DELETE",
      "count": 34
    },
    {
      "action": "LOGIN",
      "count": 567
    }
  ],
  "tableStats": [
    {
      "table_name": "posts",
      "count": 156
    },
    {
      "table_name": "comments",
      "count": 223
    }
  ],
  "recentActivity": 47,
  "totalLogs": 1035
}

---

When to Use Logs APIs

Use these endpoints to:

• Audit database changes: Track all INSERT, UPDATE, and DELETE operations
• Monitor user activity: Review authentication events and user actions
• Debug issues: Investigate what changed and when in your database
• Compliance: Maintain audit trails for regulatory requirements
• Analytics: Analyze usage patterns and activity trends

Common Use Cases

1. Admin Dashboard: Display recent activity and statistics using /api/logs/stats
2. Audit Trail: Use /api/logs with filters to track specific tables or users
3. Security Monitoring: Filter by action=LOGIN to review authentication events
4. Data Retention: Use /api/logs DELETE endpoint to comply with retention policies
5. Debugging: Filter by table and date range to investigate data issues