API Overview¶

REST API conventions for Quorvex AI. For the full endpoint catalog, see API Endpoints.

Base URL¶

http://localhost:8001

Interactive Documentation¶

Authentication¶

Authentication is optional by default (REQUIRE_AUTH=false). When enabled, the API uses JWT bearer tokens.

Token Flow¶

1. POST /auth/register (if ALLOW_REGISTRATION=true)
2. POST /auth/login returns access token + refresh token
3. Include Authorization: Bearer <access_token> on requests
4. POST /auth/refresh with refresh token to get new access token

Token Lifetimes¶

Token Payload¶

Algorithm: HS256. Secret: JWT_SECRET_KEY environment variable.

Password Requirements¶

Minimum 8 characters, at least one uppercase letter, one lowercase letter, one digit, and one special character.

Account Lockout¶

5 consecutive failed login attempts locks the account for 30 minutes.

User Roles¶

Superusers have full access to all projects and /users admin endpoints.

Request Format¶

Content type: application/json (file uploads use multipart/form-data).

Common Query Parameters¶

Path Parameters¶

Spec names and folder paths use FastAPI {name:path} syntax, allowing slashes: GET /specs/folder/subfolder/my-test.md

Response Format¶

Success¶

Single resource:

{"id": "...", "status": "passed"}

Paginated list:

{"items": [...], "total": 142, "limit": 20, "offset": 0, "has_more": true}

Error Codes¶

Error Response Shape¶

{"detail": "Spec not found"}

Validation errors (422):

{"detail": [{"loc": ["body", "field"], "msg": "field required", "type": "value_error.missing"}]}

Rate Limiting¶

Backend: slowapi with Redis (production) or in-memory (development).

Global Default¶

1000 requests per hour per IP address (or per authenticated user ID).

Per-Endpoint Limits¶

Rate Limit Key¶

Authenticated user ID when available, otherwise client IP address.

Pagination¶

Server-Sent Events¶

Stream terminates on: terminal status, 10 minutes inactivity, or server error.

File Upload Constraints¶

CORS¶

Configured via ALLOWED_ORIGINS environment variable (comma-separated). Default: http://localhost:3000.

Request Logging¶

Every request receives an X-Request-ID header (UUID) for traceability.

Router Organization¶

Related¶

• API Endpoints
• Environment Variables