Skip to main content

API Overview

Introduction​

ForgeX is a microservices-based API platform designed for construction estimation and project management. The system consists of three independent services, each handling a specific domain.

Services​

🧮

Bids Service

Estimation and bid management with comprehensive cost tracking

💼

Projects Service

Purchase orders and cost tracking for active projects

🕐

Field Service

Timesheets and GPS tracking for field workers

Base URLs​

Development​

Bids:     http://localhost:5001/api
Projects: http://localhost:5002/api
Field:    http://localhost:5003/api

Production​

Bids:     https://bids.precisionsiteservices.com/api
Projects: https://projects.precisionsiteservices.com/api
Field:    https://field.precisionsiteservices.com/api

Authentication​

All endpoints require session authentication via SuperTokens. See the Authentication section for details.

Sessions are managed using HTTP-only cookies (sAccessToken, sRefreshToken) shared across the .precisionsiteservices.com domain.

Cookie: sAccessToken=...; sRefreshToken=...

Response Formats​

Success Response (200/201)​

{
  "id": "uuid",
  "message": "Operation successful",
  ...resource data
}

Error Response (400 Bad Request)​

{
  "error": "Validation error message"
}

Error Response (401 Unauthorized)​

{
  "error": "Unauthorized"
}

Error Response (403 Forbidden)​

{
  "error": "Insufficient permissions"
}

Error Response (404 Not Found)​

{
  "error": "Resource not found"
}

Multi-Status Response (207)​

Used for batch operations where some succeed and others fail:

{
  "attachments": [
    { "id": "uuid1", "filename": "file1.pdf", ... }
  ],
  "failed": [
    { "filename": "file2.pdf", "error": "File too large" }
  ]
}

Common Conventions​

Date/Time Format​

All timestamps use ISO 8601 format (UTC):

2025-01-29T10:00:00.000Z

UUID Format​

All IDs use UUID v4:

550e8400-e29b-41d4-a716-446655440000

Pagination​

List endpoints support pagination via query parameters:

?limit=50&offset=0

Filtering​

Most list endpoints support filtering:

?status=ACTIVE&role=ESTIMATOR&search=john

Role-Based Access Control​

ServiceADMINESTIMATORPMOPSACCOUNTINGFOREMAN
BidsFullFull (no delete)Read-only---
ProjectsFull-Approve POsCreate/Manage POsReconcile-
FieldFull-Approve timesheets--Clock in/out

API Versioning​

Currently using v1 (implicit). Future versions will be prefixed:

/api/v2/bids

Rate Limiting​

warning

Rate limits are not currently enforced but may be added in future versions.

Support​

For API support, contact: