Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/IvanchoDev89/maleku-system/llms.txt

Use this file to discover all available pages before exploring further.

The Maleku System REST API powers a full-stack multi-vendor tourism marketplace for Costa Rica. It is built on FastAPI and exposes a versioned JSON API that lets client applications browse and book properties, tours, vehicles, boats, and more — while giving vendors a complete management interface and superadmins full platform oversight. All responses are JSON; all authenticated requests must carry a JWT Bearer token issued at login or registration.

​
Base URL

EnvironmentURL
Productionhttps://api.costaricatravel.dev/api/v1
Local devhttp://localhost:8000/api/v1
Every endpoint documented in this reference is relative to the base URL above. For example, the login endpoint is reached at https://api.costaricatravel.dev/api/v1/auth/login.

​
Interactive Docs

When the server is running in debug mode, auto-generated interactive documentation is available at:
InterfacePath
Swagger UI/docs
ReDoc/redoc
OpenAPI spec (JSON)/openapi.json
The interactive docs UIs are disabled in production (DEBUG=false). Use the endpoints at https://api.costaricatravel.dev/docs only in staging or local environments.

​
Authentication

All protected endpoints require a JWT Bearer token in the Authorization header: 
Authorization: Bearer <access_token>
Tokens are obtained by calling POST /auth/register or POST /auth/login. Access tokens expire after 60 minutes by default (ACCESS_TOKEN_EXPIRE_MINUTES in config). Use POST /auth/refresh with your refresh token to obtain a new access token before expiry. See the full Authentication reference for registration, login, refresh, logout, password reset, and email verification flows.

​
Versioning

All endpoints live under the /api/v1/ prefix. The current and only stable version is v1. Breaking changes will be introduced under a new version prefix (e.g. /api/v2/) rather than altering existing routes. 
GET https://api.costaricatravel.dev/api/v1/tours/

​
Pagination

Most list endpoints return a paginated PaginatedResponse envelope. Use page and page_size query parameters to control the window of results.
ParameterTypeDefaultMaximumDescription
pageinteger1—1-based page number
page_sizeinteger20100Items per page
Some endpoints (such as the admin users list) also accept skip + limit as an alternative style. Check the individual endpoint reference for which parameters it supports. Paginated response envelope: 
{
  "items": [...],
  "total": 245,
  "page": 2,
  "page_size": 20,
  "pages": 13,
  "has_next": true,
  "has_prev": true
}
Requesting page_size larger than 100 will result in a 422 Validation Error. Keep requests to 100 items or fewer per page.

​
Rate Limiting

The API enforces per-IP rate limits to protect platform stability.
ScopeLimit
General endpoints60 requests / minute
Auth endpoints (/auth/login, /auth/register)5 requests / minute
Forgot-password3 requests / minute
Booking creation10 requests / minute
When a limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. Rate limit state is tracked via Redis. Rate limit response headers (on successful requests): 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640995200

​
Error Responses

The API uses standard HTTP status codes. All error bodies follow a consistent JSON format: 
{
  "detail": "Human-readable error message"
}
Validation errors from Pydantic (status 422) include a structured detail array that names the field(s) that failed: 
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}
Common status codes:
CodeMeaningCommon Causes
400Bad RequestInvalid JSON, missing required fields, email already registered
401UnauthorizedMissing or invalid token, expired access token, revoked token
403ForbiddenInsufficient role or permission, inactive account, email not verified
404Not FoundResource does not exist or has been soft-deleted
409ConflictDuplicate email, booking date conflict
422Unprocessable EntityPydantic schema validation failed
423LockedAccount locked after too many failed login attempts
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server-side failure (logged via Sentry)

​
API Resources

Authentication

Register, login, refresh tokens, logout, password reset, and email verification.

Properties

Browse, create, and manage accommodation listings across Costa Rica.

Tours

Adventure, wildlife, beach, and cultural tours with filters and full-text search.

Vehicles & Boats

Vehicle rentals (SUVs, 4x4s) and boat charters available from vendors.

Bookings

Create and manage property, tour, vehicle, and boat bookings.

Payments

Stripe-powered checkout, webhook events, and commission handling.

Reviews

Read and submit reviews for properties, tours, vehicles, boats, and vendors.

Search

Full-text cross-entity search with location, price, and map data.

Destinations

Costa Rica destination guides linked to listings and tours.

Vendors

Vendor profiles, dashboards, verification status, and public listings.

Users

User profile management and admin user administration.

Superadmin

Platform-wide controls: user management, vendor approvals, audit logs, and settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us