# API Overview

Turista exposes a JSON REST API under the base URL `/api/v1`.

## Base URL

```
https://{your-domain}/api/v1
```

## Versioning

The current API version is `v1`. Versioning is path-based. Future versions will use a new path prefix (e.g., `/api/v2`).

## Headers

All requests should include:

```http
Accept: application/json
Content-Type: application/json
```

Authenticated requests must also include:

```http
Authorization: Bearer {sanctum_token}
```

## Authentication

See [`authentication.md`](authentication.md) for details on login, registration, OTP verification, password reset, and logout.

## Rate limiting

Public authentication endpoints (login, register, OTP) are rate-limited by IP and contact information. Authenticated endpoints generally use the default Laravel throttle. Specific limits are configured in `RouteServiceProvider` or route middleware.

## Response format

Successful responses return a 2xx status and a JSON body. The shape depends on the endpoint; see [`auto-generated.md`](auto-generated.md) for full schemas.

List endpoints typically return paginated data:

```json
{
  "data": [...],
  "links": {...},
  "meta": {...}
}
```

Single-resource endpoints return a resource object:

```json
{
  "data": {...}
}
```

## Error format

Errors are returned as JSON with an HTTP 4xx/5xx status. See [`architecture/error-handling.md`](../architecture/error-handling.md) for details.

## Filtering and sorting

List endpoints accept query parameters for filtering, sorting, and pagination. Common patterns:

- `?page=2`
- `?per_page=20`
- `?status=active`
- `?sort=-created_at`

Exact parameter names vary by endpoint. Use Laravel Request Docs for the full list.

## Role-specific endpoints

The API is organized by actor:

- [`Admin endpoints`](roles/admin.md)
- [`Owner endpoints`](roles/owner.md)
- [`Employee endpoints`](roles/employee.md)
- [`Customer endpoints`](roles/customer.md)

## Auto-generated reference

For exhaustive request/response schemas, see [`auto-generated.md`](auto-generated.md) on how to use Laravel Request Docs.