InfraForge Docs

InfraNotes Core · v2

Welcome

Select a document from the sidebar to read it.

Smart Expense Notepad API Documentation

Overview

This document provides comprehensive documentation for the Smart Expense Notepad API. The API enables tracking expenses, income, and related notes for professionals in the construction industry while facilitating team collaboration and providing robust security features.

Base URL

All API requests should be prefixed with the base URL:

https://notes.api.infraforg.com

Authentication

Most endpoints require authentication. Authentication is provided through JSON Web Tokens (JWT).

Authentication Headers

For protected endpoints, include the JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Response Format

Unless otherwise specified, all responses are returned in JSON format with the following structure:

{
  "success": true,
  "data": {
    // Response data
  },
  "message": "Operation successful"
}

For errors:

{
  "success": false,
  "error": "Error message",
  "code": 400
}

API Endpoints

Health Check

GET /health

Simple health check to verify API is running.

Response: A simple response indicating the server is running.

GET /health/details

Detailed health check with database and Redis connection status.

Response: Detailed health information about the server and its dependencies.

Authentication

POST /api/auth/register

Register a new user.

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "Full Name"
}

Response: User details and authentication token.

POST /api/auth/login

Login with email and password.

Request Body:

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response: User details and authentication token.

POST /api/auth/login/mfa

Complete login with Multi-Factor Authentication.

Request Body:

{
  "email": "user@example.com",
  "token": "temporary_token",
  "code": "123456"
}

Response: User details and final authentication token.

GET /api/auth/profile

Get the current user's profile.

Response: User profile details.

PUT /api/auth/profile

Update the current user's profile.

Request Body:

{
  "name": "Updated Name",
  "email": "updated@example.com"
}

Response: Updated user profile.

GET /api/auth/verify-email

Verify user's email address using verification token.

Query Parameters:

  • token: Email verification token

Response: Confirmation of email verification.

POST /api/auth/resend-verification

Resend email verification link.

Request Body:

{
  "email": "user@example.com"
}

Response: Confirmation of email sent.

Session Management

GET /api/sessions

Get all active sessions for the current user.

Response: List of active sessions with device and location information.

POST /api/sessions/revoke

Revoke a specific session.

Request Body:

{
  "session_id": "session_identifier"
}

Response: Confirmation of session revocation.

POST /api/sessions/revoke-all

Revoke all sessions except the current one.

Response: Confirmation of all sessions revoked.

Multi-Factor Authentication

POST /api/auth/mfa/setup

Generate MFA setup for a user.

Response: TOTP secret and QR code URL.

POST /api/auth/mfa/enable

Verify and enable MFA for a user.

Request Body:

{
  "code": "123456",
  "secret": "totp_secret"
}

Response: Confirmation of MFA enabled.

POST /api/auth/mfa/disable

Disable MFA for a user.

Request Body:

{
  "password": "current_password"
}

Response: Confirmation of MFA disabled.

Expenses

GET /api/expenses

List all expenses for the authenticated user.

Query Parameters:

  • start_date: Filter by start date (YYYY-MM-DD)
  • end_date: Filter by end date (YYYY-MM-DD)
  • category_id: Filter by category ID
  • project_id: Filter by project ID
  • amount_min: Filter by minimum amount
  • amount_max: Filter by maximum amount
  • page: Page number for pagination
  • limit: Number of items per page

Response: List of expenses.

POST /api/expenses

Create a new expense.

Request Body:

{
  "amount": 150.75,
  "date": "2025-03-15",
  "description": "Building materials",
  "category_id": 1,
  "project_id": 2,
  "currency_id": 1,
  "notes": "For site renovation"
}

Response: Created expense details.

GET /api/expenses/{id}

Get a specific expense by ID.

Response: Expense details.

PUT /api/expenses/{id}

Update a specific expense.

Request Body: Same as POST with fields to update.

Response: Updated expense details.

DELETE /api/expenses/{id}

Delete a specific expense.

Response: Confirmation of deletion.

GET /api/expenses/summary

Get expense summary for the authenticated user.

Query Parameters:

  • start_date: Start date (YYYY-MM-DD)
  • end_date: End date (YYYY-MM-DD)
  • group_by: Group by parameter (day, week, month, year)

Response: Expense summary data.

Projects

GET /api/projects

List all projects for the authenticated user.

Response: List of projects.

POST /api/projects

Create a new project.

Request Body:

{
  "name": "Site Renovation",
  "description": "Full renovation of construction site",
  "start_date": "2025-03-01",
  "end_date": "2025-06-30",
  "budget": 50000
}

Response: Created project details.

GET /api/projects/{id}

Get a specific project by ID.

Response: Project details.

PUT /api/projects/{id}

Update a specific project.

Request Body: Same as POST with fields to update.

Response: Updated project details.

DELETE /api/projects/{id}

Delete a specific project.

Response: Confirmation of deletion.

GET /api/projects/{id}/expenses

Get all expenses associated with a specific project.

Response: List of project expenses.

GET /api/projects/{id}/summary

Get summary of expenses for a specific project.

Response: Project expense summary.

Receipt Management

POST /api/expenses/{id}/receipt

Upload a receipt for an expense.

Content-Type: multipart/form-data

Form Parameters:

  • file: The receipt image/file

Response: Upload confirmation with receipt URL.

GET /api/expenses/{id}/receipt

Get the receipt for an expense.

Response: Receipt file or URL.

DELETE /api/expenses/{id}/receipt

Delete the receipt for an expense.

Response: Confirmation of deletion.

Export

GET /api/export/expenses

Export expenses to CSV or Excel.

Query Parameters:

  • format: Export format (csv, excel)
  • start_date: Start date (YYYY-MM-DD)
  • end_date: End date (YYYY-MM-DD)

Response: File download.

GET /api/export/projects

Export projects to CSV or Excel.

Query Parameters:

  • format: Export format (csv, excel)

Response: File download.

Summary

GET /api/summary/daily

Get daily expense summary.

Query Parameters:

  • date: Date to summarize (YYYY-MM-DD)

Response: Daily summary data.

GET /api/summary/weekly

Get weekly expense summary.

Query Parameters:

  • start_date: Start of week (YYYY-MM-DD)

Response: Weekly summary data.

GET /api/summary/monthly

Get monthly expense summary.

Query Parameters:

  • month: Month (1-12)
  • year: Year (YYYY)

Response: Monthly summary data.

GET /api/summary/yearly

Get yearly expense summary.

Query Parameters:

  • year: Year (YYYY)

Response: Yearly summary data.

GET /api/summary/custom

Get summary for a custom date range.

Query Parameters:

  • start_date: Start date (YYYY-MM-DD)
  • end_date: End date (YYYY-MM-DD)

Response: Custom period summary data.

Categories

GET /api/categories

List all categories.

Response: List of expense categories.

POST /api/categories

Create a new category.

Request Body:

{
  "name": "Materials",
  "description": "Construction materials",
  "color": "#FF5733"
}

Response: Created category details.

GET /api/categories/{id}

Get a specific category.

Response: Category details.

PUT /api/categories/{id}

Update a specific category.

Request Body: Same as POST with fields to update.

Response: Updated category details.

DELETE /api/categories/{id}

Delete a specific category.

Response: Confirmation of deletion.

Tags

GET /api/tags

List all tags.

Response: List of all tags.

POST /api/tags

Create a new tag.

Request Body:

{
  "name": "Urgent",
  "color": "#FF0000"
}

Response: Created tag details.

GET /api/tags/{id}

Get a specific tag.

Response: Tag details.

PUT /api/tags/{id}

Update a specific tag.

Request Body: Same as POST with fields to update.

Response: Updated tag details.

DELETE /api/tags/{id}

Delete a specific tag.

Response: Confirmation of deletion.

GET /api/expenses/{id}/tags

Get all tags associated with an expense.

Response: List of tags.

POST /api/expenses/{id}/tags

Add a tag to an expense.

Request Body:

{
  "tag_id": 1
}

Response: Confirmation of tag addition.

DELETE /api/expenses/{expenseId}/tags/{tagId}

Remove a tag from an expense.

Response: Confirmation of tag removal.

Currencies

GET /api/currencies

List all currencies.

Response: List of all currencies.

POST /api/currencies

Create a new currency.

Request Body:

{
  "code": "USD",
  "name": "US Dollar",
  "symbol": "$",
  "exchange_rate": 1.0
}

Response: Created currency details.

GET /api/currencies/{id}

Get a specific currency by ID.

Response: Currency details.

GET /api/currencies/code/{code}

Get a specific currency by code.

Response: Currency details.

PUT /api/currencies/{id}

Update a specific currency.

Request Body: Same as POST with fields to update.

Response: Updated currency details.

DELETE /api/currencies/{id}

Delete a specific currency.

Response: Confirmation of deletion.

GET /api/currencies/base

Get the base currency.

Response: Base currency details.

PUT /api/currencies/{id}/base

Set a currency as the base currency.

Response: Confirmation of base currency update.

POST /api/currencies/exchange-rates

Update exchange rates for all currencies.

Request Body:

{
  "rates": {
    "EUR": 0.85,
    "GBP": 0.75,
    "JPY": 110.25
  }
}

Response: Confirmation of exchange rates update.

Teams

GET /api/teams

List all teams for the authenticated user.

Response: List of teams.

POST /api/teams

Create a new team.

Request Body:

{
  "name": "Construction Team A",
  "description": "Team responsible for north site projects"
}

Response: Created team details.

GET /api/teams/{id}

Get a specific team by ID.

Response: Team details.

PUT /api/teams/{id}

Update a specific team.

Request Body: Same as POST with fields to update.

Response: Updated team details.

DELETE /api/teams/{id}

Delete a specific team.

Response: Confirmation of deletion.

GET /api/teams/{id}/members

Get all members of a team.

Response: List of team members.

POST /api/teams/{id}/members

Add a member to a team.

Request Body:

{
  "user_id": 123,
  "role": "member"
}

Response: Confirmation of member addition.

DELETE /api/teams/{id}/members/{userId}

Remove a member from a team.

Response: Confirmation of member removal.

PUT /api/teams/{id}/members/{userId}/role

Update a team member's role.

Request Body:

{
  "role": "admin"
}

Response: Confirmation of role update.

GET /api/teams/{id}/expenses

Get all expenses shared with a team.

Response: List of team expenses.

GET /api/teams/{id}/expenses/summary

Get summary of expenses for a team.

Response: Team expense summary.

POST /api/expenses/{expenseId}/share

Share an expense with a team.

Request Body:

{
  "team_id": 1
}

Response: Confirmation of expense sharing.

POST /api/expenses/{expenseId}/unshare

Unshare an expense from a team.

Request Body:

{
  "team_id": 1
}

Response: Confirmation of expense unsharing.

Team Roles and Permissions

GET /api/roles/{role}/permissions

Get all permissions for a specific role.

Response: List of permissions.

GET /api/roles

Get all roles and their permissions.

Response: List of roles with permissions.

GET /api/teams/{id}/permissions

Get user permissions in a team.

Response: List of user permissions.

Activity Logs

GET /api/activity

Get activity logs for the authenticated user.

Query Parameters:

  • page: Page number
  • limit: Number of items per page
  • start_date: Filter by start date
  • end_date: Filter by end date

Response: List of activity logs.

GET /api/activity/recent

Get recent activity for the authenticated user.

Query Parameters:

  • limit: Number of items (default: 10)

Response: List of recent activity logs.

GET /api/teams/{id}/activity

Get activity logs for a team.

Query Parameters: Same as /api/activity.

Response: List of team activity logs.

GET /api/teams/{id}/activity/recent

Get recent activity for a team.

Query Parameters:

  • limit: Number of items (default: 10)

Response: List of recent team activity logs.

GET /api/activity/{entity_type}/{entity_id}

Get activity logs for a specific entity.

Query Parameters: Same as /api/activity.

Response: List of entity activity logs.

Security

GET /api/security/audit-logs

Get security audit logs. Admin only.

Query Parameters:

  • page: Page number
  • limit: Number of items per page
  • start_date: Filter by start date
  • end_date: Filter by end date

Response: List of security audit logs.

GET /api/security/status

Get security status. Admin only.

Response: System security status.

GET /api/security/login-history

Get login history for the authenticated user.

Query Parameters:

  • limit: Number of items (default: 20)

Response: Login history.

GET /api/security/lockout-status

Get account lockout status.

Response: Account lockout status.

POST /api/security/unlock-user

Unlock a user account. Admin only.

Request Body:

{
  "user_id": 123
}

Response: Confirmation of account unlock.

POST /api/security/reset-rate-limit

Reset rate limit for a user. Admin only.

Request Body:

{
  "user_id": 123,
  "ip_address": "192.168.1.1"
}

Response: Confirmation of rate limit reset.

Security Dashboard

GET /api/security/dashboard/overview

Get security overview data.

Response: Security overview statistics.

GET /api/security/dashboard/timeline

Get security event timeline.

Query Parameters:

  • days: Number of days of history (default: 30)

Response: Security event timeline.

GET /api/security/dashboard/anomalies

Get security anomaly data.

Response: Security anomalies detected.

Geolocation

GET /api/security/location-history

Get location history for the authenticated user.

Response: Location history.

GET /api/security/suspicious-logins

Get suspicious logins. Admin only.

Response: List of suspicious logins.

POST /api/security/test-geolocation

Test geolocation service. Admin only.

Request Body:

{
  "ip_address": "1.2.3.4"
}

Response: Geolocation data.

Analytics

GET /api/analytics/trends

Get expense trends.

Query Parameters:

  • period: Time period (week, month, quarter, year)
  • count: Number of periods (default: 6)

Response: Expense trend data.

GET /api/analytics/anomalies

Get expense anomalies.

Query Parameters:

  • sensitivity: Anomaly detection sensitivity (1-10)

Response: Expense anomalies detected.

GET /api/analytics/forecast

Get expense forecast.

Query Parameters:

  • months: Number of months to forecast (default: 3)

Response: Expense forecast data.

Permission Management

Admin Permission Templates

GET /api/admin/permissions/templates

Get all permission templates. Admin only.

Response: List of templates.

POST /api/admin/permissions/templates

Create a permission template. Admin only.

Request Body:

{
  "name": "Limited Access",
  "description": "View only access to expenses",
  "permissions": [
    {
      "resource_type": "expense",
      "permission": "view"
    }
  ]
}

Response: Created template details.

GET /api/admin/permissions/templates/{id}

Get a specific template. Admin only.

Response: Template details.

PUT /api/admin/permissions/templates/{id}

Update a template. Admin only.

Request Body: Same as POST with fields to update.

Response: Updated template details.

DELETE /api/admin/permissions/templates/{id}

Delete a template. Admin only.

Response: Confirmation of deletion.

Team Permission Management

GET /api/teams/{teamId}/permissions/templates

Get templates assigned to a team.

Response: List of team templates.

POST /api/teams/{teamId}/permissions/templates

Assign a template to a team.

Request Body:

{
  "template_id": 123
}

Response: Confirmation of template assignment.

DELETE /api/teams/{teamId}/permissions/templates/{templateId}

Remove a template from a team.

Response: Confirmation of template removal.

User Permission Management

GET /api/teams/{teamId}/permissions/users

Get user permissions in a team.

Response: List of user permissions.

POST /api/teams/{teamId}/permissions/users/grant

Grant a permission to a user.

Request Body:

{
  "user_id": 123,
  "resource_type": "expense",
  "permission": "create",
  "resource_id": 0
}

Response: Confirmation of permission grant.

DELETE /api/teams/{teamId}/permissions/users/{userId}

Revoke a user's permission.

Query Parameters:

  • resource_type: Resource type
  • permission: Permission name
  • resource_id: Resource ID (optional)

Response: Confirmation of permission revocation.

GET /api/teams/{teamId}/permissions/audit

Get permission audit log.

Response: Permission audit log.

API Documentation

GET /api/docs

Access the interactive API documentation (Swagger UI).

GET /api/docs/swagger.yaml

Get the OpenAPI specification file.

Error Codes

  • 400: Bad Request - Invalid parameters or request body
  • 401: Unauthorized - Authentication required
  • 403: Forbidden - Insufficient permissions
  • 404: Not Found - Resource not found
  • 409: Conflict - Resource already exists
  • 422: Unprocessable Entity - Validation error
  • 429: Too Many Requests - Rate limit exceeded
  • 500: Internal Server Error - Server-side error

Versioning

The current API version is v1.

Rate Limiting

The API implements rate limiting to prevent abuse. Limits are:

  • 100 requests per minute for general API endpoints
  • 5 login attempts per 5 minutes for authentication endpoints

When a rate limit is exceeded, the API returns a 429 Too Many Requests status code.

CORS

The API supports Cross-Origin Resource Sharing (CORS) for integration with web applications.