TenderCheck AI REST API Reference

TenderCheck AI exposes a JSON REST API built on Express and TypeScript. All endpoints return application/json responses. Protected routes require an authenticated session via an HttpOnly cookie or an Authorization: Bearer header — the API accepts both so the same backend serves browser clients and programmatic integrations equally.

Base URL

The frontend resolves the API origin from the VITE_API_BASE_URL environment variable. All API endpoints are prefixed with /api.

# .env (frontend)
VITE_API_BASE_URL=https://tendercheckai.elecodes.online

Every request path follows the pattern:

https://tendercheckai.elecodes.online/api/<resource>

In local development, omit VITE_API_BASE_URL (or set it to an empty string) and configure your Vite dev server proxy to forward /api requests to http://localhost:3001. The frontend will then use relative paths automatically.

Authentication

Protected routes require a valid JWT supplied in one of two ways:

HttpOnly cookie — the token cookie set by the server on login. Sent automatically by the browser when credentials: 'include' is used.
Bearer token header — Authorization: Bearer <token> for environments where cookies are unreliable (native apps, server-to-server calls, cross-origin setups).

The authMiddleware checks the cookie first, then falls back to the header. See Authentication for the full flow, token lifecycle, and code examples.

Endpoint Summary

Method	Path	Auth Required	Description
`POST`	`/api/auth/register`	No	Register a new user account
`POST`	`/api/auth/login`	No	Login with email + password, sets HttpOnly cookie
`POST`	`/api/auth/google/callback`	No	Exchange Google OAuth PKCE code for a session
`POST`	`/api/auth/logout`	No	Clear the session cookie
`GET`	`/api/auth/me`	Yes	Get the currently authenticated user
`POST`	`/api/auth/reset-password-request`	No	Request a password reset email
`POST`	`/api/tenders/analyze`	Yes	Upload a tender PDF for AI analysis
`POST`	`/api/tenders/:id/validate-proposal`	Yes	Upload a proposal PDF for compliance validation
`GET`	`/api/tenders`	Yes	List the current user’s analysis history
`DELETE`	`/api/tenders/:id`	Yes	Delete an analysis record (owner only)

Error Format

All errors are serialised by the global error handler into a consistent JSON envelope. The error and message fields both contain the human-readable description; status is the string literal "error".

interface ApiErrorResponse {
  status: "error";    // always the string "error"
  error: string;      // human-readable message (operational errors)
  message: string;    // same value as error (backward-compatibility alias)
  stack?: string;     // only present in development mode
}

Example — 401 Unauthorized:

{
  "status": "error",
  "error": "No authorization token provided",
  "message": "No authorization token provided"
}

Example — non-operational error (production):

{
  "status": "error",
  "error": "Something went wrong",
  "message": "Something went wrong"
}

In development mode the error response also includes a stack field with the full stack trace to aid debugging. This field is never present in production. For non-operational errors (unexpected crashes), the error and message values are always "Something went wrong" regardless of the underlying message, to avoid leaking implementation details.

Common Status Codes

Code	Meaning	Typical Cause
`400`	Bad Request	Validation error, missing required field, invalid file type
`401`	Unauthorized	Missing, expired, or invalid JWT
`403`	Forbidden	Authenticated but not the resource owner
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Login rate limit exceeded
`500`	Internal Server Error	Unexpected server-side failure
`503`	Service Unavailable	Database connection failure

Rate Limiting

The login endpoints are protected by a sliding-window rate limiter configured in constants.ts:

Constant	Value	Meaning
`RATE_LIMIT_WINDOW_MS`	`60 000 ms` (1 minute)	Rolling window duration
`RATE_LIMIT_MAX_ATTEMPTS`	`300`	Max requests per window

The limiter is applied to:

POST /api/auth/login
POST /api/auth/google/callback

When the limit is exceeded the API responds with HTTP 429 and the following body:

{
  "error": "Too many login attempts, please try again after 15 minutes"
}

Standard rate-limit headers (RateLimit-*) are included in every response from these endpoints (standardHeaders: true).

File Upload Limits

File uploads are handled via multipart/form-data using Multer in-memory storage. The following limits apply globally to all upload endpoints:

Constraint	Value
Maximum file size	50 MB (`FILE_UPLOAD_LIMIT_MB = 50`)
Accepted MIME type	`application/pdf` only

Uploading a file that exceeds 50 MB returns HTTP 400 with the message:

{
  "status": "error",
  "error": "File is too large. Maximum allowed size is 50MB.",
  "message": "File is too large. Maximum allowed size is 50MB."
}

Uploading a non-PDF file returns HTTP 400 with:

{
  "status": "error",
  "error": "Invalid file type. Only PDF documents are allowed.",
  "message": "Invalid file type. Only PDF documents are allowed."
}

CORS

Allowed origins are driven by the ALLOWED_ORIGINS environment variable on the backend — a comma-separated list of fully-qualified frontend URLs:

# .env (backend)
ALLOWED_ORIGINS=https://tendercheckai.elecodes.online,https://staging.elecodes.online

The following request headers are whitelisted:

Content-Type
Authorization
Cache-Control
Pragma
Expires
X-Requested-With

Credentials (cookies) are supported — the CORS configuration sets credentials: true, which means your frontend requests must include credentials: 'include'.

In production, any origin not listed in ALLOWED_ORIGINS is blocked. Requests from unlisted origins receive an HTTP error and the server logs a [CORS] Blocked origin warning. localhost and 127.0.0.1 are always permitted in non-production environments.

Authentication

Tender Endpoints

Analyze tender documents, validate proposals, manage your analysis history.

​Base URL

​Authentication

​Endpoint Summary

​Error Format

​Common Status Codes

​Rate Limiting

​File Upload Limits

​CORS

Authentication

Tender Endpoints

Base URL

Authentication

Endpoint Summary

Error Format

Common Status Codes

Rate Limiting

File Upload Limits

CORS