Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jhonyes04/new-wayfy/llms.txt

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

The WayFy API is a RESTful HTTP API built with Python Flask, designed for developers integrating with or extending the WayFy accessibility-focused travel platform. Whether you’re building a third-party client, automating trip planning workflows, or extending WayFy’s core feature set, every capability — from user management and AI-powered map chat to accessibility photo submissions — is exposed through a consistent, JSON-based interface secured with JWT Bearer token authentication.

​
Base URL

The API server runs locally on port 3001. In deployed environments, the base URL is configured via the VITE_BACKEND_URL environment variable on the frontend. All routes are mounted under the /api prefix. 
# Local development
http://localhost:3001/api

# Production (set via VITE_BACKEND_URL on the frontend)
https://<your-domain>/api

​
Route Prefixes

All WayFy API endpoints are grouped into six blueprints, each serving a distinct area of the platform:
PrefixPurpose
/api/usersUser registration, login, profile management, and avatar uploads
/api/aiAI-powered map chat (MapGPT), geocoding, and point-of-interest search
/api/accessibilityAccessibility feature submissions, ratings, and photo uploads
/api/tripsTrip creation, management, itinerary building, and cover images
/api/placesCommunity place submissions and bounding-box map queries
/api/utilsOpen Graph image extraction and Google Places photo enrichment

​
Authentication

All protected endpoints require a JWT Bearer token in the Authorization header. Tokens are issued at login or registration and expire after a configurable period (default: 1 hour). See the Authentication page for the full token flow. 
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

​
Error Responses

WayFy uses a consistent error envelope across all endpoints. Errors are raised via the internal APIException class (defined in api/utils.py) and caught globally in app.py. Every error response is a JSON object with an appropriate HTTP status code. Depending on the origin of the error, the key will be either message (application-level exceptions raised via APIException) or msg (controller-level errors and JWT/auth library errors): 
// Application error via APIException
{
  "message": "A trip with this name already exists."
}

// Controller or JWT error
{
  "msg": "Token has expired"
}
Common HTTP status codes returned by the API:
StatusMeaning
200Success
201Resource created
400Bad request — missing or invalid fields
401Unauthorized — missing, invalid, or expired token
403Forbidden — insufficient permissions
404Resource not found
429Too many requests — rate limit exceeded
500Internal server error

​
Rate Limits

Rate limiting is applied via Flask-Limiter on endpoints that perform expensive operations such as AI inference and geocoding. Limits are enforced per client IP address.
EndpointMethodLimit
/api/ai/mapgptPOST20 requests / minute
/api/ai/geocodeGET30 requests / minute
/api/ai/geocode-poiGET30 requests / minute
/api/utils/og-imageGET60 requests / minute
/api/utils/google-photoGET60 requests / minute
When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests. Build retry logic with exponential backoff in any client that calls the AI or geocoding endpoints heavily.
Rate limits apply per IP address. If you’re running automated tests or batch jobs, be mindful of the 20 req/min cap on /api/ai/mapgpt in particular — it is the most restrictive limit in the API.

​
CORS Configuration

Cross-Origin Resource Sharing is configured on the WayFy backend via the CORS_ALLOWED_ORIGINS environment variable. Provide a comma-separated list of allowed origins: 
# .env (backend)
CORS_ALLOWED_ORIGINS=http://localhost:5173,https://app.wayfy.com
If your frontend origin is not included in this list, browsers will block requests to the API. During local development, ensure http://localhost:5173 (or whichever port Vite uses) is present in the list.

​
Static Asset Endpoints

The following endpoints serve binary files (images). The avatar endpoint requires authentication; cover images and accessibility photos are publicly accessible without a token.
EndpointAsset TypeAuth Required
GET /api/users/avatar/<filename>User profile avatar imagesYes
GET /api/accessibility/photos/<filename>Accessibility feature photosNo
GET /api/trips/cover/<filename>Trip cover imagesNo
Filenames for static assets are returned as part of the respective resource objects (e.g., the avatar field on a user object returns the full path /api/users/avatar/<filename>). Use the path directly as the src for <img> tags.

​
Authenticated Request Example

Here is a complete curl example of a request to a protected WayFy endpoint, including the Authorization header and Content-Type: 
curl -X GET "http://localhost:3001/api/trips/" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

​
Endpoint Groups

Users

Register accounts, log in, manage profiles, and upload avatars.

Trips

Create and manage trips, build itineraries, and upload cover images.

Accessibility

Submit and retrieve accessibility features, ratings, and photos.

Places

Submit community place pins and query the map by bounding box.

AI

Use MapGPT for conversational map queries and geocode addresses or POIs.

Utils

Fetch Open Graph preview images and Google Places photos for place cards.

Build docs developers (and LLMs) love

Get started for freeTalk to us