Trips & Itineraries API Reference

WayFy’s Trips API is the core itinerary engine. A trip contains one or more days, each of which holds an ordered list of places — points of interest with visit times, notes, and optional links to saved favorites. Trips can be kept private or published publicly for the WayFy community to discover and fork into their own itineraries.

Endpoints that accept optional JWT (optional jwt) will return public trip data when called without a token. Passing a valid token additionally exposes the caller’s own private trips where relevant.

Trips

POST /api/trips/

Creates a new trip for the authenticated user. The trip starts private by default — set is_public: true to publish it immediately. Authentication: Required

Request

title

string

required

Name of the trip (e.g. "Accessible Weekend in Lisbon").

description

string

A longer description of the trip, its highlights, or accessibility notes.

is_public

boolean

Whether the trip is visible to the WayFy community. Defaults to false.

Response

Returns 201 Created with a wrapper containing the new trip object.

msg

string

Confirmation message.

trip

object

Show Trip object

integer

Unique trip ID.

user_id

integer

ID of the owning user.

author

object

Object with firstname and lastname of the trip owner.

title

string

Trip title.

description

string

Trip description.

is_public

boolean

Public visibility flag.

cover_image

string

Full cover image path (e.g. /api/trips/cover/filename.jpg), or null until one is uploaded.

original_trip_id

integer

ID of the source trip if this was forked. null for original trips.

fork_count

integer

Number of times this trip has been forked.

total_days

integer

Number of days in this trip.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

Example

curl -X POST http://localhost:3001/api/trips/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Accessible Weekend in Lisbon",
    "description": "A curated 3-day itinerary covering wheelchair-friendly spots in central Lisbon.",
    "is_public": true
  }'

{
  "msg": "Viaje creado",
  "trip": {
    "id": 15,
    "user_id": 42,
    "author": { "firstname": "Ada", "lastname": "Lovelace" },
    "title": "Accessible Weekend in Lisbon",
    "description": "A curated 3-day itinerary covering wheelchair-friendly spots in central Lisbon.",
    "is_public": true,
    "cover_image": null,
    "original_trip_id": null,
    "fork_count": 0,
    "total_days": 0,
    "created_at": "2024-04-10T09:00:00Z",
    "updated_at": "2024-04-10T09:00:00Z"
  }
}

GET /api/trips/

Returns all trips belonging to the authenticated user. Authentication: Required

Response

total

integer

Number of trips returned.

trips

array

Array of trip objects for the authenticated user, ordered by creation date descending.

Show Trip object

integer

Trip ID.

user_id

integer

Owning user ID.

author

object

Object with firstname and lastname of the trip owner.

title

string

Trip title.

description

string

Trip description.

is_public

boolean

Visibility flag.

cover_image

string

Full cover image path or null.

original_trip_id

integer

Source trip ID if forked, else null.

fork_count

integer

Number of forks.

total_days

integer

Number of days in the trip.

created_at

string

Creation timestamp.

updated_at

string

Last-updated timestamp.

Example

curl http://localhost:3001/api/trips/ \
  -H "Authorization: Bearer <token>"

{
  "total": 1,
  "trips": [
    {
      "id": 15,
      "user_id": 42,
      "author": { "firstname": "Ada", "lastname": "Lovelace" },
      "title": "Accessible Weekend in Lisbon",
      "description": "A curated 3-day itinerary...",
      "is_public": true,
      "cover_image": "/api/trips/cover/lisbon_cover_1712345678.jpg",
      "original_trip_id": null,
      "fork_count": 2,
      "total_days": 3,
      "created_at": "2024-04-10T09:00:00Z",
      "updated_at": "2024-04-11T12:30:00Z"
    }
  ]
}

GET /api/trips/public

Returns all trips marked is_public: true across the entire WayFy platform. Useful for the community discovery feed. Authentication: Optional

Response

total

integer

Number of public trips returned.

trips

array

Array of all public trip objects.

Example

curl http://localhost:3001/api/trips/public

{
  "total": 1,
  "trips": [
    {
      "id": 15,
      "user_id": 42,
      "author": { "firstname": "Ada", "lastname": "Lovelace" },
      "title": "Accessible Weekend in Lisbon",
      "is_public": true,
      "cover_image": "/api/trips/cover/lisbon_cover_1712345678.jpg",
      "original_trip_id": null,
      "fork_count": 2,
      "total_days": 3,
      "created_at": "2024-04-10T09:00:00Z",
      "updated_at": "2024-04-11T12:30:00Z"
    }
  ]
}

GET /api/trips/:trip_id

Returns a single trip including its days and places. Returns the trip if it is public, or if the authenticated user is the owner. Authentication: Optional

Private trips return 403 Forbidden when accessed without a valid token or by a non-owner.

Response

integer

Trip ID.

user_id

integer

Owning user ID.

author

object

Object with firstname and lastname of the trip owner.

title

string

Trip title.

description

string

Trip description.

is_public

boolean

Visibility flag.

cover_image

string

Full cover image path or null.

original_trip_id

integer

Source trip ID if forked, else null.

fork_count

integer

Number of forks.

total_days

integer

Number of days in the trip.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

days

array

Ordered array of trip day objects.

Show TripDay object

integer

Day ID.

trip_id

integer

Parent trip ID.

day_number

integer

Sequence number (1-indexed).

date

string

ISO 8601 date string (e.g. "2024-06-01") or null. Stored as a SQL Date type, serialized via .isoformat().

title

string

Day title.

notes

string

Free-form notes for the day.

places

array

Ordered array of places for this day.

Show TripDayPlace object

integer

Place entry ID.

trip_day_id

integer

Parent day ID.

favorite_id

integer

Linked favorite ID, or null.

place_name

string

Place name.

latitude

number

Latitude.

longitude

number

Longitude.

osm_id

string

OSM identifier.

sub_type

string

WayFy place category.

order

integer

Position within the day’s itinerary.

notes

string

Place-level notes.

visit_time

string

Planned visit start time as "HH:MM" string, or null. Stored as SQL Time.

visit_time_end

string

Planned visit end time as "HH:MM" string, or null. Stored as SQL Time.

Example

curl http://localhost:3001/api/trips/15 \
  -H "Authorization: Bearer <token>"

{
  "id": 15,
  "user_id": 42,
  "author": { "firstname": "Ada", "lastname": "Lovelace" },
  "title": "Accessible Weekend in Lisbon",
  "description": "A curated 3-day itinerary covering wheelchair-friendly spots in central Lisbon.",
  "is_public": true,
  "cover_image": "/api/trips/cover/lisbon_cover_1712345678.jpg",
  "original_trip_id": null,
  "fork_count": 2,
  "total_days": 1,
  "created_at": "2024-04-10T09:00:00Z",
  "updated_at": "2024-04-11T12:30:00Z",
  "days": [
    {
      "id": 8,
      "trip_id": 15,
      "day_number": 1,
      "date": "2024-06-01",
      "title": "Belém & Waterfront",
      "notes": "All locations are step-free.",
      "places": [
        {
          "id": 101,
          "trip_day_id": 8,
          "favorite_id": 7,
          "place_name": "MAAT – Museum of Art, Architecture and Technology",
          "latitude": 38.6969,
          "longitude": -9.2244,
          "osm_id": "way/987654321",
          "sub_type": "cultura_turismo",
          "order": 1,
          "notes": "Ramp entrance on the riverside side.",
          "visit_time": "10:00",
          "visit_time_end": "12:30"
        }
      ]
    }
  ]
}

PUT /api/trips/:trip_id

Updates metadata for an existing trip. Only the trip owner can perform updates. Authentication: Required

Request

title

string

New trip title.

description

string

Updated description.

is_public

boolean

Change the trip’s visibility. Setting to true publishes it to the community feed.

Response

Returns a wrapper with the full updated trip object.

msg

string

Confirmation message.

trip

object

The full updated trip object.

Example

curl -X PUT http://localhost:3001/api/trips/15 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"is_public": false}'

{
  "msg": "Viaje actualizado",
  "trip": {
    "id": 15,
    "title": "Accessible Weekend in Lisbon",
    "is_public": false,
    "updated_at": "2024-04-12T08:00:00Z"
  }
}

DELETE /api/trips/:trip_id

Permanently deletes a trip and all its days and places. Only the trip owner can delete. Authentication: Required

Deleting a trip is irreversible and cascades to all associated days and places.

Example

curl -X DELETE http://localhost:3001/api/trips/15 \
  -H "Authorization: Bearer <token>"

{
  "msg": "Viaje eliminado"
}

Cover Images

PUT /api/trips/:trip_id/cover

Uploads a cover image for a trip. Send as multipart/form-data with field file. Accepted formats: png, jpg, jpeg, webp. Authentication: Required

Request

file

required

Image file for the trip cover. Accepted formats: png, jpg, jpeg, webp. Sent as multipart/form-data.

Response

Returns a wrapper with the full updated trip object.

msg

string

Confirmation message.

trip

object

The full updated trip object with the new cover_image path.

Example

curl -X PUT http://localhost:3001/api/trips/15/cover \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/lisbon.jpg"

{
  "msg": "Imagen actualizada",
  "trip": {
    "id": 15,
    "cover_image": "/api/trips/cover/trip_15_1712345678.jpg"
  }
}

DELETE /api/trips/:trip_id/cover

Removes the cover image from a trip, resetting cover_image to null. Authentication: Required

Example

curl -X DELETE http://localhost:3001/api/trips/15/cover \
  -H "Authorization: Bearer <token>"

{
  "msg": "Imagen eliminada",
  "trip": {
    "id": 15,
    "cover_image": null
  }
}

GET /api/trips/cover/:filename

Serves a trip cover image file by its stored filename. No authentication required — suitable for use in public <img> tags in the WayFy frontend. Authentication: None

Example

curl http://localhost:3001/api/trips/cover/trip_15_1712345678.jpg \
  --output cover.jpg

Forking

POST /api/trips/:trip_id/fork

Creates a full copy of a public trip into the authenticated user’s account, setting original_trip_id to the source trip’s ID. Days and places are duplicated; the fork starts as a private trip. Cover images are also copied if present. Authentication: Required

Forks allow WayFy users to personalise community itineraries without altering the original. The original_trip_id field lets the UI show attribution to the source trip.

Response

Returns 201 Created with a wrapper containing the new forked trip object including all days and places.

msg

string

Confirmation message.

trip

object

The full new forked trip object including days and their places.

Example

curl -X POST http://localhost:3001/api/trips/15/fork \
  -H "Authorization: Bearer <token>"

{
  "msg": "Viaje copiado correctamente",
  "trip": {
    "id": 23,
    "user_id": 88,
    "author": { "firstname": "Kwame", "lastname": "Asante" },
    "title": "Accessible Weekend in Lisbon",
    "description": "A curated 3-day itinerary covering wheelchair-friendly spots in central Lisbon.",
    "is_public": false,
    "cover_image": "/api/trips/cover/trip_23_1712345999.jpg",
    "original_trip_id": 15,
    "fork_count": 0,
    "total_days": 1,
    "created_at": "2024-04-15T10:00:00Z",
    "updated_at": "2024-04-15T10:00:00Z",
    "days": []
  }
}

Trip Days

POST /api/trips/:trip_id/days

Adds a new day to an existing trip. day_number is optional — if omitted, it is automatically set to len(existing_days) + 1. Authentication: Required

Request

day_number

integer

The day’s position in the itinerary sequence (e.g. 1 for Day 1). Auto-assigned if omitted.

date

string

ISO 8601 date for this day (e.g. "2024-06-01"). Optional if the trip has no fixed dates.

title

string

A descriptive title for the day (e.g. "Belém & Waterfront").

notes

string

Free-form notes visible on the day’s itinerary card.

Response

Returns 201 Created with a wrapper containing the new TripDay object.

msg

string

Confirmation message.

day

object

Show TripDay object

integer

Day ID.

trip_id

integer

Parent trip ID.

day_number

integer

Day sequence number.

date

string

ISO 8601 date string or null.

title

string

Day title.

notes

string

Day notes.

Example

curl -X POST http://localhost:3001/api/trips/15/days \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "day_number": 1,
    "date": "2024-06-01",
    "title": "Belém & Waterfront",
    "notes": "All locations are step-free."
  }'

{
  "msg": "Día añadido",
  "day": {
    "id": 8,
    "trip_id": 15,
    "day_number": 1,
    "date": "2024-06-01",
    "title": "Belém & Waterfront",
    "notes": "All locations are step-free."
  }
}

PUT /api/trips/:trip_id/days/:day_id

Updates fields on an existing trip day. Returns the updated day including its places. Authentication: Required

Request

day_number

integer

Updated sequence number.

date

string

Updated date string (ISO 8601), or null to clear the date.

title

string

Updated day title.

notes

string

Updated day notes.

Response

msg

string

Confirmation message.

day

object

The updated day object including its places array.

Example

curl -X PUT http://localhost:3001/api/trips/15/days/8 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Belém, Waterfront & Ajuda"}'

{
  "msg": "Día actualizado",
  "day": {
    "id": 8,
    "trip_id": 15,
    "day_number": 1,
    "date": "2024-06-01",
    "title": "Belém, Waterfront & Ajuda",
    "notes": "All locations are step-free.",
    "places": []
  }
}

DELETE /api/trips/:trip_id/days/:day_id

Removes a day and all of its places from the trip. Authentication: Required

Example

curl -X DELETE http://localhost:3001/api/trips/15/days/8 \
  -H "Authorization: Bearer <token>"

{
  "msg": "Día eliminado"
}

Day Places

POST /api/trips/:trip_id/days/:day_id/places

Adds a place to a specific day in the itinerary. place_name is required; all other fields are optional. Authentication: Required

Request

place_name

string

required

Name of the place to add.

latitude

number

Latitude coordinate of the place.

longitude

number

Longitude coordinate of the place.

osm_id

string

OpenStreetMap identifier (e.g. node/123456789).

sub_type

string

WayFy place category (e.g. gastronomia, cultura_turismo).

order

integer

Position of this place within the day’s itinerary. Auto-assigned to end of list if omitted.

notes

string

Accessibility or visit notes specific to this place.

visit_time

string

Planned visit start time in "HH:MM" format (e.g. "10:00"). Stored as SQL Time.

visit_time_end

string

Planned visit end time in "HH:MM" format (e.g. "12:30"). Stored as SQL Time.

favorite_id

integer

ID of a saved favorite to link this place to. Enables quick add from the favorites panel.

Response

Returns 201 Created with a wrapper containing the new place entry.

msg

string

Confirmation message.

place

object

Show TripDayPlace object

integer

Place entry ID.

trip_day_id

integer

Parent day ID.

favorite_id

integer

Linked favorite ID or null.

place_name

string

Place name.

latitude

number

Latitude.

longitude

number

Longitude.

osm_id

string

OSM identifier.

sub_type

string

WayFy place category.

order

integer

Position in the day.

notes

string

Place notes.

visit_time

string

"HH:MM" string or null.

visit_time_end

string

"HH:MM" string or null.

Example

curl -X POST http://localhost:3001/api/trips/15/days/8/places \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "place_name": "MAAT – Museum of Art, Architecture and Technology",
    "latitude": 38.6969,
    "longitude": -9.2244,
    "osm_id": "way/987654321",
    "sub_type": "cultura_turismo",
    "order": 1,
    "notes": "Ramp entrance on the riverside side.",
    "visit_time": "10:00",
    "visit_time_end": "12:30",
    "favorite_id": 7
  }'

{
  "msg": "Lugar añadido",
  "place": {
    "id": 101,
    "trip_day_id": 8,
    "favorite_id": 7,
    "place_name": "MAAT – Museum of Art, Architecture and Technology",
    "latitude": 38.6969,
    "longitude": -9.2244,
    "osm_id": "way/987654321",
    "sub_type": "cultura_turismo",
    "order": 1,
    "notes": "Ramp entrance on the riverside side.",
    "visit_time": "10:00",
    "visit_time_end": "12:30"
  }
}

PUT /api/trips/:trip_id/days/:day_id/places/:place_id

Updates an existing place entry within a trip day. Authentication: Required

Request

place_name

string

Updated place name.

order

integer

New position within the day’s itinerary.

notes

string

Updated notes.

visit_time

string

Updated visit start time in "HH:MM" format.

visit_time_end

string

Updated visit end time in "HH:MM" format.

trip_day_id

integer

Move the place to a different day by supplying the target day’s ID.

Response

msg

string

Confirmation message.

place

object

The updated place object.

Example

curl -X PUT http://localhost:3001/api/trips/15/days/8/places/101 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"order": 2, "visit_time": "11:00", "visit_time_end": "13:00"}'

{
  "msg": "Lugar actualizado",
  "place": {
    "id": 101,
    "trip_day_id": 8,
    "place_name": "MAAT – Museum of Art, Architecture and Technology",
    "order": 2,
    "visit_time": "11:00",
    "visit_time_end": "13:00"
  }
}

DELETE /api/trips/:trip_id/days/:day_id/places/:place_id

Removes a place entry from a trip day. Authentication: Required

Example

curl -X DELETE http://localhost:3001/api/trips/15/days/8/places/101 \
  -H "Authorization: Bearer <token>"

{
  "msg": "Lugar eliminado"
}

Overview

Endpoints

Documentation Index

​Trips

​POST /api/trips/

​Request

​Response

​Example

​GET /api/trips/

​Response

​Example

​GET /api/trips/public

​Response

​Example

​GET /api/trips/:trip_id

​Response

​Example

​PUT /api/trips/:trip_id

​Request

​Response

​Example

​DELETE /api/trips/:trip_id

​Example

​Cover Images

​PUT /api/trips/:trip_id/cover

​Request

​Response

​Example

​DELETE /api/trips/:trip_id/cover

​Example

​GET /api/trips/cover/:filename

​Example

​Forking

​POST /api/trips/:trip_id/fork

​Response

​Example

​Trip Days

​POST /api/trips/:trip_id/days

​Request

​Response

​Example

​PUT /api/trips/:trip_id/days/:day_id

​Request

​Response

​Example

​DELETE /api/trips/:trip_id/days/:day_id

​Example

​Day Places

​POST /api/trips/:trip_id/days/:day_id/places

​Request

​Response

​Example

​PUT /api/trips/:trip_id/days/:day_id/places/:place_id

​Request

​Response

​Example

​DELETE /api/trips/:trip_id/days/:day_id/places/:place_id

​Example

Build docs developers (and LLMs) love

Trips

POST /api/trips/

Request

Response

Example

GET /api/trips/

Response

Example

GET /api/trips/public

Response

Example

GET /api/trips/:trip_id

Response

Example

PUT /api/trips/:trip_id

Request

Response

Example

DELETE /api/trips/:trip_id

Example

Cover Images

PUT /api/trips/:trip_id/cover

Request

Response

Example

DELETE /api/trips/:trip_id/cover

Example

GET /api/trips/cover/:filename

Example

Forking

POST /api/trips/:trip_id/fork

Response

Example

Trip Days

POST /api/trips/:trip_id/days

Request

Response

Example

PUT /api/trips/:trip_id/days/:day_id

Request

Response

Example

DELETE /api/trips/:trip_id/days/:day_id

Example

Day Places

POST /api/trips/:trip_id/days/:day_id/places

Request

Response

Example

PUT /api/trips/:trip_id/days/:day_id/places/:place_id

Request

Response

Example

DELETE /api/trips/:trip_id/days/:day_id/places/:place_id

Example