API Reference

Overview

MineSync uses tRPC for all client-server communication. There are no REST endpoints for core application features. The API is type-safe end-to-end, with input validation via Zod schemas and automatic TypeScript type inference on the client.

All API calls go through the tRPC handler at /api/trpc. Client-side hooks are generated from src/trpc/react.tsx and used as api.<router>.<procedure>.useQuery(...) or api.<router>.<procedure>.useMutation(...).

Authentication and Authorization

Procedure Types

Procedure	Auth Required	Tenant Scoped	Description
`publicProcedure`	No	No	Health checks and unauthenticated endpoints.
`protectedProcedure`	Yes	No	Requires a valid session. Guarantees `ctx.session.user` is non-null.
`tenantProcedure`	Yes	Yes	Extends `protectedProcedure`. Requires an `x-tenant-slug` header, verifies tenant existence and user membership. Adds `ctx.tenantId` and `ctx.membership`.

Role-Based Access

Procedures that require specific roles use the requireRole middleware:

.use(requireRole(["ADMIN"]))

See Roles and Permissions for the full role matrix.

Tenant Slug

All tenant-scoped API calls include the tenant slug via the x-tenant-slug HTTP header, which is automatically set by the tRPC client based on the current route (/t/[slug]/...).

API Routers

Core Fleet

Router	Key	Procedures
Vehicles	`vehicles`	List, get, create, update, delete fleet vehicles.
Fleet	`fleet`	Fleet-wide queries and statistics.
Meters	`meters`	Record and query meter readings (SMU/hours).
Maintenance Logs	`maintenanceLogs`	Component change-out and maintenance event history.

Lifecycle Management

Router	Key	Procedures
Dashboard	`dashboard`	Dashboard summary statistics and charts.
Profiles	`profiles`	Asset lifecycle profiles and event configuration.
Profile Templates	`profileTemplates`	Reusable profile templates.
Work Orders	`workOrders`	Full work order CRUD, status transitions, assignment.
TCO	`tco`	Total cost of ownership calculations and scenarios.

Parts Management

Router	Key	Procedures
Parts	`parts`	Parts catalog and inventory.
BOM	`bom`	Bill of materials for vehicles.
Standard Jobs	`standardJobs`	Reusable job templates with parts and labor.

Benchmark

Router	Key	Procedures
Benchmark Data	`benchmarkData`	CRUD for failure data, lifecycle stats, Weibull analysis, fleet comparison, risk scoring, cost impact, seasonal analysis, site comparison, and component hierarchy.

Scheduler

Router	Key	Procedures
Scheduler	`scheduler`	Schedule scenarios, tasks, and Gantt chart data.
Scheduler Resources	`schedulerResources`	Bay, crew, and resource management.
Scheduler Config	`schedulerConfig`	Scheduler settings and constraint rules.
Scheduler Approvals	`schedulerApprovals`	Multi-level approval workflows.

AI

Router	Key	Procedures
AI	`ai`	AI settings, model discovery, provider checks, conversation CRUD, and message persistence.

Master Data

Router	Key	Procedures
OEMs	`oems`	Equipment manufacturer catalog.
Models	`models`	Equipment model catalog.
Machine Families	`machineFamilies`	Machine family groupings.
Component Catalog	`componentCatalog`	Component type catalog with hierarchy.
Machine Positions	`machinePositions`	Physical positions on machines.
Work Activities	`workActivities`	Maintenance work activity definitions.
Component Categories	`componentCategories`	Component grouping categories.
Location Categories	`locationCategories`	Site location categories.

Administration

Router	Key	Procedures
Sites	`sites`	Mine site management.
Companies	`companies`	Company / tenant information.
Members	`members`	Tenant membership and role management.
Settings	`settings`	Tenant-level feature flags and configuration.
Account	`account`	User account and profile management.
Notifications	`notifications`	User notification preferences and delivery.
Billing	`billing`	Subscription and billing information.
Audit	`audit`	Audit trail queries.
Themes	`themes`	UI theme preferences.
Backup	`backup`	Database backup and selective restore.
Update	`update`	Application update checking.
SQL	`sql`	Direct SQL query execution (admin only).

Search

Router	Key	Procedures
Search	`search`	Global search across entities (Cmd+K).

Input Validation

All procedure inputs are validated with Zod schemas before execution. Invalid inputs return a structured error with the Zod validation details in error.data.zodError.

Error Handling

tRPC errors use standard codes:

Code	Meaning
`UNAUTHORIZED`	No valid session.
`FORBIDDEN`	Valid session but insufficient role or no tenant membership.
`NOT_FOUND`	Requested resource does not exist or is not accessible.
`BAD_REQUEST`	Missing required input (e.g., no tenant slug).

Data Serialization

MineSync uses SuperJSON as its tRPC transformer. This means Date objects, BigInt values, Maps, and Sets are automatically serialized and deserialized across the wire.

Common Questions

Can I call the API from outside the browser?

Yes, but you need a valid session token. Use pnpm test:token (with the dev server running) to get a token for testing. Include it as a cookie or authorization header.

Is there a REST API?

There are no REST endpoints for core features. The AI router includes OpenAPI metadata annotations for potential future OpenAPI generation, but all production calls go through tRPC.

How do I find the exact input schema for a procedure?

Look at the router file in src/server/api/routers/. Each procedure's .input() call contains the Zod schema with all fields, types, and validation rules.