API Overview

To see which endpoints the Vue client actually calls (and how), see Frontend API Integration.

Interactive API Route Map

Searchable, filterable diagram of all 150+ routes, controllers, and middleware — current API, legacy v1, and web routes.

Base URLs

Environment	URL
Local (Docker)	`http://localhost/api`
Staging	Configured via `APP_URL` env var
Production	Configured via `APP_URL` env var

API versions

Two API versions coexist:

Version	Prefix	Route file	Controller namespace
Current	`/api/*`	`routes/api.php`	`tutorbloc\Http\Controllers`
Legacy v1	`/api/v1/*`	`routes/legacy-api.php`	`tutorbloc\Http\Controllers\v1`

The current API also supports header-based versioning via the API-Version request header. Controllers dynamically resolve service and transformer classes based on this header.

Authentication

Three authentication modes are used across endpoints:

Middleware	Header/param	Description
`auth:api`	`Authorization: Bearer {token}`	Standard token auth via Redis guard
`web.api`	Token, signed URL, or `secret` param	Hybrid auth (see Authentication)
`internal`	Requires `auth:api` + role_id=200	Admin-only operations
(none)	—	Public endpoint

Rate limiting

API endpoints are throttled at 300 requests per minute per client (configured in app/Http/Kernel.php).

CORS

CORS is handled by the TrustedOrigins middleware (not Laravel’s built-in CORS package):

Exact match: TRUSTED_ORIGINS env var — comma-separated origins
Substring match: WHITELISTED_ORIGINS env var — comma-separated partial origins

Returns 403 if the Origin header doesn’t match either list.

Response format

All API responses are JSON. Errors follow this structure:

{
  "message": "Error description",
  "details": { ... },
  "exception": "ClassName",
  "trace": [...]
}

exception and trace fields are only included when APP_DEBUG=true.

HTTP caching

The ETag middleware (app/Http/Middleware/API/v1/ETag.php) adds ETag-based caching for GET requests. Returns 304 Not Modified when the client’s If-None-Match header matches.

Security headers

All responses include (via SecureHeaders middleware):

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Referrer-Policy: no-referrer-when-downgrade

Headers removed: X-Powered-By, Server.

Interactive API Route Map

​Base URLs

​API versions

​Authentication

​Rate limiting

​CORS

​Response format

​HTTP caching

​Security headers

Base URLs

API versions

Authentication

Rate limiting

CORS

Response format

HTTP caching

Security headers