gemtrack-backend/API_DOCUMENTATION.md

Gem Track Backend - API Documentation Overview

Welcome to the backend API reference for Gem Track! This guide is designed to help frontend developers and API integrators understand the available resources, authentication flow, and how to start making requests locally.

Detailed OpenAPI Reference

The backend uses TSOA, which means that our API routes and schemas are strongly-typed and automatically generated.

You can access the full Interactive Swagger API documentation by navigating to: 👉 http://localhost:3000/docs

(Make sure you have started your Docker environment via docker compose up first)

From the Swagger UI, you can:

• Test Endpoints: Execute API requests directly from your browser.
• View Schemas: Inspect the exact JSON payload shapes for requests and responses.
• Download Specification: Grab the raw swagger.json file to auto-generate frontend SDKs/clients using generic tools (like OpenAPI Generator or Orval).

---

High-Level Capabilities

The API exposes endpoints divided into distinct domains:

1. Tenancy (/api/v1/tenants)

Gem Track is a multi-tenant application. Every organization runs in its own tenant container.

• POST /api/v1/tenants: Onboard a new tenant (this sets up default DB rows, billing plans, roles, and permissions).
• GET /api/v1/tenants/{tenantId}: Fetch details about an active tenant.

2. Authentication (/api/v1/auth)

Tokens are issued via JWT and must be provided natively in the Authorization header (Bearer <token>).

• POST /api/v1/auth/register: Enroll the first administrator user for a new tenant.
• POST /api/v1/auth/login: Acquire a JWT credential by authenticating.
• GET /api/v1/auth/me: Returns profile info, active roles, and authorization scopes (permissions) for the current user.

3. User Management (/api/v1/users)

• POST /api/v1/users: Directly create a new user profile inside a tenant.
• POST /api/v1/users/invite: Issue an invitation to a new team member.
• PATCH /api/v1/users/{userId}/roles: Assign operational security roles (tenant_admin or tenant_user).
• PATCH /api/v1/users/{userId}/status: Adjust user standing (active/suspended).
• GET /api/v1/users/{userId}: Extract scoped profile details.

4. Billing (/api/v1/billing)

Tracks the assigned tier usage context logic.

• GET /api/v1/billing/subscription: Pull the current subscription parameters (e.g., Free vs Pro vs Enterprise limits).
• POST /api/v1/billing/subscription/plan: Downgrade/Upgrade the overarching plan context constraints.
• GET /api/v1/billing/history: Return paginated historical statement data.

5. Task Management (/api/v1/tasks)

Agile tracking mechanics for users operating within the ecosystem.

• POST /api/v1/tasks: Map a new task context.
• GET /api/v1/tasks: Read parameters, scope visibility based on user tenant constraints.
• PATCH /api/v1/tasks/{taskId} & Sub-Tasks: Mutate progress milestones spanning assignments.

6. Document Management (/api/v1/documents)

• POST /api/v1/documents: Implements multi-part form data uploads for handling physical file ingest scaling.
• GET /api/v1/documents: Retrieves associated files stored alongside records.

---

Common Workflows

System Setup

1. Create the Tenant: Hit POST /api/v1/tenants
2. Create the Admin User: Hit POST /api/v1/auth/register using the UUID returned from step 1.
3. Login in App: Send credentials via POST /api/v1/auth/login and persist the generated accessToken.

Authenticating Requests

Once you have the accessToken from login, all requests tagged with the lock icon in Swagger (which require the bearerAuth security schema) must include the following header:

Authorization: Bearer <your-access-token>