API Overview

Tracera REST and WebSocket API reference

API Overview

Tracera exposes a RESTful API under /api/v1 and a WebSocket endpoint for real-time updates.

Base URL

http://localhost:8080/api/v1

In production, replace with your configured BASE_URL.

Authentication

Most endpoints are public. Authenticated endpoints require a valid session cookie (set during login). The session is managed server-side in Redis.

To check authentication status:

curl http://localhost:8080/api/v1/auth/me \
  -b cookies.txt

CSRF Protection

State-changing endpoints (POST, PUT, DELETE) on authenticated routes require a CSRF token:

1. Fetch the token:

   curl http://localhost:8080/api/v1/auth/csrf \
     -b cookies.txt
   

2. Include it in subsequent requests:

   curl -X POST http://localhost:8080/api/v1/auth/logout \
     -b cookies.txt \
     -H "X-CSRF-Token: {token}"
   

Rate Limiting

Authentication endpoints are rate-limited to 20 requests per minute per IP address.

Response Format

All API responses use JSON. Successful responses return the resource directly. Error responses follow this format:

{
  "error": "Description of what went wrong"
}

Endpoint Groups

Group	Base Path	Auth Required	Status	Description
Health	/api/v1/health	No	✅ Live	Service health status
Auth	/api/v1/auth/*	Varies	✅ Live	Authentication and session management
Items	/api/v1/items/*	No	🔜 Planned	Item metadata, prices, and volatility
Portfolio	/api/v1/portfolio/*	Yes	🔜 Planned	Portfolio management and valuation
WebSocket	/api/v1/ws	No	🔜 Planned	Real-time price and volatility updates