API docs by Redocly

Excursions API (v2.0.1)

Download OpenAPI specification:

License: AGPL-3.0-or-later

A lightweight group travel planning app. Last updated April 6th, 16:40 2025.

User Management

Create, fetch, update and delete users.

Create User

Create and return a new User alongside a Bearer Token.

Request Body schema: application/json
required
userName
required
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

firstName
required
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

lastName
required
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

email
required
string <email> /[-A-Za-z0-9!#$%&'*+\/=?^_`{|}~]+(?:\.[-A-Za-...

An email address.

password
required
string <password> (Password) >= 8 characters /^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[...

A password.

Responses

Request samples

Content type
application/json
{
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "password": "Testing1234!"
}

Response samples

Content type
application/json
{
  • "_id": "67e35ab146687a50c9ec3ff9",
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "password": "Testing1234!",
  • "friends": [ ],
  • "outgoingFriendRequests": [ ],
  • "incomingFriendRequests": [ ],
  • "hostedExcursions": [ ],
  • "sharedExcursions": [ ],
  • "completedExcursions": [ ],
  • "outgoingExcursionInvites": [ ],
  • "incomingExcursionInvites": [ ],
  • "hostedTrips": [ ]
}

Get User

Return the currently authenticated User.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "_id": "67e35ab146687a50c9ec3ff9",
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "password": "Testing1234!",
  • "friends": [ ],
  • "outgoingFriendRequests": [ ],
  • "incomingFriendRequests": [ ],
  • "hostedExcursions": [ ],
  • "sharedExcursions": [ ],
  • "completedExcursions": [ ],
  • "outgoingExcursionInvites": [ ],
  • "incomingExcursionInvites": [ ],
  • "hostedTrips": [ ]
}

Update User

Modify an existing User and return the updated User data.

Authorizations:
BearerToken
Request Body schema: application/json
required
userName
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

firstName
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

lastName
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

email
string <email> (Email) /[-A-Za-z0-9!#$%&'*+\/=?^_`{|}~]+(?:\.[-A-Za-...

An email address.

password
string <password> (Password) >= 8 characters /^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[...

A password.

Responses

Request samples

Content type
application/json
{
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "_id": "67e35ab146687a50c9ec3ff9",
  • "password": "Testing1234!",
  • "friends": [ ],
  • "outgoingFriendRequests": [ ],
  • "incomingFriendRequests": [ ],
  • "hostedExcursions": [ ],
  • "sharedExcursions": [ ],
  • "completedExcursions": [ ],
  • "outgoingExcursionInvites": [ ],
  • "incomingExcursionInvites": [ ],
  • "hostedTrips": [ ]
}

Response samples

Content type
application/json
{
  • "_id": "67e35ab146687a50c9ec3ff9",
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "password": "Testing1234!",
  • "friends": [ ],
  • "outgoingFriendRequests": [ ],
  • "incomingFriendRequests": [ ],
  • "hostedExcursions": [ ],
  • "sharedExcursions": [ ],
  • "completedExcursions": [ ],
  • "outgoingExcursionInvites": [ ],
  • "incomingExcursionInvites": [ ],
  • "hostedTrips": [ ]
}

Delete User

Delete an existing User and return the deleted User data.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "_id": "67e35ab146687a50c9ec3ff9",
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "password": "Testing1234!",
  • "friends": [ ],
  • "outgoingFriendRequests": [ ],
  • "incomingFriendRequests": [ ],
  • "hostedExcursions": [ ],
  • "sharedExcursions": [ ],
  • "completedExcursions": [ ],
  • "outgoingExcursionInvites": [ ],
  • "incomingExcursionInvites": [ ],
  • "hostedTrips": [ ]
}

Get Users

Return a list of Users.

Authorizations:
BearerToken
query Parameters
limit
required
number >= 0

The number of Users to be returned.

start
number >= 0

The document index upon which the returned list of Users should begin.

keywords
Array of strings

Comma delimited list of terms to search on.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get User By ID

Return the User with the matching id.

Authorizations:
BearerToken
path Parameters
userId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID of the user to get.

Responses

Response samples

Content type
application/json
{
  • "_id": "67e35ab146687a50c9ec3ff9",
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "password": "Testing1234!",
  • "friends": [ ],
  • "outgoingFriendRequests": [ ],
  • "incomingFriendRequests": [ ],
  • "hostedExcursions": [ ],
  • "sharedExcursions": [ ],
  • "completedExcursions": [ ],
  • "outgoingExcursionInvites": [ ],
  • "incomingExcursionInvites": [ ],
  • "hostedTrips": [ ]
}

User Authentication

Manage the authentication status of a user.

Sign In

Verify User credentials and grant a Bearer Token.

Request Body schema: application/json
required
email
required
string <email> (Email) /[-A-Za-z0-9!#$%&'*+\/=?^_`{|}~]+(?:\.[-A-Za-...

An email address.

password
required
string <password> (Password) >= 8 characters /^(?=.*?[A-Z])(?=.*?[a-z])(?=.*?[0-9])(?=.*?[...

A password.

Responses

Request samples

Content type
application/json
{
  • "email": "joe@user.com",
  • "password": "Testing1234!"
}

Response samples

Content type
application/json
{
  • "_id": "67e35ab146687a50c9ec3ff9",
  • "userName": "joeuser",
  • "firstName": "Joe",
  • "lastName": "User",
  • "email": "joe@user.com",
  • "password": "Testing1234!",
  • "friends": [ ],
  • "outgoingFriendRequests": [ ],
  • "incomingFriendRequests": [ ],
  • "hostedExcursions": [ ],
  • "sharedExcursions": [ ],
  • "completedExcursions": [ ],
  • "outgoingExcursionInvites": [ ],
  • "incomingExcursionInvites": [ ],
  • "hostedTrips": [ ]
}

Sign Out

Revoke a Bearer Token for the currently authenticated User.

Authorizations:
BearerToken

Responses

Response samples

Content type
text/plain
200 OK

Park Details

Retrieve detailed data about national parks from the NPS API.

Get National Parks

Retrieve data about national parks (addresses, contacts, description, hours of operation, etc.).

Authorizations:
BearerToken
query Parameters
parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{
  • "total": "474",
  • "limit": "1",
  • "start": "0",
  • "data": [
    ]
}

Get National Park Summaries

Retrieve curated data about national parks (id, fullName, description, parkCode, etc.).

Authorizations:
BearerToken
query Parameters
parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{
  • "total": "474",
  • "limit": "1",
  • "start": "0",
  • "data": [
    ]
}

Get National Park Codes

Retrieve an alphabetically sorted list of all parkCodes and stateCodes.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "parks": {
    },
  • "states": {
    }
}

Get Campgrounds

Retrieve data about National Park Service campgrounds including addresses, contacts, description, hours of operation, etc.

Authorizations:
BearerToken
query Parameters
parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{
  • "total": "661",
  • "limit": "1",
  • "start": "0",
  • "data": [
    ]
}

Get Things To Do

Retrieve suggested things to do recommended by and for specific national parks.

Authorizations:
BearerToken
query Parameters
id
string <BSON> (ID) [0-9a-f]
Example: id=67d75fdeb5e9f677795522ec

A comma delimited list of things to do IDs.

parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{
  • "total": "3468",
  • "limit": "1",
  • "start": "0",
  • "data": [
    ]
}

Multimedia

Access media data about national parks from the NPS API.

Get Audio

Retrieve metadata relating to audio files created by national parks.

query Parameters
parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{}

Get Galleries

Retrieve galleries created by national parks and other NPS entities.

query Parameters
parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{
  • "total": "9765",
  • "limit": "1",
  • "start": "0",
  • "data": [
    ]
}

Get Gallery Assets

Retrieve gallery assets by unique asset id, or gallery id, etc.

query Parameters
id
any

The unique identifier of an asset within a gallery.

galleryId
any

The unique identifier for a gallery.

parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number. Default is 0.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{}

Get Videos

Retrieve metadata relating to videos created by national parks.

query Parameters
parkCode
string

A comma delimited list of park codes (each 4-10 characters in length).

stateCode
string

A comma delimited list of 2 character state codes.

limit
required
number <int32>

Number of results to return per request.

start
number <int32>

Get the next [limit] results starting with this number.

q
string

Term to search on.

Responses

Response samples

Content type
application/json
{}

Excursions

Create a collection of trips that you can share with friends.

Create Excursion

Create a new Excursion. Returns the newly created Excursion object.

Authorizations:
BearerToken
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

description
required
string

A short description about this Excursion.

trips
Array of strings <BSON> (ID) [ items <BSON >[0-9a-f] ]

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Name",
  • "description": "string",
  • "trips": [
    ]
}

Response samples

Content type
application/json
{
  • "excursion": [
    ]
}

Get Excursions By User

Retrieve all Excursions related to the currently authenticated User.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "excursions": [
    ]
}

Get Excursion By Id

Return a new excursion object with a matching id.

Authorizations:
BearerToken
path Parameters
excursionId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
application/json
{
  • "excursion": {
    }
}

Update Excursion By Id

Update an excursion object with a matching id.

Authorizations:
BearerToken
path Parameters
excursionId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Request Body schema: application/json
required
name
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

description
string

A short description about this Excursion.

trips
Array of strings <BSON> (ID) [ items <BSON >[0-9a-f] ]
isComplete
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Name",
  • "description": "string",
  • "trips": [
    ],
  • "isComplete": false
}

Response samples

Content type
application/json
{
  • "excursion": {
    }
}

Delete Excursion By Id

Delete an excursion object with a matching id.

Authorizations:
BearerToken
path Parameters
excursionId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
text/plain
200 OK

Trips

Plan a trip to a national park. Pick a campground, things to do, and dates.

Create Trip

Create a new Trip and add it to the Users hostedTrips array.

Authorizations:
BearerToken
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

description
required
string

A short description about this Trip.

startDate
required
string <date-time>

ISO8601 format.

endDate
required
string <date-time>

ISO8601 format.

park
string <BSON> (ID) [0-9a-f]

The ID (BSON) of this object.

campground
string <BSON> (ID) [0-9a-f]

The ID (BSON) of this object.

thingstodo
Array of strings <BSON> (ID) [ items <BSON >[0-9a-f] ]

Array of thingstodo ids.

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Name",
  • "description": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "park": "67d75fdeb5e9f677795522ec",
  • "campground": "67d75fdeb5e9f677795522ec",
  • "thingstodo": [
    ]
}

Response samples

Content type
application/json
{
  • "trip": {
    }
}

Get Trips by User

Returns an array of Trips with a matching Excursion Id.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "trips": [
    ]
}

Get Trip by Id

Return a trip object.

Authorizations:
BearerToken
path Parameters
tripId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
application/json
{
  • "trip": {
    }
}

Update Trip By Id

Return an updated Trip object.

Authorizations:
BearerToken
path Parameters
tripId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Request Body schema: application/json
required
name
string (Name) [ 1 .. 128 ] characters

The name of an object, field, property, etc.

description
string

A short description about this Trip.

startDate
string <date-time>

ISO8601 format.

endDate
string <date-time>

ISO8601 format.

park
string <BSON> (ID) [0-9a-f]

The ID (BSON) of this object.

campground
string <BSON> (ID) [0-9a-f]

The ID (BSON) of this object.

thingstodo
Array of strings <BSON> (ID) [ items <BSON >[0-9a-f] ]

Array of thingstodo ids.

Responses

Request samples

Content type
application/json
{
  • "name": "Sample Name",
  • "description": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "park": "67d75fdeb5e9f677795522ec",
  • "campground": "67d75fdeb5e9f677795522ec",
  • "thingstodo": [
    ]
}

Response samples

Content type
application/json
{
  • "trip": {
    }
}

Delete Trip By Id

Return the deleted Trip object.

Authorizations:
BearerToken
path Parameters
tripId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
text/plain
200 OK

Friends

Add other users to share excursions.

Get Friends

Get a User's friends list.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "friends": [
    ]
}

Delete Friend

Remove a friend from the currently authenticated User's friends list.

Authorizations:
BearerToken
path Parameters
friendId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
text/plain
200 OK

Friend Requests

The medium used to add users to friends lists.

Create Friend Request

Create and send a friend request to a particular user. Multiple friend requests cannot be sent to the same user.

Authorizations:
BearerToken
Request Body schema: application/json
required
friendId
required
string <BSON> (ID) [0-9a-f]

The ID (BSON) of this object.

Responses

Request samples

Content type
application/json
{
  • "friendId": "67d75fdeb5e9f677795522ec"
}

Response samples

Content type
application/json
{
  • "friendRequest": {
    }
}

Get Friend Requests

Retrieve a list of all friend requests (incoming/outgoing) for the currently authenticated User.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "friendRequests": [
    ]
}

Handle Friend Request

Manage an incoming friend request for the currently authenticated User.

Authorizations:
BearerToken
path Parameters
requestId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Request Body schema: application/json
required
isAccepted
required
boolean

Responses

Request samples

Content type
application/json
{
  • "isAccepted": true
}

Response samples

Content type
application/json
{
  • "friendRequest": {
    }
}

Delete Friend Request

Delete an outgoing pending friend request.

Authorizations:
BearerToken
path Parameters
requestId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
text/plain
200 OK

Sharing Excursions

Share your excursions with friends.

Create Excursion Invite

Create and send an excursion invitation to a user.

Authorizations:
BearerToken
path Parameters
excursionId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Request Body schema: application/json
required
friendId
required
string <BSON> (ID) [0-9a-f]

The ID of the friend being invited to this Excursion.

Responses

Request samples

Content type
application/json
{
  • "friendId": "67d75fdeb5e9f677795522ec"
}

Response samples

Content type
application/json
{
  • "_id": "67d75fdeb5e9f677795522ec",
  • "sender": {
    },
  • "receiver": {
    },
  • "isAccepted": false,
  • "excursion": {
    }
}

Get Excursion Invites

Retrieve all Excursion invites (incoming/outgoing) for the currently authenticated User.

Authorizations:
BearerToken

Responses

Response samples

Content type
application/json
{
  • "excursionInvites": {
    }
}

Handle Excursion Invite

Accept or decline an Excursion invite.

Authorizations:
BearerToken
Request Body schema: application/json
required
isAccepted
required
boolean

Responses

Request samples

Content type
application/json
{
  • "isAccepted": true
}

Response samples

Content type
text/plain
200 OK

Delete Excursion Invite

Rescind an Excursion invite for a given User.

Authorizations:
BearerToken
path Parameters
excursionId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
text/plain
200 OK

Remove User By Excursion Id

The excursion host may remove a participant via this endpoint.

Authorizations:
BearerToken
path Parameters
excursionId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Request Body schema: application/json
optional
participantId
any

Responses

Request samples

Content type
application/json
{
  • "participantId": null
}

Response samples

Content type
text/plain
200 OK

Leave Excursion By Id

A participant of an excursion may leave via this endpoint.

Authorizations:
BearerToken
path Parameters
excursionId
required
string <BSON> (ID) [0-9a-f]
Example: 67d75fdeb5e9f677795522ec

The ID (BSON) of this object.

Responses

Response samples

Content type
text/plain
200 OK