Getting Started

Welcome to the One Request API, connecting the realms of Middle-earth through a single unified interface. Our API provides programmatic access to locations, activities, groups, and more, allowing developers to create custom journey planning applications.

Note: The One Request system is currently available only through our API. Our master craftsmen are forging a user interface worthy of display in the halls of kings, but until its completion, all interactions must occur through this API.

Base URL

All API requests should be directed to:

https://one-request.malteksolutions.com/v1

Request Format

The API accepts JSON for request bodies and returns JSON responses. All requests must include the appropriate Content-Type header:

Content-Type: application/json

Authentication

One Request requires authentication for all API endpoints. We use JWT (JSON Web Tokens) for secure authentication.

Obtaining Tokens

To obtain an access token, make a POST request to the authentication endpoint:

POST /auth/token

Authenticates a user and returns access and refresh tokens.

Request Body:

  • email - User's registered email
  • password - User's password
{ "email": "user@example.com", "password": "secure_password" }

Response:

{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "bearer", "expires_in": 3600 }

Using Authentication

Include the access token in the Authorization header for all authenticated requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Refresh

When an access token expires, use the refresh token to obtain a new one:

POST /auth/refresh

Request Body:

  • refresh_token - Valid refresh token
{ "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }

Locations

The Locations API provides access to our extensive catalog of vetted destinations across Middle-earth.

GET /locations

Returns a paginated list of all available locations.

Query Parameters:

  • page - Page number (default: 1)
  • size - Results per page (default: 20)
  • sort - Sort field (name, id)
  • order - Sort order (asc, desc)

Response:

{ "items": [ { "id": "b8f7c5e2-3a1d-4b6f-9c8d-7e5f4a3b2c1d", "name": "Rivendell", "description": "The Last Homely House East of the Sea, nestled in a hidden valley", "lat": "54.2361", "long": "-7.8921", "reviews": [ { "id": "d3c2b1a9-8f7e-6d5c-4b3a-2c1d0f9e8d7", "rating": 5, "review": "The halls echo with ancient wisdom and song. A sanctuary for weary travelers." } ] }, ... ], "total": 42, "page": 1, "size": 20, "pages": 3 }
GET /locations/{id}

Returns detailed information about a specific location.

Path Parameters:

  • id - Location unique identifier

Activities

The Activities API allows discovery and booking of experiences across Middle-earth.

GET /activities

Returns a paginated list of available activities.

Query Parameters:

  • location_id - Filter by location
  • day - Filter by date (YYYY-MM-DD)
  • price_min - Minimum price
  • price_max - Maximum price
  • currency - Currency (GOLD, SILV, MITH)
POST /activities

Creates a new activity.

Request Body:

  • name - Activity name
  • description - Detailed description
  • price - Activity cost
  • currency - Currency code (GOLD, SILV, MITH)
  • day - Date of activity (YYYY-MM-DD)
  • invite_code - Private activity access code
  • group_id - Associated group ID
{ "name": "Starlight Feast", "description": "An evening of feasting and song beneath the stars of Elendil", "price": 450, "currency": "SILV", "day": "3019-04-15", "invite_code": "mellon", "group_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6" }

Groups

The Groups API enables fellowship management, allowing coordination between travelers.

GET /groups

Returns groups the authenticated user belongs to.

POST /groups

Creates a new group with the authenticated user as owner.

Request Body:

  • name - Group name
  • description - Group description
GET /groups/{id}/chats

Returns chat messages for a specific group.

Path Parameters:

  • id - Group unique identifier

Postman Collection

To simplify your development process, we provide a complete Postman collection containing all endpoints, example requests, and authentication workflows.

Download Postman Collection

Using the Collection

  1. Download the collection JSON file
  2. Import into Postman using File → Import
  3. Set up an environment with your API credentials
  4. Run the authentication request to populate your tokens
Important: Our collection uses environment variables for authentication tokens and base URL. Be sure to configure your Postman environment accordingly.

OpenAPI Specification

One Request follows OpenAPI 3.0 specifications. The complete schema is available for download and can be used with tools like Swagger UI, ReDoc, or any OpenAPI-compatible code generator.

Download OpenAPI Spec Browse Interactive Docs

Our interactive documentation provides a convenient way to explore the API without leaving your browser. For the most comprehensive view, we recommend using the interactive docs.