Airbnb-Style Rental Marketplace Backend - Frontend Development Prompts

AI-assisted frontend development prompts for Airbnb-Style Rental Marketplace Backend

This document contains all frontend development prompts that can be used to build the user interface for this project. Each prompt provides detailed specifications for implementing specific frontend features.

Introduction
Project Introduction & Setup
Authentication Management
Verification Management
Profile Management
User Management
MCP BFF Integration
Messaging Service
PropertyCatalog Service
BookingManagement Service
BookingManagement Service Reservation Payment Flow
ReviewSystem Service
PlatformAdmin Service
AgentHub Service

Introduction

Project Overview

Airbnb-Style Rental Marketplace Backend

Version : 1.0.108

airbnb is a global platform enabling hosts to list properties and guests to book short-term stays with secure payments, messaging, and review systems. It connects hosts and guests through a robust travel/hospitality marketplace, handling authentication, bookings, payments, and moderation. The backend supports global operations with multi-language and multi-currency features…

How to Use Project Documents

The Airbnb project has been designed and generated using Mindbricks, a powerful microservice-based backend generation platform. All documentation is automatically produced by the Mindbricks Genesis Engine, based on the high-level architectural patterns defined by the user or inferred by AI.

This documentation set is intended for both AI agents and human developers—including frontend and backend engineers—who need precise and structured information about how to interact with the backend services of this project. Each document reflects the live architecture of the system, providing a reliable reference for API consumption, data models, authentication flows, and business logic.

By following this documentation, developers can seamlessly integrate with the backend, while AI agents can use it to reason about the service structure, make accurate decisions, or even generate compatible client-side code.

Accessing Project Services

Each service generated by Mindbricks is exposed via a dedicated REST API endpoint. Every service documentation set includes the base URL of that service along with the specific API paths for each available route.

Before consuming any API, developers or agents must understand the service URL structure and environment-specific endpoints.

Service Endpoint Structure

Environment	URL Pattern Example
Preview	`https://airbnb3.prw.mindbricks.com/auth-api`
Staging	`https://airbnb3-stage.mindbricks.co/auth-api`
Production	`https://airbnb3.mindbricks.co/auth-api`

Replace auth with the actual service name as lower case (e.g., order-api, bff-service, customermanagement-api etc.).

Environment Usage Notes

Preview APIs become accessible after a project is previewed inside the Mindbricks platform. These are ideal for development and testing.
Staging and Production APIs are only accessible after the project is deployed to cloud environments provisioned via Mindbricks.
In some cases, the project owner may choose to deploy services on their own infrastructure. In such scenarios, the service base URLs will be custom and should be communicated manually by the project owner to developers or AI agents.

Frontend applications should be designed to easily switch between environments, allowing dynamic endpoint targeting for Preview, Staging, and Production.

Getting Started: Use the Auth Service First

Before interacting with other services in the Airbnb project, AI agents and developers should begin by integrating with the Auth Service.

Mindbricks automatically generates a dedicated authentication microservice based on the project’s authentication definitions provided by the architect. This service provides the essential user and access management foundation for the project.

Agents should first utilize the Auth Service to:

Register and authenticate users (login)
Manage users, roles, and permissions
Handle user groups (if defined)
Support multi-tenancy logic (if configured)
Perform Policy-Based Access Control (PBAC), if activated by the architect

Auth Service Documentation

Use the following resources to understand and integrate the Auth Service:

REST API Guide – ideal for frontend and direct HTTP usage
Auth REST API Guide
Event Guide – helpful for event-driven or cross-service integrations
Auth Event Guide
Service Design Document – overall structure, patterns, and logic
Auth Service Design

Note: For most frontend use cases, the REST API Guide will be the primary source. The Event Guide and Service Design documents are especially useful when integrating with other backend microservices or building systems that interact with the auth service indirectly.

Using the BFF (Backend-for-Frontend) Service

In Mindbricks, all backend services are designed with an advanced CQRS (Command Query Responsibility Segregation) architecture. Within this architecture, business services are responsible for managing their respective domains and ensuring the accuracy and freshness of domain data.

The BFF service complements these business services by providing a read-only aggregation and query layer tailored specifically for frontend and client-side applications.

Key Principles of the BFF Service

Elasticsearch Replicas for Fast Queries:
Each data object managed by a business service is automatically replicated as an Elasticsearch index, making it accessible for fast, frontend-oriented queries through the BFF.
Cross-Service Data Aggregation:
The BFF offers an aggregation layer capable of combining data across multiple services, enabling complex filters, searches, and unified views of related data.
Read-Only by Design:
The BFF service is strictly read-only. All create, update, or delete operations must be performed through the relevant business services, or via event-driven sagas if designed.

BFF Service Documentation

REST API Guide – querying aggregated and indexed data
BFF REST API Guide
Event Guide – syncing strategies across replicas
BFF Event Guide
Service Design – aggregation patterns and index structures
BFF Service Design

Tip: Use the BFF service as the main entry point for all frontend data queries. It simplifies access, reduces round-trips, and ensures that data is shaped appropriately for the UI layer.

Business Services Overview

The Airbnb-Style Rental Marketplace Backend project consists of multiple business services, each responsible for managing a specific domain within the system. These services expose their own REST APIs and documentation sets, and are accessible based on the environment (Preview, Staging, Production).

Usage Guidance

Business services are primarily designed to:

Handle the state and operations of domain data
Offer Create, Update, Delete operations over owned entities
Serve direct data queries (get, list) for their own objects when needed

Base URL Examples:

Environment	URL
Preview	`https://airbnb3.prw.mindbricks.com/agenthub-api`
Staging	`https://airbnb3-stage.mindbricks.co/agenthub-api`
Production	`https://airbnb3.mindbricks.co/agenthub-api`

Connect via MCP (Model Context Protocol)

All backend services in the Airbnb project expose their Business APIs as MCP tools. These tools are aggregated by the MCP-BFF service into a single unified endpoint that external AI tools can connect to.

Unified MCP Endpoint

Environment	StreamableHTTP (recommended)	SSE (legacy fallback)
Preview	`https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp`	`https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp/sse`
Staging	`https://airbnb3-stage.mindbricks.co/mcpbff-api/mcp`	`https://airbnb3-stage.mindbricks.co/mcpbff-api/mcp/sse`
Production	`https://airbnb3.mindbricks.co/mcpbff-api/mcp`	`https://airbnb3.mindbricks.co/mcpbff-api/mcp/sse`

Authentication

MCP connections require authentication via the Authorization header:

API Key (recommended for AI agents): Authorization: Bearer sk_mbx_your_api_key_here API keys are long-lived and don’t expire like JWT tokens. Create one from the profile page.
JWT Token: Authorization: Bearer {accessToken} Use a valid access token obtained from the login API.

OAuth is not supported for MCP connections at this time.

Connecting from Cursor

Add the following to your project’s .cursor/mcp.json:

{
  "mcpServers": {
    "airbnb3": {
      "url": "https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mbx_your_api_key_here"
      }
    }
  }
}

Connecting from Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "airbnb3": {
      "url": "https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mbx_your_api_key_here"
      }
    }
  }
}

What’s Available

Once connected, the AI tool can discover and call all Business API tools from all services — CRUD operations, custom queries, file operations, and more. The MCP-BFF handles routing each tool call to the correct backend service and propagates your authentication context.

Conclusion

This documentation set provides a comprehensive guide for understanding and consuming the Airbnb-Style Rental Marketplace Backend backend, generated by the Mindbricks platform. It is structured to support both AI agents and human developers in navigating authentication, data access, service responsibilities, and system architecture.

To summarize:

Start with the Auth Service to manage users, roles, sessions, and permissions.
Use the BFF Service for optimized, read-only data queries and cross-service aggregation.
Refer to the Business Services when you need to manage domain-specific data or perform direct CRUD operations.

Each service offers a complete set of documentation—REST API guides, event interface definitions, and design insights—to help you integrate efficiently and confidently.

Whether you are building a frontend application, configuring an automation agent, or simply exploring the architecture, this documentation is your primary reference for working with the backend of this project.

For environment-specific access, ensure you’re using the correct base URLs (Preview, Staging, Production), and coordinate with the project owner for any custom deployments.

How to Use These Prompts

These prompts are designed to be used with AI coding assistants to help build frontend features. Each prompt includes:

Feature Description - What the feature does and its purpose
Data Models - The backend data structures to work with
API Endpoints - Available REST APIs for the feature
UI Requirements - Specific user interface requirements
Implementation Guidelines - Best practices and patterns to follow

When using these prompts with an AI assistant:

Copy the relevant prompt section
Provide context about your frontend framework (React, Vue, Angular, etc.)
Reference the REST API documentation for endpoint details

Frontend Development Prompts

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 1 - Project Introduction & Setup

This is the introductory document for the airbnb frontend project. It is designed for AI agents that will generate frontend code to consume the project’s backend. Read it carefully — it describes the project scope, architecture, API conventions, and initial screens you must build before proceeding to the feature-specific prompts that follow.

This prompt will help you set up the project infrastructure, create the initial layout, home page, navigation, and any dummy screens. The subsequent prompts will provide detailed API documentation for each feature area.

Project Introduction

Project Services Overview

The project has 1 auth service, 1 notification service, 1 BFF service, and 6 business services, plus other helper services such as bucket and realtime.

Each service is a separate microservice application and listens for HTTP requests at different service URLs.

#	Service	Description	API Prefix
1	auth	Authentication and user management	`/auth-api`
2	messaging	Enables secure in-app messaging between guests and hosts. Handles threads, messages (with text/media/system types), abuse flagging, and admin moderation for resolution…	`/messaging-api`
3	propertyCatalog	Service for management of property listings, calendars, amenities, and localization for a short-term rental marketplace. Hosts can manage listings, availability, multi-language descriptions, policies, pricing, and attributes, served for global search and discovery…	`/propertyCatalog-api`
4	bookingManagement	Orchestrates booking, payment, calendar, changewsand dispute flows for Airbnb-style short-term rental marketplace…test Handles reservations, approval, Stripe payments, iCal sync, payment records, and the dispute/refund lifecycle with host/guest/admin visibility.	`/bookingManagement-api`
5	reviewSystem	Handles double-blind, moderated reviews and rating aggregation for stays. Allows guests/hosts to review each other and listings, supports moderation, and exposes aggregate stats for listings/profiles…	`/reviewSystem-api`
6	platformAdmin	Administrative and compliance management backend for moderation, audit, dispute, financial oversight, localization, and GDPR in the Airbnb-style rental platform.	`/platformAdmin-api`
7	agentHub	AI Agent Hub	`/agentHub-api`

Detailed API documentation for each service will be given in the following prompts. In this document, you will build the initial project structure, home pages, and navigation.

API Structure

Object Structure of a Successful Response

When the service processes requests successfully, it wraps the requested resource(s) within a JSON envelope. This envelope includes the data and essential metadata such as configuration details and pagination information, providing context to the client.

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

If a request encounters an issue—whether due to a logical fault or a technical problem—the service responds with a standardized JSON error structure. The HTTP status code indicates the nature of the error, using commonly recognized codes for clarity:

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Accessing the Backend

Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the home page includes a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services.

The base URL of the application in each environment is as follows:

Preview: https://airbnb3.prw.mindbricks.com
Staging: https://airbnb3-stage.mindbricks.co
Production: https://airbnb3.mindbricks.co

For the auth service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/auth-api
Staging: https://airbnb3-stage.mindbricks.co/auth-api
Production: https://airbnb3.mindbricks.co/auth-api

For each other service, append /{serviceName}-api to the environment base URL.

Any request that requires login must include a valid token in the Bearer authorization header.

Please note that for each service in the project (which will be introduced in following prompts) will use a different address so it is a good practice to define a separate client for each service in the frontend application lib source. Not only the different base urls, some services even may need different access rules when shaping the request.

Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page.

Home Page

First build a home page which shows some static content about the application, and has got login and registration (if is public) buttons. The home page should be updated later according to the content that each service provides, as a frontend developer use best and common practices to reflect the service content to the home page. User may also give extra information for the home page content in addition to this prompt.

Note that this page should include a deployment (environment) selection option to set the base URL. Set the default to production.

After user logs in, page header should show the current login state as in modern web pages, logged in user fullname, avatar, email and with a logout link, make a fancy current user component. The home page may have different views before and after login.

Initial Navigation Structure

Build the initial navigation/sidebar with placeholder pages for each area of the application. These will be implemented in detail by the subsequent prompts:

Home / Landing
Login
Register
Verification
Profile
User Management (admin)
Messaging Service Pages
PropertyCatalog Service Pages
BookingManagement Service Pages
ReviewSystem Service Pages
PlatformAdmin Service Pages
AgentHub Service Pages

Create these as placeholder/dummy pages with a title and “Coming soon” note. They will be filled in by the following prompts.

What To Build Now

With this prompt, build:

Project infrastructure — routing, layout, environment config, API client setup (one client per service)
Home page with environment selector, login/register buttons, project description
Placeholder pages for all navigation items listed above
Common components — header with user info, navigation sidebar/menu, layout wrapper

Do not implement authentication flows, registration, or any service-specific features yet — those will be covered in the next prompts.

Common Reminders

When the application starts, please ensure that the baseUrl is set to the production server URL, and that the environment selector dropdown has the Production option selected by default.
Note that any API call to the application backend is based on a service base URL. Auth APIs use /auth-api prefix, and each business service uses /{serviceName}-api prefix after the application’s base URL.
The deployment environment selector will only be used in the home page. If any page is called directly bypassing the home page, the page will use the stored or default environment.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 2 - Authentication Management

This document covers the authentication features of the airbnb project: registration, login, logout, and session management. The project introduction, API conventions, base URLs, home page, and multi-tenancy setup were covered in the previous introductory prompt — make sure those are implemented before proceeding.

All auth APIs use the auth service base URL with the /auth-api prefix (e.g., https://airbnb3.mindbricks.co/auth-api).

FRONTEND_URL

The FRONTEND_URL environment variable is automatically set on the auth service from the project’s frontendUrl setting in Basic Project Settings. It contains the base URL of the frontend application for the current deployment environment (e.g., http://localhost:5173 for dev, https://myapp.com for production). Defaults if not configured:

Environment	Default
dev	`http://localhost:5173`
test	`https://airbnb3.prw.mindbricks.com`
stage	`https://airbnb3-stage.mindbricks.co`
prod	`https://airbnb3.mindbricks.co`

This variable is used by the auth service for:

Social login redirects — after OAuth processing, the auth service redirects to FRONTEND_URL + /auth/callback (the frontend must have a page at this route; see the Social Login prompt for details)
Email notification links — verification, password reset, and other links in emails point back to the frontend

You can customize FRONTEND_URL per environment by configuring the frontendUrl field in your project’s Basic Project Settings (e.g., when using a custom domain).

Registration Management

User Registration

User registration is public in the application. Please create a simple and polished registration page that includes only the necessary fields of the registration API.

Using the registeruser route of the auth API, send the required fields from your registration page.

The registerUser API in the auth service is described with the request and response structure below.

Note that since the registerUser API is a business API, it is versioned; call it with the given version like /v1/registeruser.

`Register User` API

This api is used by public users to register themselves

Rest Route

The registerUser API REST controller can be triggered via the following route:

/v1/registeruser

Rest Request Parameters

The registerUser api has got 6 regular request parameters

Parameter	Type	Required	Population
avatar	String	false	request.body?.[“avatar”]
password	String	true	request.body?.[“password”]
fullname	String	true	request.body?.[“fullname”]
email	String	true	request.body?.[“email”]
preferredLanguage	String	false	request.body?.[“preferredLanguage”]
bio	Text	false	request.body?.[“bio”]
avatar : The avatar url of the user. If not sent, a default random one will be generated.
password : The password defined by the the user that is being registered.
fullname : The fullname defined by the the user that is being registered.
email : The email defined by the the user that is being registered.
preferredLanguage : User’s preferred language for the application interface
bio : User’s biography or profile description

REST Request To access the api you can use the REST controller with the path POST /v1/registeruser

  axios({
    method: 'POST',
    url: '/v1/registeruser',
    data: {
            avatar:"String",  
            password:"String",  
            fullname:"String",  
            email:"String",  
            preferredLanguage:"String",  
            bio:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

After a successful registration, the frontend code should handle any verification requirements. Verification Management will be given in the next prompt.

The registration response will include a user object in the root envelope; this object contains user information with an id field.

Login Management

Login Identifier Model

The primary login identifier for this application is the email address. Users register and log in using their email and password. No mobile field is stored in the user data model. The login page should include an email input and a password input.

Login Flow

After successful registration and completing any required verifications, the user can log in. Please create a minimal, polished login page as described above. Note that this page should respect the deployment (environment) selection option made in the home page to set the base URL. If the user reaches this page directly skipping home page, the default production deployment will be used.

The login API returns a created session. This session can be retrieved later with the access token using the /currentuser system route.

Any request that requires login must include a valid token. When a user logs in successfully, the response JSON includes a JWT access token in the accessToken field. Under normal conditions, this token is also set as a cookie and consumed automatically. However, since AI coding agents’ preview options may fail to use cookies, ensure that each request includes the access token in the Bearer authorization header.

If the login fails due to verification requirements, the response JSON includes an errCode. If it is EmailVerificationNeeded, start the email verification flow; if it is MobileVerificationNeeded, start the mobile verification flow.

After a successful login, you can access session (user) information at any time with the /currentuser API. On inner pages, show brief profile information (avatar, name, etc.) using the session information from this API.

Note that the currentuser API returns a session object, so there is no id property; instead, the values for the user and session are exposed as userId and sessionId. The response combines user and session information.

The login, logout, and currentuser APIs are as follows. They are system routes and are not versioned.

`POST /login` — User Login

Purpose: Verifies user credentials and creates an authenticated session with a JWT access token.

Access Routes:

Request Parameters

Parameter	Type	Required	Source
`username`	String	Yes	`request.body.username`
`password`	String	Yes	`request.body.password`

Behavior

Authenticates credentials and returns a session object.
Sets cookie: projectname-access-token[-tenantCodename]
Adds the same token in response headers.
Accepts either username or email fields (if both exist, username is prioritized). The mobile field is also accepted when the user has a mobile number on file.

Example

axios.post("/login", {
  email: "user@example.com",
  password: "securePassword"
});

Success Response

{
  "sessionId": "e81c7d2b-4e95-9b1e-842e-3fb9c8c1df38",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  //...
  "accessToken": "ey7....",
  "userBucketToken": "e56d....",
  "sessionNeedsEmail2FA": true,

}

Note on bucket tokens: The userBucketToken is for the external bucket service (used for general file uploads like documents and product images). User avatars do not use the external bucket service — they are uploaded via database buckets (dbBuckets) built into the auth service using the regular accessToken. See the Profile or Bucket Management sections for dbBucket avatar upload details.

Two-Factor Authentication (2FA): When the login response contains sessionNeedsEmail2FA: true, the session is not yet fully authorized. The accessToken is valid but all protected API calls will return 403 until 2FA is completed. Do not treat this login as successful — instead, store the accessToken, userId, and sessionId, and navigate the user to a 2FA verification page. The 2FA flow details are covered in the Verification Management prompt.

Error Responses

401 Unauthorized: Invalid credentials
403 Forbidden: Email/mobile verification or 2FA pending
400 Bad Request: Missing parameters

`POST /logout` — User Logout

Purpose: Terminates the current session and clears associated authentication tokens.

Behavior

Invalidates the session (if it exists).
Clears cookie projectname-access-token[-tenantCodename].
Returns a confirmation response (always 200 OK).

Example

axios.post("/logout", {}, {
  headers: { "Authorization": "Bearer your-jwt-token" }
});

Notes

Can be called without a session (idempotent behavior).
Works for both cookie-based and token-based sessions.

Success Response

{ "status": "OK", "message": "User logged out successfully" }

`GET /currentuser` — Current Session

Purpose Returns the currently authenticated user’s session.

Route Type sessionInfo

Authentication Requires a valid access token (header or cookie).

Request

No parameters.

Example

axios.get("/currentuser", {
  headers: { Authorization: "Bearer <jwt>" }
});

Success (200)

Returns the session object (identity, tenancy, token metadata):

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  "...": "..."
}

Note that the currentuser API returns a session object, so there is no id property, instead, the values for the user and session are exposed as userId and sessionId. The response is a mix of user and session information.

Errors

401 Unauthorized — No active session/token

{ "status": "ERR", "message": "No login found" }

Notes

Commonly called by web/mobile clients after login to hydrate session state.
Includes key identity/tenant fields and a token reference (if applicable).
Ensure a valid token is supplied to receive a 200 response.

After you complete this step, please ensure you have not made the following common mistakes:

The /currentuser API returns a mix of session and user data. There is no id property —use userId and sessionId.
Note that any API call to the auth service should use the /auth-api prefix after the application’s base URL.

After this prompt, the user may give you new instructions to update your output or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 3 - Verification Management

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document includes the verification processes for the autheitcation flow. Please read it carefully and implement all requirements described here.

The project has 1 auth service, 1 notification service, 1 BFF service, and 6 business services, plus other helper services such as bucket and realtime. In this document you will be informed only about the auth service.

Each service is a separate microservice application and listens for HTTP requests at different service URLs.

Accessing the backend

For the auth service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/auth-api
Staging: https://airbnb3-stage.mindbricks.co/auth-api
Production: https://airbnb3.mindbricks.co/auth-api

Any request that requires login must include a valid token in the Bearer authorization header.

After User Registration

Frontend should also be aware of verification after any login attempt. The login request may return a 401 or 403 with the error codes that indicates the verification needs.

{
  //...
  "errCode": "EmailVerificationNeeded",
  // or
  "errCode": "MobileVerificationNeeded",
}

Email Verification

In the registration response, check the emailVerificationNeeded property in the response root. If it is true, start the email verification flow.

After the login process, if you receive an HTTP error and the response contains an errCode with the value EmailVerificationNeeded, start the email verification flow.

Call the email verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the provided email address. The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the secretCode property of the response.
The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. If the secretCode is sent to the frontend for testing, display it on the input page so the user can copy and paste it.
The start response includes a codeIndex property. Display its value on the input page so the user can match the index in the message with the one on the screen.
When the user submits the code, complete the email verification using the complete route of the backend (described below) with the user’s email and the secret code.
After a successful email verification response, please check the response object to have the property ‘mobileVerificationNeeded’ as true, if so navigate to the mobile verification flow as described below. If no mobile verification is needed then just navigate the login page.

Below are the start and complete routes for email verification. These are system routes and therefore are not versioned.

`POST /verification-services/email-verification/start`

Purpose: Starts email verification by generating and sending a secret code.

Parameter	Type	Required	Description
`email`	String	Yes	User’s email address to verify

Example Request

{ "email": "user@example.com" }

Success Response

{
  "status": "OK", 
  "codeIndex": 1,
  // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT
  "timeStamp": 1784578660000,
  "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)",
  // expireTime: in seconds
  "expireTime": 86400,
  "verificationType": "byLink",

  // in testMode
  "secretCode": "123456",
  "userId": "user-uuid"
}

⚠️ In production, secretCode is not returned — it is only sent via email.

Error Responses

400 Bad Request: Already verified
403 Forbidden: Too many attempts (rate limit)

`POST /verification-services/email-verification/complete`

Purpose: Completes verification using the received code.

Parameter	Type	Required	Description
`email`	String	Yes	User’s email
`secretCode`	String	Yes	Verification code

Success Response

{
  "status": "OK", 
  "isVerified": true,
  "email": "user@email.com",
  // in testMode
  "userId": "user-uuid"
}

Error Responses

403 Forbidden: Code expired or mismatched
404 Not Found: No verification in progress

Mobile Verification

Mobile numbers must be in E.164 format (+ followed by country code and subscriber number, e.g. +905551234567). Use the PhoneInput component for mobile number inputs on verification pages.

In the registration response, check the mobileVerificationNeeded property in the response root. If it is true, start the mobile verification flow.

After the login process, if you receive a 403 error and the response contains an errCode with the value MobileVerificationNeeded, start the mobile verification flow.

Call the mobile verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the user’s mobile number. If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the secretCode property.
The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. If the secretCode is returned for testing, display it on the input page for easy copy/paste.
When the user submits the code, complete mobile verification using the complete route of the backend (described below) with the user’s email and the secret code.
The start response includes a codeIndex property. Display its value on the input page so the user can match the index shown in the message with the one on the screen.
After a successful mobile verification response, navigate to the login page.

Verification Order If both emailVerificationNeeded and mobileVerificationNeeded are true, handle both verification flows in order. First complete email verification, then mobile verification.

Below are the start and complete routes for mobile verification. These are system routes and therefore are not versioned.

`POST /verification-services/mobile-verification/start`

Parameter	Type	Required	Description
`email`	String	Yes	User’s email to locate mobile record

Success Response

{
  "status": "OK", 
  "codeIndex": 1,
  // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT
  "timeStamp": 1784578660000,
  "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)",
  // expireTime: in seconds
  "expireTime": 180,
  "verificationType": "byCode",

  // in testMode
  "secretCode": "123456",
  "userId": "user-uuid"
}

⚠️ secretCode is returned only in development.

Errors

400 Bad Request: Already verified
403 Forbidden: Rate-limited

`POST /verification-services/mobile-verification/complete`

Parameter	Type	Required	Description
`email`	String	Yes	Associated email
`secretCode`	String	Yes	Code received via SMS

Success Response

{
  "status": "OK", 
  "isVerified": true,
  "mobile": "+1 333 ...",
  // in testMode
  "userId": "user-uuid"
}

Resetting Password

Users can reset their forgotten passwords without a login required, through email verification. To be able to start a password reset flow, users will click on the “Reset Password” link in the login page.

Since there are two verification methods, by email or by mobile, for password reset, when the reset password link is clicked, frontend should ask user if they want to make the verification through email of mobile. According to the users selection the frontend shoudl start the related flow as explaned below step by step.

Password Reset By Email Flow

Call the password reset by email verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the provided email address. The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the secretCode property of the response.
The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. If the secretCode is sent to the frontend for testing, display it on the input page so the user can copy and paste it.
The start response includes a codeIndex property. Display its value on the input page so the user can match the index in the message with the one on the screen.
The input page should also include a double input area for the user to enter and confirm their new password.
When the user submits the code and the new password, complete the password reset by email using the complete route of the backend (described below) with the user’s email , the secret code and new password.
After a successful verification response, navigate to the login page.

Below are the start and complete routes for password reset by email verification. These are system routes and therefore are not versioned.

POST `/verification-services/password-reset-by-email/start`

Purpose:
Starts the password reset process by generating and sending a secret verification code.

Request Body

Parameter	Type	Required	Description
email	String	Yes	The email address of the user

{
  "email": "user@example.com"
}

Success Response

Returns secret code details (only in development environment) and confirmation that the verification step has been started.

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "codeIndex": 1,
  "secretCode": "123456", 
  "timeStamp": 1765484354,
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z",
  "verificationType": "byLink",
}

⚠️ In production, the secret code is only sent via email and not exposed in the API response.

Error Responses

401 NotAuthenticated: Email address not found or not associated with a user.
403 Forbidden: Sending a code too frequently (spam prevention).

POST `/verification-services/password-reset-by-email/complete`

Purpose:
Completes the password reset process by validating the secret code and updating the user’s password.

Request Body

Parameter	Type	Required	Description
email	String	Yes	The email address of the user
secretCode	String	Yes	The code received via email
password	String	Yes	The new password the user wants to set

{
  "email": "user@example.com",
  "secretCode": "123456",
  "password": "newSecurePassword123"
}

Success Response

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "isVerified": true
}

Error Responses

403 Forbidden:
- Secret code mismatch
- Secret code expired
- No ongoing verification found

Password Reset By Mobile Flow

Call the password reset by mobile verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the user’s mobile number. If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the secretCode property.
The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. If the secretCode is returned for testing, display it on the input page for easy copy/paste.
The start response includes a codeIndex property. Display its value on the input page so the user can match the index in the message with the one on the screen. Also display the half masked mobilenumber that comes in the response, to tell the user that their code is sent to this number.
The input page should also include a double input area for the user to enter and confirm their new password.
When the user submits the code, complete mobile verification using the complete route of the backend (described below) with the user’s email and the secret code.
After a successful mobile verification response, navigate to the login page.

Below are the start and complete routes for password reset by mobile verification. These are system routes and therefore are not versioned.

POST `/verification-services/password-reset-by-mobile/start`

Purpose:
Initiates the mobile-based password reset by sending a verification code to the user’s mobile.

Request Body

Parameter	Type	Required	Description
email	String	Yes	The email of the user that resets the password

{
  "email": "user@user.com"
}

Success Response

Returns the verification context (code returned only in development):

{
  "status": "OK",
  "codeIndex": 1,
  timeStamp: 133241255,
  "mobile": "+905.....67",
  "secretCode": "123456", 
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z",
  verificationType: "byLink"
}

⚠️ In production, the secretCode is not included in the response and is only sent via SMS.

Error Responses

400 Bad Request: Mobile already verified
403 Forbidden: Rate-limited (code already sent recently)
404 Not Found: User with provided mobile not found

POST `/verification-services/password-reset-by-mobile/complete`

Purpose:
Finalizes the password reset process by validating the received verification code and updating the user’s password.

Request Body

Parameter	Type	Required	Description
email	String	Yes	The email address of the user
secretCode	String	Yes	The code received via SMS
password	String	Yes	The new password to assign

{
  "email": "user@example.com",
  "secretCode": "123456",
  "password": "NewSecurePassword123!"
}

Success Response

{
  "userId": "user-uuid",
  "isVerified": true
}

Two-Factor Authentication (2FA)

This project has email two-factor authentication enabled. 2FA is different from email/mobile verification: verification proves ownership during registration (one-time), while 2FA runs on every login as an additional security layer.

How 2FA Works After Login

When a user logs in successfully, the login response includes accessToken, userId, sessionId, and all session data. However, when 2FA is active, the response also contains one or both of these flags:

sessionNeedsEmail2FA: true — email 2FA is required

When any of these flags are true, the session is NOT fully authorized. The accessToken is valid only for calling the 2FA verification endpoints. All other protected API calls will return 403 Forbidden with error code EmailTwoFactorNeeded or MobileTwoFactorNeeded until 2FA is completed.

2FA Frontend Flow

After a successful login, check the response for sessionNeedsEmail2FA or sessionNeedsMobile2FA.
If either is true, do not treat the user as authenticated. Store the accessToken, userId, and sessionId temporarily.
Navigate the user to a 2FA verification page.
On the 2FA page, immediately call the 2FA start endpoint (described below) with the userId and sessionId. This triggers sending the verification code to the user’s email.
Display a 6-digit code input. If the response contains secretCode (test/development mode), display it on the page so the user can copy and paste it.
The start response includes a codeIndex property. Display its value on the page so the user can match the index in the message with the one on the screen.
When the user submits the code, call the 2FA complete endpoint with userId, sessionId, and secretCode.
On success, the complete endpoint returns the updated session object with the 2FA flag cleared. Now set the user as fully authenticated and navigate to the main application page.
Provide a “Resend Code” button with a 60-second cooldown to prevent spam.
Provide a “Cancel” option that discards the partial session and returns the user to the login page.

Email 2FA Endpoints

`POST /verification-services/email-2factor-verification/start`

Purpose: Starts email-based 2FA by generating and sending a verification code to the user’s email.

Parameter	Type	Required	Description
`userId`	String	Yes	The user’s ID
`sessionId`	String	Yes	The current session ID

Example Request

{
  "userId": "user-uuid",
  "sessionId": "session-uuid"
}

Success Response

{
  "status": "OK",
  "sessionId": "session-uuid",
  "userId": "user-uuid",
  "codeIndex": 1,
  "timeStamp": 1784578660000,
  "date": "Mon Jul 20 2026 23:17:40 GMT+0300",
  "expireTime": 86400,
  "verificationType": "byCode",

  // in testMode only
  "secretCode": "123456"
}

⚠️ In production, secretCode is not returned — it is only sent via email.

Error Responses

403 Forbidden: Code resend attempted before cooldown (60s)
401 Unauthorized: Session not found

`POST /verification-services/email-2factor-verification/complete`

Purpose: Completes email 2FA by validating the code and clearing the session 2FA flag.

Parameter	Type	Required	Description
`userId`	String	Yes	The user’s ID
`sessionId`	String	Yes	The session ID
`secretCode`	String	Yes	Verification code from email

Success Response

Returns the updated session with sessionNeedsEmail2FA: false:

{
  "sessionId": "session-uuid",
  "userId": "user-uuid",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "sessionNeedsEmail2FA": false,
  "accessToken": "jwt-token",
  "...": "..."
}

Error Responses

403 Forbidden: Code mismatch or expired
403 Forbidden: No ongoing verification found
401 Unauthorized: Session does not exist

Important 2FA Notes

One code per session: Only one active verification code exists per session at a time.
Resend throttling: Code requests are throttled — wait at least 60 seconds between resend attempts.
Code expiration: Codes expire after 86400 seconds.
Session stays valid: The accessToken from login remains the same throughout the 2FA flow — you do not get a new token. The complete response returns the same session with the 2FA flag cleared.
/currentuser works during 2FA: The /currentuser endpoint does not enforce 2FA, so it can be called during the 2FA flow. However, all other protected endpoints will return 403.

** Please dont forget to arrange the code to be able to navigate to the verification pages both after registrations and login attempts if verification is needed.**

After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 4 - Profile Management

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document includes information and api descriptions about building a profile page in the frontend using the auth service profile api calls. Avatar images are stored in the auth service’s database buckets — no external bucket service is needed for avatars.

The project has 1 auth service, 1 notification service, 1 BFF service, and 6 business services, plus other helper services such as bucket and realtime. In this document you will use the auth service (including its database bucket endpoints for avatar uploads).

Each service is a separate microservice application and listens for HTTP requests at different service URLs.

Accessing the backend

Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the register and login pages include a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services.

The base URL of the application in each environment is as follows:

Preview: https://airbnb3.prw.mindbricks.com
Staging: https://airbnb3-stage.mindbricks.co
Production: https://airbnb3.mindbricks.co

For the auth service, service urls are as follows:

Preview: https://airbnb3.prw.mindbricks.com/auth-api
Staging: https://airbnb3-stage.mindbricks.co/auth-api
Production: https://airbnb3.mindbricks.co/auth-api

For each other service, the service URL will be given in the service sections.

Any request that requires login must include a valid token in the Bearer authorization header.

Avatar Storage (Database Buckets)

User avatars and tenant avatars are stored directly in the auth service database using database buckets (dbBuckets). This means avatar files are uploaded to and downloaded from the auth service itself — no external bucket service is needed.

The auth service provides these avatar buckets:

User Avatar Bucket

Upload: POST {authBaseUrl}/bucket/userAvatars/upload Download by ID: GET {authBaseUrl}/bucket/userAvatars/download/{fileId} Download by Key: GET {authBaseUrl}/bucket/userAvatars/download/key/{accessKey}

Read access: Public (anyone can view avatars, no auth needed for download)
Write access: Authenticated (any logged-in user can upload their own avatar)
Allowed types: image/png, image/jpeg, image/webp, image/gif
Max size: 5 MB
Access key: Each uploaded file gets a 12-character random key for shareable links

Upload example (multipart/form-data):

const formData = new FormData();
formData.append('file', croppedImageBlob, 'avatar.png');

const response = await fetch(`${authBaseUrl}/bucket/userAvatars/upload`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
  },
  body: formData,
});

const result = await response.json();
// result.file.id — the file ID (use for download URL)
// result.file.accessKey — 12-char key for public sharing
// result.file.fileName, result.file.mimeType, result.file.fileSize

After uploading, update the user’s avatar field with the download URL:

const avatarUrl = `${authBaseUrl}/bucket/userAvatars/download/${result.file.id}`;
// OR use the access key for a shorter, shareable URL:
const avatarUrl = `${authBaseUrl}/bucket/userAvatars/download/key/${result.file.accessKey}`;

await updateProfile({ avatar: avatarUrl });

Displaying avatars: Since read access is public, avatar URLs can be used directly in <img> tags without any authentication token:

<img src={user.avatar} alt="Avatar" />

Listing and Deleting Avatars

The auth service also provides metadata APIs for each bucket (auto-generated):

API	Method	Path	Description
`getUserAvatarsFile`	GET	`/v1/userAvatarsFiles/:id`	Get file metadata (no binary)
`listUserAvatarsFiles`	GET	`/v1/userAvatarsFiles`	List files with filtering
`deleteUserAvatarsFile`	DELETE	`/v1/userAvatarsFiles/:id`	Delete file and its data

Profile Page

Design a profile page to manage (view and edit) user information. The profile page should include an avatar upload component that uploads to the database bucket.

On the profile page, you will need 4 business APIs: getUser , updateProfile, updateUserPassword and archiveProfile. Do not rely on the /currentuser response for profile data, because it contains session information. The most recent user data is in the user database and should be accessed via the getUser business API.

The updateProfile, updateUserPassword and archiveProfile api can only be called by the users themselves. They are designed specific to the profile page.

Avatar upload workflow:

User selects an image → crop with react-easy-crop (install it, do not implement your own)
Convert cropped area to a Blob
Upload to POST {authBaseUrl}/bucket/userAvatars/upload with the access token
Get back the file metadata (id, accessKey)
Construct the download URL: {authBaseUrl}/bucket/userAvatars/download/key/{accessKey}
Call updateProfile({ avatar: downloadUrl }) to save it

Note that the user cannot change/update their email or roleId.

For password update you should make a separate block in the UI, so that user can enter old password, new password and confirm new password before calling the updateUserPassword.

Here are the 3 auth APIs—getUser , updateProfile and updateUserPassword— as follows: You can access these APIs through the auth service base URL, {appUrl}/auth-api.

`Get User` API

This api is used by admin roles or the users themselves to get the user profile information.

Rest Route

The getUser API REST controller can be triggered via the following route:

/v1/users/:userId

Rest Request Parameters

The getUser api has got 1 regular request parameter

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
userId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/users/:userId

  axios({
    method: 'GET',
    url: `/v1/users/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Profile` API

This route is used by users to update their profiles.

Rest Route

The updateProfile API REST controller can be triggered via the following route:

/v1/profile/:userId

Rest Request Parameters

The updateProfile api has got 5 regular request parameters

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
fullname	String	false	request.body?.[“fullname”]
avatar	String	false	request.body?.[“avatar”]
preferredLanguage	String	false	request.body?.[“preferredLanguage”]
bio	Text	false	request.body?.[“bio”]
userId : This id paremeter is used to select the required data object that will be updated
fullname : A string value to represent the fullname of the user
avatar : The avatar url of the user. A random avatar will be generated if not provided
preferredLanguage : User’s preferred language for the application interface
bio : User’s biography or profile description

REST Request To access the api you can use the REST controller with the path PATCH /v1/profile/:userId

  axios({
    method: 'PATCH',
    url: `/v1/profile/${userId}`,
    data: {
            fullname:"String",  
            avatar:"String",  
            preferredLanguage:"String",  
            bio:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Userpassword` API

This route is used to update the password of users in the profile page by users themselves

Rest Route

The updateUserPassword API REST controller can be triggered via the following route:

/v1/userpassword/:userId

Rest Request Parameters

The updateUserPassword api has got 3 regular request parameters

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
oldPassword	String	true	request.body?.[“oldPassword”]
newPassword	String	true	request.body?.[“newPassword”]
userId : This id paremeter is used to select the required data object that will be updated
oldPassword : The old password of the user that will be overridden bu the new one. Send for double check.
newPassword : The new password of the user to be updated

REST Request To access the api you can use the REST controller with the path PATCH /v1/userpassword/:userId

  axios({
    method: 'PATCH',
    url: `/v1/userpassword/${userId}`,
    data: {
            oldPassword:"String",  
            newPassword:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Archiving A Profile

A user may want to archive their profile. So the profile page should include an archive section for the users to archive their accounts. When an account is archived, it is marked as archived and an aarchiveDate is atteched to the profile. All user data is kept in the database for 1 month after user archived. If user tries to login or register with the same email, the account will be activated again. But if no login or register occures in 1 month after archiving, the profile and its related data will be deleted permanenetly. So in the profile page,

The arcihve options should be accepted after user writes a text like (“ARCHİVE MY ACCOUNT”) to a confirmation dialog, so that frontend UX can ensure this is not an unconscious request.
The user should be warned about the process, that his account will be available for a restore for 1 month.

The archive api, can only be called by the users themselves and its used as follows.

`Archive Profile` API

This api is used by users to archive their profiles.

Rest Route

The archiveProfile API REST controller can be triggered via the following route:

/v1/archiveprofile/:userId

Rest Request Parameters

The archiveProfile api has got 1 regular request parameter

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
userId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/archiveprofile/:userId

  axios({
    method: 'DELETE',
    url: `/v1/archiveprofile/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

After you complete this step, please ensure you have not made the following common mistakes:

Avatar uploads go to the auth service’s database bucket endpoints (/bucket/userAvatars/upload), not to an external bucket service. Use the same accessToken (Bearer header) for both auth APIs and avatar bucket uploads — no bucket-specific tokens are needed.
Note that any api call to the application backend is based on a service base url, in this prompt all auth apis (including avatar bucket endpoints) should be called by the auth service base url.
On the profile page, fetch the latest user data from the service using getUser. The /currentuser API is session-stored data; the latest data is in the database.
When you upload the avatar image on the profile page, use the returned download URL as the user’s avatar property and update the user record when the Save button is clicked.

After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 5 - User Management

This document is the 2nd part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides extensive instruction for administrative user management.

Service Access

User management is handled through auth service again.

Auth service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the auth service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/auth-api
Staging: https://airbnb3-stage.mindbricks.co/auth-api
Production: https://airbnb3.mindbricks.co/auth-api

Please note that any feature in this document is open to admins only. When the user logins, the response includes a roleId field.

This roleId should one of these following admin roles. superAdmin, admin,

Scope

Auth service provides following feature for user management in airbnb application.

These features are already handled in the previous part.

User Registration
User Authentication
Password Reset
Email (and/or) Mobile Verification
Profile Management

These features will be handled in this part.

User Management
User Groups Management
Permission Manageemnt

API Structure

Object Structure of a Successful Response

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

User Management

User management will be one of the main parts of the administrative manageemnts, so there will be a minimal but fancy users page in the admin dashboard.

User Roles

superadmin : The first creator of the backend, the owner of the application, root user, has got an absolute authroization on all actions. It can not be assgined any other user. It can’t be unassigned. Super admin user can not be deleted in any way.
admin : The role that can be assigned to any user by the super admin. This role includes most permissions that super admin have, but admins can’t assign admin roles, can’t unassign an admin role, can’t delete other users who have admin role. In addition to these limitations, some critical actions in the business services may also be open to only super admin.
user : The standard role that is assgined to every user when first created or registered. This role doesnt have any privilages and can access to their own data or public data.

The roles object is a hardcoded object in the generated code, and it contains the following roles:

{
  "superAdmin": "'superAdmin'",
  "admin": "'admin'",
  "user": "'user'"
}

Each user may have only one role, and it is given in /login , /currentuser or /users/:userId response as follows

{
  // ...
  "roleId":"superAdmin",
  // ...
}

Listing Users

You can list users using the listUsers api.

`List Users` API

The list of users is filtered by the tenantId.

Rest Route

The listUsers API REST controller can be triggered via the following route:

/v1/users

Rest Request Parameters

Filter Parameters

The listUsers api supports 3 optional filter parameters for filtering list results:

email (String): A string value to represent the user’s email.

Single (partial match, case-insensitive): ?email=<value>
Multiple: ?email=<value1>&email=<value2>
Null: ?email=null

fullname (String): A string value to represent the fullname of the user

Single (partial match, case-insensitive): ?fullname=<value>
Multiple: ?fullname=<value1>&fullname=<value2>
Null: ?fullname=null

roleId (String): A string value to represent the roleId of the user.

Single (partial match, case-insensitive): ?roleId=<value>
Multiple: ?roleId=<value1>&roleId=<value2>
Null: ?roleId=null

REST Request To access the api you can use the REST controller with the path GET /v1/users

  axios({
    method: 'GET',
    url: '/v1/users',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // email: '<value>' // Filter by email
        // fullname: '<value>' // Filter by fullname
        // roleId: '<value>' // Filter by roleId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "users",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"users": [
		{
			"id": "ID",
			"email": "String",
			"password": "String",
			"fullname": "String",
			"avatar": "String",
			"roleId": "String",
			"emailVerified": "Boolean",
			"preferredLanguage": "String",
			"bio": "Text",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Searching Users

You may search users with their full names, emails. The search is done in elasticsearch index of the user table so a fast response is provided by the backend. You can send search request on each character update in the search box but start searching after 3 chars. The keyword parameter that is used in the business logic of the api, is read from the keyword query parameter.

eg: GET /v1/searchusers?keyword=Joe

When the user deletes the search keyword, use the listUsers api to get the full list again.

`Search Users` API

The list of users is filtered by the tenantId.

Rest Route

The searchUsers API REST controller can be triggered via the following route:

/v1/searchusers

Rest Request Parameters

The searchUsers api has got 1 regular request parameter

Parameter	Type	Required	Population
keyword	String	true	request.query?.[“keyword”]
keyword :

Filter Parameters

The searchUsers api supports 1 optional filter parameter for filtering list results:

roleId (String): A string value to represent the roleId of the user.

Single (partial match, case-insensitive): ?roleId=<value>
Multiple: ?roleId=<value1>&roleId=<value2>
Null: ?roleId=null

REST Request To access the api you can use the REST controller with the path GET /v1/searchusers

  axios({
    method: 'GET',
    url: '/v1/searchusers',
    data: {
    
    },
    params: {
             keyword:'"String"',  
    
        // Filter parameters (see Filter Parameters section above)
        // roleId: '<value>' // Filter by roleId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "users",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"users": [
		{
			"id": "ID",
			"email": "String",
			"password": "String",
			"fullname": "String",
			"avatar": "String",
			"roleId": "String",
			"emailVerified": "Boolean",
			"preferredLanguage": "String",
			"bio": "Text",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

Pagination

When you list the users please use pagination. To be able to use pagination you should provide a pageNumber paramater in the query. The default row count for one page is 25, add an option for user to change it to 50 or 100. You can provide this value to the api through the pageRowCount parameter;

GET /users?pageNumber=1&pageRowCount=50

Creating Users

The user management console in the admin dashboard should provide UX components for user creating by admins. When creating users, it should also be possible to upload user avatar. Note that when creating, updating users, admins can not set emailVerified as true, since it is a logical mechanism and should be verified only through verification processes.

`Create User` API

This api is used by admin roles to create a new user manually from admin panels

Rest Route

The createUser API REST controller can be triggered via the following route:

/v1/users

Rest Request Parameters

The createUser api has got 6 regular request parameters

Parameter	Type	Required	Population
avatar	String	false	request.body?.[“avatar”]
email	String	true	request.body?.[“email”]
password	String	true	request.body?.[“password”]
fullname	String	true	request.body?.[“fullname”]
preferredLanguage	String	false	request.body?.[“preferredLanguage”]
bio	Text	false	request.body?.[“bio”]
avatar : The avatar url of the user. If not sent, a default random one will be generated.
email : A string value to represent the user’s email.
password : A string value to represent the user’s password. It will be stored as hashed.
fullname : A string value to represent the fullname of the user
preferredLanguage : User’s preferred language for the application interface
bio : User’s biography or profile description

REST Request To access the api you can use the REST controller with the path POST /v1/users

  axios({
    method: 'POST',
    url: '/v1/users',
    data: {
            avatar:"String",  
            email:"String",  
            password:"String",  
            fullname:"String",  
            preferredLanguage:"String",  
            bio:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Avatar Upload

Avatars are stored in the auth service’s database bucket — no external bucket service needed. Upload the avatar image to the auth service’s userAvatars bucket endpoint:

POST {authBaseUrl}/bucket/userAvatars/upload

Use the regular access token (Bearer header) for authentication — the same token used for all other API calls. The upload body is multipart/form-data with a file field.

After upload, the response returns file metadata including id and accessKey. Construct a public download URL and save it in the user’s avatar field:

const avatarUrl = `${authBaseUrl}/bucket/userAvatars/download/key/${result.file.accessKey}`;
await updateUser(userId, { avatar: avatarUrl });

Since the userAvatars bucket has public read access, avatar URLs work directly in <img> tags without auth.

Before the avatar upload, use the react-easy-crop lib for zoom, pan and crop. This component is also used in the profile page — reuse the existing code.

Updating Users

User update is possible by updateUserapi. However since this update api is also called by teh user themselves it is lmited with name and avatar change (or any other user related property). For roleId and password updates seperate apis are used. So arrange the user update UI as to update the user info, as to set roleId and as to update password.

`Update User` API

This route is used by admins to update user profiles.

Rest Route

The updateUser API REST controller can be triggered via the following route:

/v1/users/:userId

Rest Request Parameters

The updateUser api has got 5 regular request parameters

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
fullname	String	false	request.body?.[“fullname”]
avatar	String	false	request.body?.[“avatar”]
preferredLanguage	String	false	request.body?.[“preferredLanguage”]
bio	Text	false	request.body?.[“bio”]
userId : This id paremeter is used to select the required data object that will be updated
fullname : A string value to represent the fullname of the user
avatar : The avatar url of the user. A random avatar will be generated if not provided
preferredLanguage : User’s preferred language for the application interface
bio : User’s biography or profile description

REST Request To access the api you can use the REST controller with the path PATCH /v1/users/:userId

  axios({
    method: 'PATCH',
    url: `/v1/users/${userId}`,
    data: {
            fullname:"String",  
            avatar:"String",  
            preferredLanguage:"String",  
            bio:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

For role updates there are some rules.

Superadmin role can not be unassigned even by superadmin.
Admin roles can be assgined or unassgined only by superadmin.
All other roles can be assigned and unassgined by admins and superadmin.

For password updates there are some rules.

Superadmin and admin passwords can be updated only by superadmin.
Admins can update only non-admin passwords.

`Update Userrole` API

This route is used by admin roles to update the user role.The default role is user when a user is registered. A user’s role can be updated by superAdmin or admin

Rest Route

The updateUserRole API REST controller can be triggered via the following route:

/v1/userrole/:userId

Rest Request Parameters

The updateUserRole api has got 2 regular request parameters

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
roleId	String	true	request.body?.[“roleId”]
userId : This id paremeter is used to select the required data object that will be updated
roleId : The new roleId of the user to be updated

REST Request To access the api you can use the REST controller with the path PATCH /v1/userrole/:userId

  axios({
    method: 'PATCH',
    url: `/v1/userrole/${userId}`,
    data: {
            roleId:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Userpasswordbyadmin` API

This route is used to change any user password by admins only. Superadmin can chnage all passwords, admins can change only nonadmin passwords

Rest Route

The updateUserPasswordByAdmin API REST controller can be triggered via the following route:

/v1/userpasswordbyadmin/:userId

Rest Request Parameters

The updateUserPasswordByAdmin api has got 2 regular request parameters

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
password	String	true	request.body?.[“password”]
userId : This id paremeter is used to select the required data object that will be updated
password : The new password of the user to be updated

REST Request To access the api you can use the REST controller with the path PATCH /v1/userpasswordbyadmin/:userId

  axios({
    method: 'PATCH',
    url: `/v1/userpasswordbyadmin/${userId}`,
    data: {
            password:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

Deleting Users

Deleting users is possible in certain conditions.

SuperAdmin can not be deleted.
Admins can be deleted by only superadmin.
Users can be deleted by admins or superadmin.

`Delete User` API

This api is used by admins to delete user profiles.

Rest Route

The deleteUser API REST controller can be triggered via the following route:

/v1/users/:userId

Rest Request Parameters

The deleteUser api has got 1 regular request parameter

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
userId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/users/:userId

  axios({
    method: 'DELETE',
    url: `/v1/users/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"preferredLanguage": "String",
		"bio": "Text",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

User Group Management

This application backend provides user groups with two data tables, UserGroup and UserGroupMember, so the admin dashboard UI should support user group creating/deleting and adding or removing member users to the groups.

Design a minimal and fancy user group management console where we can manage the groups and their members. The user groups may be in a main list and when selected a right drawer can show the members of the group, and at the bottom of the drawer there can be a user search area to select the user to be added to the group. For user searching use the user search api and make a call to the api in each character added to the search edit box.

To manage user groups and members, use the related apis below.

`Create Usergroup` API

This route is used by admin roles to create a new usergroup manually from admin panels

Rest Route

The createUserGroup API REST controller can be triggered via the following route:

/v1/usergroups

Rest Request Parameters

The createUserGroup api has got 2 regular request parameters

Parameter	Type	Required	Population
avatar	String	false	request.body?.[“avatar”]
groupName	String	true	request.body?.[“groupName”]
avatar : A string value to represent the groups icon.
groupName : A string value to represent the group name.

REST Request To access the api you can use the REST controller with the path POST /v1/usergroups

  axios({
    method: 'POST',
    url: '/v1/usergroups',
    data: {
            avatar:"String",  
            groupName:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Usergroup` API

This route is used by admin to update user groups.

Rest Route

The updateUserGroup API REST controller can be triggered via the following route:

/v1/usergroups/:userGroupId

Rest Request Parameters

The updateUserGroup api has got 3 regular request parameters

Parameter	Type	Required	Population
userGroupId	ID	true	request.params?.[“userGroupId”]
groupName	String	false	request.body?.[“groupName”]
avatar	String	false	request.body?.[“avatar”]
userGroupId : This id paremeter is used to select the required data object that will be updated
groupName : A string value to represent the group name.
avatar : A string value to represent the groups icon.

REST Request To access the api you can use the REST controller with the path PATCH /v1/usergroups/:userGroupId

  axios({
    method: 'PATCH',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
            groupName:"String",  
            avatar:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Usergroup` API

This route is used by admin to delete a user group.

Rest Route

The deleteUserGroup API REST controller can be triggered via the following route:

/v1/usergroups/:userGroupId

Rest Request Parameters

The deleteUserGroup api has got 1 regular request parameter

Parameter	Type	Required	Population
userGroupId	ID	true	request.params?.[“userGroupId”]
userGroupId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/usergroups/:userGroupId

  axios({
    method: 'DELETE',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Usergroup` API

This is a public route to get the user group information.

Rest Route

The getUserGroup API REST controller can be triggered via the following route:

/v1/usergroups/:userGroupId

Rest Request Parameters

The getUserGroup api has got 1 regular request parameter

Parameter	Type	Required	Population
userGroupId	ID	true	request.params?.[“userGroupId”]
userGroupId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/usergroups/:userGroupId

  axios({
    method: 'GET',
    url: `/v1/usergroups/${userGroupId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroup",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroup": {
		"id": "ID",
		"groupName": "String",
		"avatar": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Usergroups` API

This is a public route to get the list of groups.

Rest Route

The listUserGroups API REST controller can be triggered via the following route:

/v1/usergroups

Rest Request Parameters

Filter Parameters

The listUserGroups api supports 2 optional filter parameters for filtering list results:

groupName (String): A string value to represent the group name.

Single (partial match, case-insensitive): ?groupName=<value>
Multiple: ?groupName=<value1>&groupName=<value2>
Null: ?groupName=null

avatar (String): A string value to represent the groups icon.

Single (partial match, case-insensitive): ?avatar=<value>
Multiple: ?avatar=<value1>&avatar=<value2>
Null: ?avatar=null

REST Request To access the api you can use the REST controller with the path GET /v1/usergroups

  axios({
    method: 'GET',
    url: '/v1/usergroups',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // groupName: '<value>' // Filter by groupName
        // avatar: '<value>' // Filter by avatar
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroups",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"userGroups": [
		{
			"id": "ID",
			"groupName": "String",
			"avatar": "String",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

A user group member is stored in the db with groupId and userId fields. The id field identifies the membership, so when removing a user from a group, the membership record (UserGroupMember) should be deleted by this id. The UserGroupMember record also has an ownerId which is automatically added to teh record from the session’s userId. This ownerId identifes the admin user who added the user to the group.

`Create Usergroupmember` API

This route is used by admin roles to add a user to a group.

Rest Route

The createUserGroupMember API REST controller can be triggered via the following route:

/v1/usergroupmembers

Rest Request Parameters

The createUserGroupMember api has got 2 regular request parameters

Parameter	Type	Required	Population
groupId	ID	true	request.body?.[“groupId”]
userId	ID	true	request.body?.[“userId”]
groupId : An ID value to represent the group that the user is asssigned as a memeber to.
userId : An ID value to represent the user that is assgined as a member to the group.

REST Request To access the api you can use the REST controller with the path POST /v1/usergroupmembers

  axios({
    method: 'POST',
    url: '/v1/usergroupmembers',
    data: {
            groupId:"ID",  
            userId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMember",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroupMember": {
		"id": "ID",
		"groupId": "ID",
		"userId": "ID",
		"ownerId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Usergroupmember` API

This route is used by admin to delete a member from a group.

Rest Route

The deleteUserGroupMember API REST controller can be triggered via the following route:

/v1/usergroupmembers/:userGroupMemberId

Rest Request Parameters

The deleteUserGroupMember api has got 1 regular request parameter

Parameter	Type	Required	Population
userGroupMemberId	ID	true	request.params?.[“userGroupMemberId”]
userGroupMemberId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/usergroupmembers/:userGroupMemberId

  axios({
    method: 'DELETE',
    url: `/v1/usergroupmembers/${userGroupMemberId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMember",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"userGroupMember": {
		"id": "ID",
		"groupId": "ID",
		"userId": "ID",
		"ownerId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Usergroupmembers` API

This is a public route to get the list of group members of a group.

Rest Route

The listUserGroupMembers API REST controller can be triggered via the following route:

/v1/listusergroupmembers/:groupId

Rest Request Parameters

The listUserGroupMembers api has got 1 regular request parameter

Parameter	Type	Required	Population
groupId	ID	true	request.params?.[“groupId”]
groupId : An ID value to represent the group that the user is asssigned as a memeber to… The parameter is used to query data.

Filter Parameters

The listUserGroupMembers api supports 2 optional filter parameters for filtering list results:

userId (ID): An ID value to represent the user that is assgined as a member to the group.

Single: ?userId=<value>
Multiple: ?userId=<value1>&userId=<value2>
Null: ?userId=null

ownerId (ID): An ID value to represent the admin user who assgined the member.

Single: ?ownerId=<value>
Multiple: ?ownerId=<value1>&ownerId=<value2>
Null: ?ownerId=null

REST Request To access the api you can use the REST controller with the path GET /v1/listusergroupmembers/:groupId

  axios({
    method: 'GET',
    url: `/v1/listusergroupmembers/${groupId}`,
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // ownerId: '<value>' // Filter by ownerId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "userGroupMembers",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"userGroupMembers": [
		{
			"id": "ID",
			"groupId": "ID",
			"userId": "ID",
			"ownerId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"user": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

When you list user group members, a user object will also be inserted in each userGroupMember object, with fullname, avatar, email.

Avatar Storage (Database Buckets)

(This information is also covered in the Profile prompt.)

Avatars are stored in the auth service’s database buckets — uploaded to and downloaded from the auth service directly using the regular access token.

User Avatar Bucket:

Upload: POST {authBaseUrl}/bucket/userAvatars/upload (multipart/form-data, file field)
Download: GET {authBaseUrl}/bucket/userAvatars/download/key/{accessKey} (public, no auth needed)
Allowed: image/png, image/jpeg, image/webp, image/gif (max 5 MB)

When uploading an avatar (for user creation or update), send the image to the bucket, get back the accessKey, construct the download URL, and store it in the user’s avatar field via the update API.

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 6 - MCP BFF Integration

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides comprehensive instructions for integrating the MCP BFF (Model Context Protocol - Backend for Frontend) service into the frontend application. The MCP BFF is the central gateway between the frontend AI chat and all backend services.

MCP BFF Architecture Overview

The Airbnb application uses an MCP BFF service that aggregates multiple backend MCP servers into a single frontend-facing API. Instead of the frontend connecting to each service’s MCP endpoint directly, it communicates exclusively through the MCP BFF.

┌────────────┐     ┌───────────┐     ┌─────────────────┐
│  Frontend   │────▶│  MCP BFF  │────▶│  Auth Service    │
│  (Chat UI)  │     │  :3005    │────▶│  Business Svc 1  │
│             │◀────│           │────▶│  Business Svc N  │
└────────────┘ SSE └───────────┘     └─────────────────┘

Key Responsibilities

Tool Aggregation: Discovers and registers tools from all connected MCP services
Session Forwarding: Injects the user’s accessToken into every MCP tool call
AI Orchestration: Routes user messages to the AI model, which decides which tools to call
SSE Streaming: Streams chat responses, tool executions, and results to the frontend in real-time
Elasticsearch: Provides direct search/aggregation endpoints across all project indices
Logging: Provides log viewing and real-time console streaming endpoints

MCP BFF Service URLs

For the MCP BFF service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/mcpbff-api
Staging: https://airbnb3-stage.mindbricks.co/mcpbff-api
Production: https://airbnb3.mindbricks.co/mcpbff-api

All endpoints below are relative to the MCP BFF base URL.

Authentication

All MCP BFF endpoints require authentication. The user’s access token (obtained from the Auth service login) must be included in every request:

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${accessToken}`,
};

Chat API (AI Interaction)

The chat API is the primary interface for AI-powered conversations. It supports both regular HTTP responses and SSE streaming for real-time output.

POST /api/chat — Regular Chat

Send a message and receive the complete AI response.

const response = await fetch(`${mcpBffUrl}/api/chat`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    message: "Show me all orders from last week",
    conversationId: "optional-conversation-id",  // for conversation context
    context: {}  // additional context
  }),
});

POST /api/chat/stream — SSE Streaming Chat (Recommended)

Stream the AI response in real-time using Server-Sent Events (SSE). This is the recommended approach for chat UIs as it provides immediate feedback while the AI is thinking, calling tools, and generating text.

Request:

const response = await fetch(`${mcpBffUrl}/api/chat/stream`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    message: "Create a new product called Widget",
    conversationId: conversationId,       // optional, auto-generated if omitted
    disabledServices: [],                 // optional, service names to exclude
  }),
});

Response: The server responds with Content-Type: text/event-stream. Each SSE frame follows the standard format:

event: <eventType>\n
data: <JSON>\n
\n

SSE Event Types

The streaming endpoint emits the following event types in order:

Event	When	Data Shape
`start`	First event, once per stream	`{ conversationId, provider, aliasMapSummary }`
`text`	AI text token streamed (many per response)	`{ content }`
`tool_start`	AI decided to call a tool	`{ tool }`
`tool_executing`	Tool invocation started with resolved args	`{ tool, args }`
`tool_result`	Tool execution completed	`{ tool, result, success, error? }` — check for `__frontendAction`
`error`	Unrecoverable error	`{ message }`
`done`	Last event, once per stream	`{ conversationId, toolCalls, processingTime, aliasMapSummary }`

SSE Event Data Reference

start — Always the first event. Use conversationId for subsequent requests in the same conversation.

{
  "conversationId": "1d143df6-29fd-49f6-823b-524b8b3b4453",
  "provider": "anthropic",
  "aliasMapSummary": { "enabled": true, "count": 0, "samples": [] }
}

text — Streamed token-by-token as the AI generates its response. Concatenate content fields to build the full markdown message.

{ "content": "Here" }
{ "content": "'s your" }
{ "content": " current session info" }

tool_start — The AI decided to call a tool. Use this to show a loading/spinner UI for the tool.

{ "tool": "currentuser" }

tool_executing — Tool is now executing with these arguments. Use this to display what the tool is doing.

{ "tool": "currentuser", "args": { "organizationCodename": "babil" } }

tool_result — Tool finished. Check success to determine if it succeeded. The result field contains the MCP tool response envelope.

{
  "tool": "currentuser",
  "result": {
    "success": true,
    "service": "auth",
    "tool": "currentuser",
    "result": {
      "content": [{ "type": "text", "text": "{...JSON...}" }]
    }
  },
  "success": true
}

On failure, success is false and an error string is present:

{
  "tool": "listProducts",
  "error": "Connection refused",
  "success": false
}

done — Always the last event. Contains a summary of all tool calls made and total processing time in milliseconds.

{
  "conversationId": "1d143df6-29fd-49f6-823b-524b8b3b4453",
  "toolCalls": [
    { "tool": "currentuser", "result": { "success": true, "..." : "..." } }
  ],
  "processingTime": 10026,
  "aliasMapSummary": {
    "enabled": true,
    "count": 6,
    "samples": [{ "alias": "user_admin_admin_com" }, { "alias": "tenant_admin_admin_com" }]
  }
}

error — Sent when an unrecoverable error occurs (e.g., AI service unavailable). The stream ends after this event.

{ "message": "AI service not configured. Please configure OPENAI_API_KEY or ANTHROPIC_API_KEY in environment variables" }

SSE Event Lifecycle

A typical conversation stream follows this lifecycle:

start
├── text (repeated)              ← AI's initial text tokens
├── tool_start                   ← AI decides to call a tool
├── tool_executing               ← tool running with resolved args
├── tool_result                  ← tool finished
├── text (repeated)              ← AI continues writing after tool result
├── tool_start → tool_executing → tool_result   ← may repeat
├── text (repeated)              ← AI's final text tokens
done

Multiple tool calls can happen in a single stream. The AI interleaves text and tool calls — text before tools (explanation), tools in the middle (data retrieval), and text after tools (formatted response using the tool results).

Inline Segment Rendering (Critical UX Pattern)

Tool cards MUST be rendered inline inside the assistant message bubble, at the exact position where they occur in the stream — not grouped at the top, not grouped at the bottom, and not outside the bubble.

The assistant message is an ordered list of segments: text segments and tool segments, interleaved in the order they arrive. Each segment appears inside the same message bubble, in sequence:

┌─────────────────────────────────────────────────┐
│  [Rendered Markdown — text before tool call]     │
│                                                  │
│  ┌─ Tool Card ─────────────────────────────────┐ │
│  │ 🔧 currentuser                    ✓ success │ │
│  │ args: { organizationCodename: "babil" }     │ │
│  └─────────────────────────────────────────────┘ │
│                                                  │
│  [Rendered Markdown — text after tool call]       │
│                                                  │
│  ┌─ Tool Card ─────────────────────────────────┐ │
│  │ 🔧 listProducts                  ✓ success  │ │
│  └─────────────────────────────────────────────┘ │
│                                                  │
│  [Rendered Markdown — final text]                │
└─────────────────────────────────────────────────┘

To achieve this, maintain an ordered segments array. Each segment is either { type: 'text', content: string } or { type: 'tool', ... }. When SSE events arrive:

text — Append to the last segment if it is a text segment; otherwise push a new text segment.
tool_start — Push a new tool segment (status: running). This “cuts” the current text segment — any further text events after the tool completes will start a new text segment.
tool_executing — Update the current tool segment with args.
tool_result — Update the current tool segment with result, success, error. Check for __frontendAction.
After tool_result, the next text event creates a new text segment (the AI is now responding after reviewing the tool result).

Render the message bubble by mapping over the segments array in order, rendering each text segment as markdown and each tool segment as a collapsible tool card.

Parsing SSE Events (Frontend Implementation)

Use the fetch API with a streaming reader. SSE frames can arrive split across chunks, so buffer partial lines:

async function streamChat(mcpBffUrl, headers, message, conversationId, onEvent) {
  const response = await fetch(`${mcpBffUrl}/api/chat/stream`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ message, conversationId }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const parts = buffer.split('\n\n');
    buffer = parts.pop(); // keep incomplete frame in buffer

    for (const part of parts) {
      let eventType = 'message';
      let dataStr = '';

      for (const line of part.split('\n')) {
        if (line.startsWith('event: ')) {
          eventType = line.slice(7).trim();
        } else if (line.startsWith('data: ')) {
          dataStr += line.slice(6);
        }
      }

      if (dataStr) {
        try {
          const data = JSON.parse(dataStr);
          onEvent(eventType, data);
        } catch (e) {
          console.warn('Failed to parse SSE data:', dataStr);
        }
      }
    }
  }
}

Building the Segments Array (React Example)

// segments: Array<{ type: 'text', content: string } | { type: 'tool', tool, args?, result?, success?, error?, status }>
let segments = [];

streamChat(mcpBffUrl, headers, userMessage, conversationId, (event, data) => {
  switch (event) {
    case 'start':
      conversationId = data.conversationId;
      segments = [];
      break;

    case 'text': {
      const last = segments[segments.length - 1];
      if (last && last.type === 'text') {
        last.content += data.content;        // append to current text segment
      } else {
        segments.push({ type: 'text', content: data.content }); // new text segment
      }
      rerenderBubble(segments);
      break;
    }

    case 'tool_start':
      // push a new tool segment — this "cuts" the text flow
      segments.push({ type: 'tool', tool: data.tool, status: 'running' });
      rerenderBubble(segments);
      break;

    case 'tool_executing': {
      const toolSeg = findLastToolSegment(segments, data.tool);
      if (toolSeg) toolSeg.args = data.args;
      rerenderBubble(segments);
      break;
    }

    case 'tool_result': {
      const toolSeg = findLastToolSegment(segments, data.tool);
      if (toolSeg) {
        toolSeg.status = data.success ? 'complete' : 'error';
        toolSeg.result = data.result;
        toolSeg.error = data.error;
        toolSeg.success = data.success;
        // Check for frontend action (QR code, data view, payment, secret)
        toolSeg.frontendAction = extractFrontendAction(data.result);
      }
      rerenderBubble(segments);
      break;
    }

    case 'error':
      segments.push({ type: 'text', content: `**Error:** ${data.message}` });
      rerenderBubble(segments);
      break;

    case 'done':
      // Store final metadata (processingTime, aliasMapSummary) for the message
      finalizeMessage(segments, data);
      break;
  }
});

function findLastToolSegment(segments, toolName) {
  for (let i = segments.length - 1; i >= 0; i--) {
    if (segments[i].type === 'tool' && segments[i].tool === toolName) return segments[i];
  }
  return null;
}

Rendering the Message Bubble

Render each segment in order inside a single assistant message bubble:

function AssistantMessageBubble({ segments }) {
  return (
    <div className="assistant-bubble">
      {segments.map((segment, i) => {
        if (segment.type === 'text') {
          return <MarkdownRenderer key={i} content={segment.content} />;
        }
        if (segment.type === 'tool') {
          if (segment.frontendAction) {
            return <ActionCard key={i} action={segment.frontendAction} />;
          }
          return <ToolCard key={i} segment={segment} />;
        }
        return null;
      })}
    </div>
  );
}

function ToolCard({ segment }) {
  const isRunning = segment.status === 'running';
  const isError = segment.status === 'error';

  return (
    <div className={`tool-card ${segment.status}`}>
      <div className="tool-header">
        {isRunning && <Spinner size="sm" />}
        <span className="tool-name">{segment.tool}</span>
        {!isRunning && (isError ? <ErrorIcon /> : <CheckIcon />)}
      </div>
      {segment.args && (
        <CollapsibleSection label="Arguments">
          <pre>{JSON.stringify(segment.args, null, 2)}</pre>
        </CollapsibleSection>
      )}
      {segment.result && (
        <CollapsibleSection label="Result" defaultCollapsed>
          <pre>{JSON.stringify(segment.result, null, 2)}</pre>
        </CollapsibleSection>
      )}
      {segment.error && <div className="tool-error">{segment.error}</div>}
    </div>
  );
}

The tool card should be compact by default (just tool name + status icon) with collapsible sections for args and result, so it doesn’t dominate the reading flow. While a tool is running (status: 'running'), show a spinner. When complete, show a check or error icon.

Handling `__frontendAction` in Tool Results

When the AI calls certain tools (e.g., QR code, data view, payment, secret reveal), the tool result contains a __frontendAction object. This signals the frontend to render a special UI component inline in the bubble at the tool segment’s position instead of the default collapsible ToolCard. This is already handled in the segments code above — when segment.frontendAction is present, render an ActionCard instead of a ToolCard.

The extractFrontendAction helper unwraps the action from various MCP response formats:

function extractFrontendAction(result) {
  if (!result) return null;
  if (result.__frontendAction) return result.__frontendAction;
  
  // Unwrap MCP wrapper format: result → result.result → content[].text → JSON
  let data = result;
  if (result?.result?.content) data = result.result;
  
  if (data?.content && Array.isArray(data.content)) {
    const textContent = data.content.find(c => c.type === 'text');
    if (textContent?.text) {
      try {
        const parsed = JSON.parse(textContent.text);
        if (parsed?.__frontendAction) return parsed.__frontendAction;
      } catch { /* not JSON */ }
    }
  }
  return null;
}

Frontend Action Types

Action Type	Component	Description
`qrcode`	`QrCodeActionCard`	Renders any string value as a QR code card
`dataView`	`DataViewActionCard`	Fetches a Business API route and renders a grid or gallery
`payment`	`PaymentActionCard`	“Pay Now” button that opens Stripe checkout modal

QR Code Action (`type: "qrcode"`)

Triggered by the showQrCode MCP tool. Renders a QR code card from any string value.

{
  "__frontendAction": {
    "type": "qrcode",
    "value": "https://example.com/invite/ABC123",
    "title": "Invite Link",
    "subtitle": "Scan to open"
  }
}

Data View Action (`type: "dataView"`)

Triggered by showBusinessApiListInFrontEnd or showBusinessApiGalleryInFrontEnd. Frontend calls the provided Business API route using the user’s bearer token, then renders:

viewType: "grid" as tabular rows/columns
viewType: "gallery" as image-first cards

{
  "__frontendAction": {
    "type": "dataView",
    "viewType": "grid",
    "title": "Recent Orders",
    "serviceName": "commerce",
    "apiName": "listOrders",
    "routePath": "/v1/listorders",
    "httpMethod": "GET",
    "queryParams": { "pageNo": 1, "pageRowCount": 10 },
    "columns": [
      { "field": "id", "label": "Order ID" },
      { "field": "orderAmount", "label": "Amount", "format": "currency" }
    ]
  }
}

Payment Action (`type: "payment"`)

Triggered by the initiatePayment MCP tool. Renders a payment card with amount and a “Pay Now” button.

{
  "__frontendAction": {
    "type": "payment",
    "orderId": "uuid",
    "orderType": "order",
    "serviceName": "commerce",
    "amount": 99.99,
    "currency": "USD",
    "description": "Order #abc123"
  }
}

Conversation Management

// List user's conversations
GET /api/chat/conversations

// Get conversation history
GET /api/chat/conversations/:conversationId

// Delete a conversation
DELETE /api/chat/conversations/:conversationId

MCP Tool Discovery & Direct Invocation

The MCP BFF exposes endpoints for discovering and directly calling MCP tools (useful for debugging or building custom UIs).

GET /api/tools — List All Tools

const response = await fetch(`${mcpBffUrl}/api/tools`, { headers });
const { tools, count } = await response.json();
// tools: [{ name, description, inputSchema, service }, ...]

GET /api/tools/service/:serviceName — List Service Tools

const response = await fetch(`${mcpBffUrl}/api/tools/service/commerce`, { headers });
const { tools } = await response.json();

POST /api/tools/call — Call a Tool Directly

const response = await fetch(`${mcpBffUrl}/api/tools/call`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    toolName: "listProducts",
    args: { page: 1, limit: 10 },
  }),
});
const result = await response.json();

GET /api/tools/status — Connection Status

const status = await fetch(`${mcpBffUrl}/api/tools/status`, { headers });
// Returns health of each MCP service connection

POST /api/tools/refresh — Reconnect Services

await fetch(`${mcpBffUrl}/api/tools/refresh`, { method: 'POST', headers });
// Reconnects to all MCP services and refreshes the tool registry

Elasticsearch API

The MCP BFF provides direct access to Elasticsearch for searching, filtering, and aggregating data across all project indices.

All Elasticsearch endpoints are under /api/elastic.

GET /api/elastic/allIndices — List Project Indices

Returns all Elasticsearch indices belonging to this project (prefixed with airbnb3_).

const indices = await fetch(`${mcpBffUrl}/api/elastic/allIndices`, { headers });
// ["airbnb3_products", "airbnb3_orders", ...]

POST /api/elastic/:indexName/rawsearch — Raw Elasticsearch Query

Execute a raw Elasticsearch query on a specific index.

const response = await fetch(`${mcpBffUrl}/api/elastic/products/rawsearch`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    query: {
      bool: {
        must: [
          { match: { status: "active" } },
          { range: { price: { gte: 10, lte: 100 } } }
        ]
      }
    },
    size: 20,
    from: 0,
    sort: [{ createdAt: "desc" }]
  }),
});
const { total, hits, aggregations, took } = await response.json();
// hits: [{ _id, _index, _score, _source: { ...document... } }, ...]

Note: The index name is automatically prefixed with airbnb3_ if not already prefixed.

POST /api/elastic/:indexName/search — Simplified Search

A higher-level search API with built-in support for filters, sorting, and pagination.

const response = await fetch(`${mcpBffUrl}/api/elastic/products/search`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    search: "wireless headphones",           // Full-text search
    filters: { status: "active" },           // Field filters
    sort: { field: "createdAt", order: "desc" },
    page: 1,
    limit: 25,
  }),
});

POST /api/elastic/:indexName/aggregate — Aggregations

Run aggregation queries for analytics and dashboards.

const response = await fetch(`${mcpBffUrl}/api/elastic/orders/aggregate`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    aggs: {
      status_counts: { terms: { field: "status.keyword" } },
      total_revenue: { sum: { field: "amount" } },
      monthly_orders: {
        date_histogram: { field: "createdAt", calendar_interval: "month" }
      }
    },
    query: { range: { createdAt: { gte: "now-1y" } } }
  }),
});

GET /api/elastic/:indexName/mapping — Index Mapping

Get the field mapping for an index (useful for building dynamic filter UIs).

const mapping = await fetch(`${mcpBffUrl}/api/elastic/products/mapping`, { headers });

POST /api/elastic/:indexName/ai-search — AI-Assisted Search

Uses the configured AI model to convert a natural-language query into an Elasticsearch query.

const response = await fetch(`${mcpBffUrl}/api/elastic/orders/ai-search`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    query: "orders over $100 from last month that are still pending",
  }),
});
// Returns: { total, hits, generatedQuery, ... }

Log API

The MCP BFF provides log viewing endpoints for monitoring application behavior.

GET /api/logs — Query Logs

const response = await fetch(`${mcpBffUrl}/api/logs?page=1&limit=50&logType=2&service=commerce&search=payment`, {
  headers,
});

Query Parameters:

page — Page number (default: 1)
limit — Items per page (default: 50)
logType — 0=INFO, 1=WARNING, 2=ERROR
service — Filter by service name
search — Search in subject and message
from / to — Date range (ISO strings)
requestId — Filter by request ID

GET /api/logs/stream — Real-time Console Stream (SSE)

Streams real-time console output from all services via Server-Sent Events.

const eventSource = new EventSource(`${mcpBffUrl}/api/logs/stream?services=commerce,auth`, {
  headers: { 'Authorization': `Bearer ${accessToken}` },
});

eventSource.addEventListener('log', (event) => {
  const logEntry = JSON.parse(event.data);
  // { service, timestamp, level, message, ... }
});

Available Services

The MCP BFF connects to the following backend services:

Service	Description
`auth`	Authentication, user management, sessions
`messaging`	Enables secure in-app messaging between guests and hosts. Handles threads, messages (with text/media/system types), abuse flagging, and admin moderation for resolution…
`propertyCatalog`	Service for management of property listings, calendars, amenities, and localization for a short-term rental marketplace. Hosts can manage listings, availability, multi-language descriptions, policies, pricing, and attributes, served for global search and discovery…
`bookingManagement`	Orchestrates booking, payment, calendar, changewsand dispute flows for Airbnb-style short-term rental marketplace…test Handles reservations, approval, Stripe payments, iCal sync, payment records, and the dispute/refund lifecycle with host/guest/admin visibility.
`reviewSystem`	Handles double-blind, moderated reviews and rating aggregation for stays. Allows guests/hosts to review each other and listings, supports moderation, and exposes aggregate stats for listings/profiles…
`platformAdmin`	Administrative and compliance management backend for moderation, audit, dispute, financial oversight, localization, and GDPR in the Airbnb-style rental platform.
`agentHub`	AI Agent Hub

Each service exposes MCP tools that the AI can call through the BFF. Use GET /api/tools to discover all available tools at runtime, or GET /api/tools/service/:serviceName to list tools for a specific service.

MCP as Internal API Gateway

The MCP-BFF service can also be used by the frontend as an internal API gateway for tool-based interactions. This is separate from external AI tool connections — it is meant for frontend code that needs to call backend tools programmatically.

Direct Tool Calls (REST)

Use the REST tool invocation endpoints for programmatic access from frontend code:

// List all available tools
const tools = await fetch(`${mcpBffUrl}/api/tools`, { headers });

// Call a specific tool directly
const result = await fetch(`${mcpBffUrl}/api/tools/call`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    toolName: 'listProducts',
    args: { page: 1, limit: 10 },
  }),
});

AI-Orchestrated Calls (Chat API)

For AI-driven interactions, use the chat streaming API documented above (POST /api/chat/stream). The AI model decides which tools to call based on the user’s message.

Both approaches use the user’s JWT access token for authentication — the MCP-BFF forwards it to the correct backend service.

MCP Connection Info for Profile Page

The user’s profile page should include an informational section explaining how to connect external AI tools (Cursor, Claude Desktop, Lovable, Windsurf, etc.) to this application’s backend via MCP.

What to Display

The MCP-BFF exposes a unified MCP endpoint that aggregates tools from all backend services into a single connection point:

Environment	URL
Preview	`https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp`
Staging	`https://airbnb3-stage.mindbricks.co/mcpbff-api/mcp`
Production	`https://airbnb3.mindbricks.co/mcpbff-api/mcp`

For legacy MCP clients that don’t support StreamableHTTP, an SSE fallback is available at the same URL with /sse appended (e.g., .../mcpbff-api/mcp/sse).

Profile Page UI Requirements

Add an “MCP Connection” or “Connect External AI Tools” card/section to the profile page with:

Endpoint URL — Display the MCP endpoint URL for the current environment with a copy-to-clipboard button.

Ready-to-Copy Configs — Show copy-to-clipboard config snippets for popular tools:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "airbnb3": {
      "url": "https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer your_access_token_here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "airbnb3": {
      "url": "https://airbnb3.prw.mindbricks.com/mcpbff-api/mcp",
      "headers": {
        "Authorization": "Bearer your_access_token_here"
      }
    }
  }
}

Auth Note — Note that users should replace your_access_token_here with a valid JWT access token from the login API.
OAuth Note — Display a note that OAuth authentication is not currently supported for MCP connections.
Available Tools — Optionally show a summary of available tool categories (e.g., “CRUD operations for all data objects, custom business APIs, file operations”) or link to the tools discovery endpoint (GET /api/tools).

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 7 - Messaging Service

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides extensive instruction for the usage of messaging

Service Access

Messaging service management is handled through service specific base urls.

Messaging service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the messaging service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/messaging-api
Staging: https://airbnb3-stage.mindbricks.co/messaging-api
Production: https://airbnb3.mindbricks.co/messaging-api

Scope

Messaging Service Description

Enables secure in-app messaging between guests and hosts. Handles threads, messages (with text/media/system types), abuse flagging, and admin moderation for resolution…

Messaging service provides apis and business logic for following data objects in airbnb application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows.

messageThread Data Object: Thread/conversation between guest and host, optionally linked to a listing/reservation. Tracks participants, context, state, and stats.

messageReport Data Object: Report/in-app abuse complaint filed for a message by a user. Tracks status, admin handling, and resolution notes. Only visible to involved parties and admins.

message Data Object: Single message within a thread (text/media/system). Includes metadata for flagging/moderation. Linked to sender, thread, and content type.

API Structure

Object Structure of a Successful Response

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

MessageThread Data Object

Thread/conversation between guest and host, optionally linked to a listing/reservation. Tracks participants, context, state, and stats.

MessageThread Data Object Properties

MessageThread data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`messageCount`	Integer	false	Yes	No	-
`isOpen`	Boolean	false	Yes	No	-
`guestId`	ID	false	Yes	No	-
`lastMessageAt`	Date	false	Yes	No	-
`listingId`	ID	false	No	No	-
`hostId`	ID	false	Yes	No	-
`reservationId`	ID	false	No	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Relation Properties

guestId listingId hostId reservationId

Mindbricks supports relations between data objects, allowing you to define how objects are linked together. The relations may reference to a data object either in this service or in another service. Id the reference is remote, backend handles the relations through service communication or elastic search. These relations should be respected in the frontend so that instaead of showing the related objects id, the frontend should list human readable values from other data objects. If the relation points to another service, frontend should use the referenced service api in case it needs related data. The relation logic is montly handled in backend so the api responses feeds the frontend about the relational data. In mmost cases the api response will provide the relational data as well as the main one.

In frontend, please ensure that,

1- instaead of these relational ids you show the main human readable field of the related target data (like name), 2- if this data object needs a user input of these relational ids, you should provide a combobox with the list of possible records or (a searchbox) to select with the realted target data object main human readable field.

guestId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

listingId: ID Relation to listing.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

hostId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

reservationId: ID Relation to reservation.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

MessageReport Data Object

Report/in-app abuse complaint filed for a message by a user. Tracks status, admin handling, and resolution notes. Only visible to involved parties and admins.

MessageReport Data Object Properties

MessageReport data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`reportedBy`	ID	false	Yes	No	-
`reportReason`	String	false	Yes	No	-
`moderationStatus`	Enum	false	Yes	No	-
`messageId`	ID	false	Yes	No	-
`adminId`	ID	false	No	No	-
`reportedAt`	Date	false	Yes	No	-
`resolutionNotes`	Text	false	No	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

Enum properties are defined with a set of allowed values, ensuring that only valid options can be assigned to them. The enum options value will be stored as strings in the database, but when a data object is created an additional property with the same name plus an idx suffix will be created, which will hold the index of the selected enum option. You can use the {fieldName_idx} property to sort by the enum value or when your enum options represent a hiyerarchy of values. In the frontend input components, enum type properties should only accept values from an option component that lists the enum options.

moderationStatus: [pending, reviewed, closed]

Relation Properties

reportedBy messageId adminId

In frontend, please ensure that,

reportedBy: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

messageId: ID Relation to message.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

adminId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

Message Data Object

Single message within a thread (text/media/system). Includes metadata for flagging/moderation. Linked to sender, thread, and content type.

Message Data Object Properties

Message data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`threadId`	ID	false	Yes	No	-
`content`	Text	false	Yes	No	-
`senderId`	ID	false	Yes	No	-
`sentAt`	Date	false	Yes	No	-
`messageType`	Enum	false	Yes	No	-
`mediaUrl`	String	false	No	No	-
`isModerated`	Boolean	false	Yes	No	-
`isFlagged`	Boolean	false	Yes	No	-
`flaggedBy`	ID	false	No	No	-
`flagReason`	String	false	No	No	-
`isRead`	Boolean	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

messageType: [text, media, system]

Relation Properties

threadId senderId flaggedBy

In frontend, please ensure that,

threadId: ID Relation to messagethread.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

senderId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

flaggedBy: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

Default CRUD APIs

For each data object, the backend architect may designate default APIs for standard operations (create, update, delete, get, list). These are the APIs that frontend CRUD forms and AI agents should use for basic record management. If no default is explicitly set (isDefaultApi), the frontend generator auto-discovers the most general API for each operation.

MessageThread Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createMessageThread`	`/v1/messagethreads`	Auto
Update	`updateMessageThread`	`/v1/messagethreads/:messageThreadId`	Auto
Delete	`deleteMessageThread`	`/v1/messagethreads/:messageThreadId`	Auto
Get	`getMessageThread`	`/v1/messagethreads/:messageThreadId`	Auto
List	`listMessageThreads`	`/v1/messagethreads`	Auto

MessageReport Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createMessageReport`	`/v1/messagereports`	Auto
Update	`updateMessageReport`	`/v1/messagereports/:messageReportId`	Auto
Delete	none	-	Auto
Get	`getMessageReport`	`/v1/messagereports/:messageReportId`	Auto
List	`listMessageReports`	`/v1/messagereports`	Auto

Message Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createMessage`	`/v1/messages`	Auto
Update	`updateMessage`	`/v1/messages/:messageId`	Auto
Delete	`deleteMessage`	`/v1/messages/:messageId`	Auto
Get	`getMessage`	`/v1/messages/:messageId`	Auto
List	`getThreadMessages`	`/v1/threadmessages/:threadId`	Auto

When building CRUD forms for a data object, use the default create/update APIs listed above. The form fields should correspond to the API’s body parameters. For relation fields, render a dropdown loaded from the related object’s list API using the display label property.

API Reference

`Delete Message` API

Soft-delete (hide) a message. Sender or admin only. Message remains for logs/audit, only hidden for sender/recipient.

Rest Route

The deleteMessage API REST controller can be triggered via the following route:

/v1/messages/:messageId

Rest Request Parameters

The deleteMessage api has got 1 regular request parameter

Parameter	Type	Required	Population
messageId	ID	true	request.params?.[“messageId”]
messageId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/messages/:messageId

  axios({
    method: 'DELETE',
    url: `/v1/messages/${messageId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "message",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"message": {
		"id": "ID",
		"threadId": "ID",
		"content": "Text",
		"senderId": "ID",
		"sentAt": "Date",
		"messageType": "Enum",
		"messageType_idx": "Integer",
		"mediaUrl": "String",
		"isModerated": "Boolean",
		"isFlagged": "Boolean",
		"flaggedBy": "ID",
		"flagReason": "String",
		"isRead": "Boolean",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Create Messagethread` API

Create a new message thread between a guest and host (optionally for specific listing/reservation). Users must be sender or recipient. Prevent duplicate open threads on same context with composite index.

Rest Route

The createMessageThread API REST controller can be triggered via the following route:

/v1/messagethreads

Rest Request Parameters

The createMessageThread api has got 7 regular request parameters

Parameter	Type	Required	Population
messageCount	Integer	true	request.body?.[“messageCount”]
isOpen	Boolean	true	request.body?.[“isOpen”]
guestId	ID	true	request.body?.[“guestId”]
lastMessageAt	Date	true	request.body?.[“lastMessageAt”]
listingId	ID	false	request.body?.[“listingId”]
hostId	ID	true	request.body?.[“hostId”]
reservationId	ID	false	request.body?.[“reservationId”]
messageCount :
isOpen :
guestId :
lastMessageAt :
listingId :
hostId :
reservationId :

REST Request To access the api you can use the REST controller with the path POST /v1/messagethreads

  axios({
    method: 'POST',
    url: '/v1/messagethreads',
    data: {
            messageCount:"Integer",  
            isOpen:"Boolean",  
            guestId:"ID",  
            lastMessageAt:"Date",  
            listingId:"ID",  
            hostId:"ID",  
            reservationId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageThread",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"messageThread": {
		"id": "ID",
		"messageCount": "Integer",
		"isOpen": "Boolean",
		"guestId": "ID",
		"lastMessageAt": "Date",
		"listingId": "ID",
		"hostId": "ID",
		"reservationId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Message` API

Allows sender or admin to edit a message (rare; only content/flag fields allowed). Use-case: correct typo, retract flag. Not for full message overwrite.

Rest Route

The updateMessage API REST controller can be triggered via the following route:

/v1/messages/:messageId

Rest Request Parameters

The updateMessage api has got 8 regular request parameters

Parameter	Type	Required	Population
messageId	ID	true	request.params?.[“messageId”]
content	Text	false	request.body?.[“content”]
mediaUrl	String	false	request.body?.[“mediaUrl”]
isModerated	Boolean	false	request.body?.[“isModerated”]
isFlagged	Boolean	false	request.body?.[“isFlagged”]
flaggedBy	ID	false	request.body?.[“flaggedBy”]
flagReason	String	false	request.body?.[“flagReason”]
isRead	Boolean	false	request.body?.[“isRead”]
messageId : This id paremeter is used to select the required data object that will be updated
content :
mediaUrl :
isModerated :
isFlagged :
flaggedBy :
flagReason :
isRead :

REST Request To access the api you can use the REST controller with the path PATCH /v1/messages/:messageId

  axios({
    method: 'PATCH',
    url: `/v1/messages/${messageId}`,
    data: {
            content:"Text",  
            mediaUrl:"String",  
            isModerated:"Boolean",  
            isFlagged:"Boolean",  
            flaggedBy:"ID",  
            flagReason:"String",  
            isRead:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "message",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"message": {
		"id": "ID",
		"threadId": "ID",
		"content": "Text",
		"senderId": "ID",
		"sentAt": "Date",
		"messageType": "Enum",
		"messageType_idx": "Integer",
		"mediaUrl": "String",
		"isModerated": "Boolean",
		"isFlagged": "Boolean",
		"flaggedBy": "ID",
		"flagReason": "String",
		"isRead": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Messagethread` API

Update thread state (e.g. isOpen=false to close), only guest, host, or admin can update.

Rest Route

The updateMessageThread API REST controller can be triggered via the following route:

/v1/messagethreads/:messageThreadId

Rest Request Parameters

The updateMessageThread api has got 6 regular request parameters

Parameter	Type	Required	Population
messageThreadId	ID	true	request.params?.[“messageThreadId”]
messageCount	Integer	false	request.body?.[“messageCount”]
isOpen	Boolean	false	request.body?.[“isOpen”]
lastMessageAt	Date	false	request.body?.[“lastMessageAt”]
listingId	ID	false	request.body?.[“listingId”]
reservationId	ID	false	request.body?.[“reservationId”]
messageThreadId : This id paremeter is used to select the required data object that will be updated
messageCount :
isOpen :
lastMessageAt :
listingId :
reservationId :

REST Request To access the api you can use the REST controller with the path PATCH /v1/messagethreads/:messageThreadId

  axios({
    method: 'PATCH',
    url: `/v1/messagethreads/${messageThreadId}`,
    data: {
            messageCount:"Integer",  
            isOpen:"Boolean",  
            lastMessageAt:"Date",  
            listingId:"ID",  
            reservationId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageThread",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"messageThread": {
		"id": "ID",
		"messageCount": "Integer",
		"isOpen": "Boolean",
		"guestId": "ID",
		"lastMessageAt": "Date",
		"listingId": "ID",
		"hostId": "ID",
		"reservationId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Messagethread` API

Soft-delete (archive/close) a thread. Only allowed for guest/host or admin; marks isActive=false.

Rest Route

The deleteMessageThread API REST controller can be triggered via the following route:

/v1/messagethreads/:messageThreadId

Rest Request Parameters

The deleteMessageThread api has got 1 regular request parameter

Parameter	Type	Required	Population
messageThreadId	ID	true	request.params?.[“messageThreadId”]
messageThreadId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/messagethreads/:messageThreadId

  axios({
    method: 'DELETE',
    url: `/v1/messagethreads/${messageThreadId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageThread",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"messageThread": {
		"id": "ID",
		"messageCount": "Integer",
		"isOpen": "Boolean",
		"guestId": "ID",
		"lastMessageAt": "Date",
		"listingId": "ID",
		"hostId": "ID",
		"reservationId": "ID",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Create Message` API

Create/send a message to a thread (guest/host only, must be participant). Sets sentAt, and updates thread.lastMessageAt/messageCount atomically.

Rest Route

The createMessage API REST controller can be triggered via the following route:

/v1/messages

Rest Request Parameters

The createMessage api has got 10 regular request parameters

Parameter	Type	Required	Population
threadId	ID	true	request.body?.[“threadId”]
content	Text	true	request.body?.[“content”]
senderId	ID	true	request.body?.[“senderId”]
sentAt	Date	true	request.body?.[“sentAt”]
messageType	Enum	true	request.body?.[“messageType”]
mediaUrl	String	false	request.body?.[“mediaUrl”]
isModerated	Boolean	true	request.body?.[“isModerated”]
isFlagged	Boolean	true	request.body?.[“isFlagged”]
flaggedBy	ID	false	request.body?.[“flaggedBy”]
flagReason	String	false	request.body?.[“flagReason”]
threadId :
content :
senderId :
sentAt :
messageType :
mediaUrl :
isModerated :
isFlagged :
flaggedBy :
flagReason :

REST Request To access the api you can use the REST controller with the path POST /v1/messages

  axios({
    method: 'POST',
    url: '/v1/messages',
    data: {
            threadId:"ID",  
            content:"Text",  
            senderId:"ID",  
            sentAt:"Date",  
            messageType:"Enum",  
            mediaUrl:"String",  
            isModerated:"Boolean",  
            isFlagged:"Boolean",  
            flaggedBy:"ID",  
            flagReason:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "message",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"message": {
		"id": "ID",
		"threadId": "ID",
		"content": "Text",
		"senderId": "ID",
		"sentAt": "Date",
		"messageType": "Enum",
		"messageType_idx": "Integer",
		"mediaUrl": "String",
		"isModerated": "Boolean",
		"isFlagged": "Boolean",
		"flaggedBy": "ID",
		"flagReason": "String",
		"isRead": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Messagethread` API

Get a message thread with participant/context enrichment. Only guest, host, or admin may view.

Rest Route

The getMessageThread API REST controller can be triggered via the following route:

/v1/messagethreads/:messageThreadId

Rest Request Parameters

The getMessageThread api has got 1 regular request parameter

Parameter	Type	Required	Population
messageThreadId	ID	true	request.params?.[“messageThreadId”]
messageThreadId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/messagethreads/:messageThreadId

  axios({
    method: 'GET',
    url: `/v1/messagethreads/${messageThreadId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageThread",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"messageThread": {
		"id": "ID",
		"messageCount": "Integer",
		"isOpen": "Boolean",
		"guestId": "ID",
		"lastMessageAt": "Date",
		"listingId": "ID",
		"hostId": "ID",
		"reservationId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Message` API

Get a message (guest/host must be in thread, or admin). Enrich with sender info.

Rest Route

The getMessage API REST controller can be triggered via the following route:

/v1/messages/:messageId

Rest Request Parameters

The getMessage api has got 1 regular request parameter

Parameter	Type	Required	Population
messageId	ID	true	request.params?.[“messageId”]
messageId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/messages/:messageId

  axios({
    method: 'GET',
    url: `/v1/messages/${messageId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "message",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"message": {
		"id": "ID",
		"threadId": "ID",
		"content": "Text",
		"senderId": "ID",
		"sentAt": "Date",
		"messageType": "Enum",
		"messageType_idx": "Integer",
		"mediaUrl": "String",
		"isModerated": "Boolean",
		"isFlagged": "Boolean",
		"flaggedBy": "ID",
		"flagReason": "String",
		"isRead": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Messagethreads` API

List threads for user; only show where session user is guest or host, or admin role.

Rest Route

The listMessageThreads API REST controller can be triggered via the following route:

/v1/messagethreads

Rest Request Parameters The listMessageThreads api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/messagethreads

  axios({
    method: 'GET',
    url: '/v1/messagethreads',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageThreads",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"messageThreads": [
		{
			"id": "ID",
			"messageCount": "Integer",
			"isOpen": "Boolean",
			"guestId": "ID",
			"lastMessageAt": "Date",
			"listingId": "ID",
			"hostId": "ID",
			"reservationId": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"listingDets": [
				{
					"title": "String",
					"address": "String",
					"propertyType": "Enum",
					"propertyType_idx": "Integer",
					"location": "Object"
				},
				{},
				{}
			],
			"rezDets": [
				{
					"bookingStatus": "Enum",
					"bookingStatus_idx": "Integer",
					"checkOut": "Date",
					"checkIn": "Date"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Get Threadmessages` API

List messages in a thread (participants only, or admin). Sorted by sentAt ASC. Includes sender info for display.

Rest Route

The getThreadMessages API REST controller can be triggered via the following route:

/v1/threadmessages/:threadId

Rest Request Parameters

The getThreadMessages api has got 1 regular request parameter

Parameter	Type	Required	Population
threadId	ID	true	request.params?.[“threadId”]
threadId :

REST Request To access the api you can use the REST controller with the path GET /v1/threadmessages/:threadId

  axios({
    method: 'GET',
    url: `/v1/threadmessages/${threadId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messages",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"messages": [
		{
			"id": "ID",
			"threadId": "ID",
			"content": "Text",
			"senderId": "ID",
			"sentAt": "Date",
			"messageType": "Enum",
			"messageType_idx": "Integer",
			"mediaUrl": "String",
			"isModerated": "Boolean",
			"isFlagged": "Boolean",
			"flaggedBy": "ID",
			"flagReason": "String",
			"isRead": "Boolean",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": [],
	"thread": {
		"listingId": "ID"
	},
	"listing": {},
	"amenities": {}
}

`Gotthread Messages` API

Rest Route

The gotthreadMessages API REST controller can be triggered via the following route:

/v1/gotthreadmessages/:threadId

Rest Request Parameters

The gotthreadMessages api has got 1 regular request parameter

Parameter	Type	Required	Population
threadId	ID	true	request.params?.[“threadId”]
threadId : undefined. The parameter is used to query data.

REST Request To access the api you can use the REST controller with the path GET /v1/gotthreadmessages/:threadId

  axios({
    method: 'GET',
    url: `/v1/gotthreadmessages/${threadId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messages",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"messages": [
		{
			"id": "ID",
			"threadId": "ID",
			"content": "Text",
			"senderId": "ID",
			"sentAt": "Date",
			"messageType": "Enum",
			"messageType_idx": "Integer",
			"mediaUrl": "String",
			"isModerated": "Boolean",
			"isFlagged": "Boolean",
			"flaggedBy": "ID",
			"flagReason": "String",
			"isRead": "Boolean",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`List Messagereports` API

List message reports. Reporter, admin, or (involved) sender may see. Admin sees all, others see those they filed or are involved in. Intended for moderation/admin panel and user reporting history.

Rest Route

The listMessageReports API REST controller can be triggered via the following route:

/v1/messagereports

Rest Request Parameters The listMessageReports api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/messagereports

  axios({
    method: 'GET',
    url: '/v1/messagereports',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageReports",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"messageReports": [
		{
			"id": "ID",
			"reportedBy": "ID",
			"reportReason": "String",
			"moderationStatus": "Enum",
			"moderationStatus_idx": "Integer",
			"messageId": "ID",
			"adminId": "ID",
			"reportedAt": "Date",
			"resolutionNotes": "Text",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Messagereport` API

User files report on a message for abuse/moderation. Links to message & reporter. Sets status=pending, visible to reporter, admin, and message sender (for defense/appeal).

Rest Route

The createMessageReport API REST controller can be triggered via the following route:

/v1/messagereports

Rest Request Parameters

The createMessageReport api has got 7 regular request parameters

Parameter	Type	Required	Population
reportedBy	ID	true	request.body?.[“reportedBy”]
reportReason	String	true	request.body?.[“reportReason”]
moderationStatus	Enum	true	request.body?.[“moderationStatus”]
messageId	ID	true	request.body?.[“messageId”]
adminId	ID	false	request.body?.[“adminId”]
reportedAt	Date	true	request.body?.[“reportedAt”]
resolutionNotes	Text	false	request.body?.[“resolutionNotes”]
reportedBy :
reportReason :
moderationStatus :
messageId :
adminId :
reportedAt :
resolutionNotes :

REST Request To access the api you can use the REST controller with the path POST /v1/messagereports

  axios({
    method: 'POST',
    url: '/v1/messagereports',
    data: {
            reportedBy:"ID",  
            reportReason:"String",  
            moderationStatus:"Enum",  
            messageId:"ID",  
            adminId:"ID",  
            reportedAt:"Date",  
            resolutionNotes:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageReport",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"messageReport": {
		"id": "ID",
		"reportedBy": "ID",
		"reportReason": "String",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"messageId": "ID",
		"adminId": "ID",
		"reportedAt": "Date",
		"resolutionNotes": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Messagereport` API

Admin moderator updates report: assign adminId, update status, add resolution notes. Only admin role allowed.

Rest Route

The updateMessageReport API REST controller can be triggered via the following route:

/v1/messagereports/:messageReportId

Rest Request Parameters

The updateMessageReport api has got 4 regular request parameters

Parameter	Type	Required	Population
messageReportId	ID	true	request.params?.[“messageReportId”]
moderationStatus	Enum	false	request.body?.[“moderationStatus”]
adminId	ID	false	request.body?.[“adminId”]
resolutionNotes	Text	false	request.body?.[“resolutionNotes”]
messageReportId : This id paremeter is used to select the required data object that will be updated
moderationStatus :
adminId :
resolutionNotes :

REST Request To access the api you can use the REST controller with the path PATCH /v1/messagereports/:messageReportId

  axios({
    method: 'PATCH',
    url: `/v1/messagereports/${messageReportId}`,
    data: {
            moderationStatus:"Enum",  
            adminId:"ID",  
            resolutionNotes:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageReport",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"messageReport": {
		"id": "ID",
		"reportedBy": "ID",
		"reportReason": "String",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"messageId": "ID",
		"adminId": "ID",
		"reportedAt": "Date",
		"resolutionNotes": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Messagereport` API

Get a message report. Reporter, admin, or message sender may view report. Includes message, admin, and involved user info via selectJoins for moderation view.

Rest Route

The getMessageReport API REST controller can be triggered via the following route:

/v1/messagereports/:messageReportId

Rest Request Parameters

The getMessageReport api has got 1 regular request parameter

Parameter	Type	Required	Population
messageReportId	ID	true	request.params?.[“messageReportId”]
messageReportId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/messagereports/:messageReportId

  axios({
    method: 'GET',
    url: `/v1/messagereports/${messageReportId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "messageReport",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"messageReport": {
		"id": "ID",
		"reportedBy": "ID",
		"reportReason": "String",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"messageId": "ID",
		"adminId": "ID",
		"reportedAt": "Date",
		"resolutionNotes": "Text",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 8 - PropertyCatalog Service

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides extensive instruction for the usage of propertyCatalog

Service Access

PropertyCatalog service management is handled through service specific base urls.

PropertyCatalog service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the propertyCatalog service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/propertycatalog-api
Staging: https://airbnb3-stage.mindbricks.co/propertycatalog-api
Production: https://airbnb3.mindbricks.co/propertycatalog-api

Scope

PropertyCatalog Service Description

Service for management of property listings, calendars, amenities, and localization for a short-term rental marketplace. Hosts can manage listings, availability, multi-language descriptions, policies, pricing, and attributes, served for global search and discovery…

PropertyCatalog service provides apis and business logic for following data objects in airbnb application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows.

listingCalendar Data Object: Represents daily availability, pricing, and reservation state for a listing (i.e., a property calendar entry).

listingAmenity Data Object: Dictionary of possible amenities (wifi, pool, etc.) for hosts to reference in their listings.

listing Data Object: Represents a property or space offered for short-term rental by a host. Includes host ref, core attributes, pricing, location, seasonal pricing, media, and booking/policy properties…

listingLocaleText Data Object: Localized title & description texts for a property listing, per language.

API Structure

Object Structure of a Successful Response

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

ListingCalendar Data Object

Represents daily availability, pricing, and reservation state for a listing (i.e., a property calendar entry).

ListingCalendar Data Object Properties

ListingCalendar data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`priceOverride`	Double	false	No	No	-
`date`	Date	false	Yes	No	-
`minStay`	Integer	false	No	No	-
`listingId`	ID	false	Yes	No	-
`bookedBy`	ID	false	No	No	-
`iCalUrl`	String	false	No	No	-
`externalCalendarIds`	String	true	No	No	-
`isAvailable`	Boolean	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Array Properties

externalCalendarIds

Array properties can hold multiple values. Array properties should be respected according to their multiple structure in the frontend in any user input for them. Please use multiple input components for the array proeprties when needed.

Relation Properties

listingId bookedBy

In frontend, please ensure that,

listingId: ID Relation to listing.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

bookedBy: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

Filter Properties

date listingId

Filter properties are used to define parameters that can be used in query filters, allowing for dynamic data retrieval based on user input or predefined criteria. These properties are automatically mapped as API parameters in the listing API’s.

date: Date has a filter named date
listingId: ID has a filter named listingId

ListingAmenity Data Object

Dictionary of possible amenities (wifi, pool, etc.) for hosts to reference in their listings.

ListingAmenity Data Object Properties

ListingAmenity data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`iconUrl`	String	false	No	No	-
`name`	String	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Filter Properties

name

name: String has a filter named name

Listing Data Object

Represents a property or space offered for short-term rental by a host. Includes host ref, core attributes, pricing, location, seasonal pricing, media, and booking/policy properties…

Listing Data Object Properties

Listing data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`title`	String	false	Yes	No	-
`amenityIds`	ID	true	No	No	-
`hostId`	ID	false	Yes	No	-
`mainPhoto`	String	false	No	No	-
`photos`	String	true	No	No	-
`address`	String	false	Yes	No	-
`pricePerNight`	Double	false	Yes	No	-
`description`	Text	false	Yes	No	-
`propertyType`	Enum	false	Yes	No	-
`location`	Object	false	Yes	No	-
`maxStay`	Integer	false	No	No	-
`minStay`	Integer	false	No	No	-
`currency`	String	false	Yes	No	-
`seasonalPricing`	Object	true	No	No	-
`approvalType`	Enum	false	Yes	No	-
`bookingPolicies`	Object	false	No	No	-
`cancellationPolicy`	Object	false	No	No	-
`languagesSupported`	String	true	No	No	-
`houseRules`	Text	false	No	No	-
`isPublished`	Boolean	false	Yes	No	-
`cityTaxPercent`	Double	false	No	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Array Properties

amenityIds photos seasonalPricing languagesSupported

Enum Properties

propertyType: [apartment, house, villa, room, condo, loft, studio, other]
approvalType: [instant, manual]

Relation Properties

amenityIds hostId

In frontend, please ensure that,

amenityIds: ID Relation to listingamenity.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

hostId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Filter Properties

title hostId address pricePerNight propertyType currency isPublished

title: String has a filter named title
hostId: ID has a filter named hostId
address: String has a filter named address
pricePerNight: Double has a filter named pricePerNight
propertyType: Enum has a filter named propertyType
currency: String has a filter named currency
isPublished: Boolean has a filter named isPublished

ListingLocaleText Data Object

Localized title & description texts for a property listing, per language.

ListingLocaleText Data Object Properties

ListingLocaleText data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`localizedDescription`	Text	false	Yes	No	-
`localizedTitle`	String	false	Yes	No	-
`listingId`	ID	false	Yes	No	-
`languageCode`	String	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Relation Properties

listingId

In frontend, please ensure that,

listingId: ID Relation to listing.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Filter Properties

listingId languageCode

listingId: ID has a filter named listingId
languageCode: String has a filter named languageCode

Default CRUD APIs

ListingCalendar Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createListingCalendar`	`/v1/listingcalendars`	Auto
Update	`updateListingCalendar`	`/v1/listingcalendars/:listingCalendarId`	Auto
Delete	`deleteListingCalendar`	`/v1/listingcalendars/:listingCalendarId`	Auto
Get	`getListingCalendar`	`/v1/listingcalendars/:listingCalendarId`	Auto
List	`listListingCalendars`	`/v1/listingcalendars`	Auto

ListingAmenity Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createListingAmenity`	`/v1/listingamenities`	Auto
Update	`updateListingAmenity`	`/v1/listingamenities/:listingAmenityId`	Auto
Delete	`deleteListingAmenity`	`/v1/listingamenities/:listingAmenityId`	Auto
Get	`getListingAmenity`	`/v1/listingamenities/:listingAmenityId`	Auto
List	`listListingAmenities`	`/v1/listingamenities`	Auto

Listing Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createListing`	`/v1/listings`	Auto
Update	`updateListing`	`/v1/listings/:listingId`	Auto
Delete	`deleteListing`	`/v1/listings/:listingId`	Auto
Get	`getListing`	`/v1/listings/:listingId`	Auto
List	`listListings`	`/v1/listings`	Auto

ListingLocaleText Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createListingLocaleText`	`/v1/listinglocaletexts`	Auto
Update	`updateListingLocaleText`	`/v1/listinglocaletexts/:listingLocaleTextId`	Auto
Delete	`deleteListingLocaleText`	`/v1/listinglocaletexts/:listingLocaleTextId`	Auto
Get	`getListingLocaleText`	`/v1/listinglocaletexts/:listingLocaleTextId`	Auto
List	`listListingLocaleTexts`	`/v1/listinglocaletexts`	Auto

API Reference

`Update Listing` API

Update an existing listing owned by the host or admin.

Rest Route

The updateListing API REST controller can be triggered via the following route:

/v1/listings/:listingId

Rest Request Parameters

The updateListing api has got 21 regular request parameters

Parameter	Type	Required	Population
listingId	ID	true	request.params?.[“listingId”]
title	String	false	request.body?.[“title”]
amenityIds	ID	false	request.body?.[“amenityIds”]
mainPhoto	String	false	request.body?.[“mainPhoto”]
photos	String	false	request.body?.[“photos”]
address	String	false	request.body?.[“address”]
pricePerNight	Double	false	request.body?.[“pricePerNight”]
description	Text	false	request.body?.[“description”]
propertyType	Enum	false	request.body?.[“propertyType”]
location	Object	false	request.body?.[“location”]
maxStay	Integer	false	request.body?.[“maxStay”]
minStay	Integer	false	request.body?.[“minStay”]
currency	String	false	request.body?.[“currency”]
seasonalPricing	Object	false	request.body?.[“seasonalPricing”]
approvalType	Enum	false	request.body?.[“approvalType”]
bookingPolicies	Object	false	request.body?.[“bookingPolicies”]
cancellationPolicy	Object	false	request.body?.[“cancellationPolicy”]
languagesSupported	String	false	request.body?.[“languagesSupported”]
houseRules	Text	false	request.body?.[“houseRules”]
isPublished	Boolean	false	request.body?.[“isPublished”]
cityTaxPercent	Double	false	request.body?.[“cityTaxPercent”]
listingId : This id paremeter is used to select the required data object that will be updated
title :
amenityIds :
mainPhoto :
photos :
address :
pricePerNight :
description :
propertyType :
location :
maxStay :
minStay :
currency :
seasonalPricing :
approvalType :
bookingPolicies :
cancellationPolicy :
languagesSupported :
houseRules :
isPublished :
cityTaxPercent :

REST Request To access the api you can use the REST controller with the path PATCH /v1/listings/:listingId

  axios({
    method: 'PATCH',
    url: `/v1/listings/${listingId}`,
    data: {
            title:"String",  
            amenityIds:"ID",  
            mainPhoto:"String",  
            photos:"String",  
            address:"String",  
            pricePerNight:"Double",  
            description:"Text",  
            propertyType:"Enum",  
            location:"Object",  
            maxStay:"Integer",  
            minStay:"Integer",  
            currency:"String",  
            seasonalPricing:"Object",  
            approvalType:"Enum",  
            bookingPolicies:"Object",  
            cancellationPolicy:"Object",  
            languagesSupported:"String",  
            houseRules:"Text",  
            isPublished:"Boolean",  
            cityTaxPercent:"Double",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listing",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"listing": {
		"id": "ID",
		"title": "String",
		"amenityIds": "ID",
		"hostId": "ID",
		"mainPhoto": "String",
		"photos": "String",
		"address": "String",
		"pricePerNight": "Double",
		"description": "Text",
		"propertyType": "Enum",
		"propertyType_idx": "Integer",
		"location": "Object",
		"maxStay": "Integer",
		"minStay": "Integer",
		"currency": "String",
		"seasonalPricing": "Object",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingPolicies": "Object",
		"cancellationPolicy": "Object",
		"languagesSupported": "String",
		"houseRules": "Text",
		"isPublished": "Boolean",
		"cityTaxPercent": "Double",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Create Listing` API

Create a new rental property listing. Host must be the owner (session user).

Rest Route

The createListing API REST controller can be triggered via the following route:

/v1/listings

Rest Request Parameters

The createListing api has got 20 regular request parameters

Parameter	Type	Required	Population
title	String	true	request.body?.[“title”]
amenityIds	ID	false	request.body?.[“amenityIds”]
mainPhoto	String	false	request.body?.[“mainPhoto”]
photos	String	false	request.body?.[“photos”]
address	String	true	request.body?.[“address”]
pricePerNight	Double	true	request.body?.[“pricePerNight”]
description	Text	true	request.body?.[“description”]
propertyType	Enum	true	request.body?.[“propertyType”]
location	Object	true	request.body?.[“location”]
maxStay	Integer	false	request.body?.[“maxStay”]
minStay	Integer	false	request.body?.[“minStay”]
currency	String	true	request.body?.[“currency”]
seasonalPricing	Object	false	request.body?.[“seasonalPricing”]
approvalType	Enum	true	request.body?.[“approvalType”]
bookingPolicies	Object	false	request.body?.[“bookingPolicies”]
cancellationPolicy	Object	false	request.body?.[“cancellationPolicy”]
languagesSupported	String	false	request.body?.[“languagesSupported”]
houseRules	Text	false	request.body?.[“houseRules”]
isPublished	Boolean	true	request.body?.[“isPublished”]
cityTaxPercent	Double	false	request.body?.[“cityTaxPercent”]
title :
amenityIds :
mainPhoto :
photos :
address :
pricePerNight :
description :
propertyType :
location :
maxStay :
minStay :
currency :
seasonalPricing :
approvalType :
bookingPolicies :
cancellationPolicy :
languagesSupported :
houseRules :
isPublished :
cityTaxPercent :

REST Request To access the api you can use the REST controller with the path POST /v1/listings

  axios({
    method: 'POST',
    url: '/v1/listings',
    data: {
            title:"String",  
            amenityIds:"ID",  
            mainPhoto:"String",  
            photos:"String",  
            address:"String",  
            pricePerNight:"Double",  
            description:"Text",  
            propertyType:"Enum",  
            location:"Object",  
            maxStay:"Integer",  
            minStay:"Integer",  
            currency:"String",  
            seasonalPricing:"Object",  
            approvalType:"Enum",  
            bookingPolicies:"Object",  
            cancellationPolicy:"Object",  
            languagesSupported:"String",  
            houseRules:"Text",  
            isPublished:"Boolean",  
            cityTaxPercent:"Double",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listing",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"listing": {
		"id": "ID",
		"title": "String",
		"amenityIds": "ID",
		"hostId": "ID",
		"mainPhoto": "String",
		"photos": "String",
		"address": "String",
		"pricePerNight": "Double",
		"description": "Text",
		"propertyType": "Enum",
		"propertyType_idx": "Integer",
		"location": "Object",
		"maxStay": "Integer",
		"minStay": "Integer",
		"currency": "String",
		"seasonalPricing": "Object",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingPolicies": "Object",
		"cancellationPolicy": "Object",
		"languagesSupported": "String",
		"houseRules": "Text",
		"isPublished": "Boolean",
		"cityTaxPercent": "Double",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Listing` API

Delete (soft-delete) a property listing. Host must be owner or admin.

Rest Route

The deleteListing API REST controller can be triggered via the following route:

/v1/listings/:listingId

Rest Request Parameters

The deleteListing api has got 1 regular request parameter

Parameter	Type	Required	Population
listingId	ID	true	request.params?.[“listingId”]
listingId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/listings/:listingId

  axios({
    method: 'DELETE',
    url: `/v1/listings/${listingId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listing",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"listing": {
		"id": "ID",
		"title": "String",
		"amenityIds": "ID",
		"hostId": "ID",
		"mainPhoto": "String",
		"photos": "String",
		"address": "String",
		"pricePerNight": "Double",
		"description": "Text",
		"propertyType": "Enum",
		"propertyType_idx": "Integer",
		"location": "Object",
		"maxStay": "Integer",
		"minStay": "Integer",
		"currency": "String",
		"seasonalPricing": "Object",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingPolicies": "Object",
		"cancellationPolicy": "Object",
		"languagesSupported": "String",
		"houseRules": "Text",
		"isPublished": "Boolean",
		"cityTaxPercent": "Double",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Listings` API

List all property listings (optionally filtered). Includes amenities and locales as joins for display search cards.

Rest Route

The listListings API REST controller can be triggered via the following route:

/v1/listings

Rest Request Parameters

Filter Parameters

The listListings api supports 7 optional filter parameters for filtering list results:

title (String): Filter by title

Single (partial match, case-insensitive): ?title=<value>
Multiple: ?title=<value1>&title=<value2>
Null: ?title=null

hostId (ID): Filter by hostId

Single: ?hostId=<value>
Multiple: ?hostId=<value1>&hostId=<value2>
Null: ?hostId=null

address (String): Filter by address

Single (partial match, case-insensitive): ?address=<value>
Multiple: ?address=<value1>&address=<value2>
Null: ?address=null

pricePerNight (Double): Filter by pricePerNight

Single: ?pricePerNight=<value>
Multiple: ?pricePerNight=<value1>&pricePerNight=<value2>
Range: ?pricePerNight=$lt-<value>, $lte-, $gt-, $gte-, $btw-<min>-<max>
Null: ?pricePerNight=null

propertyType (Enum): Filter by propertyType

Single: ?propertyType=<value> (case-insensitive)
Multiple: ?propertyType=<value1>&propertyType=<value2>
Null: ?propertyType=null

currency (String): Filter by currency

Single (partial match, case-insensitive): ?currency=<value>
Multiple: ?currency=<value1>&currency=<value2>
Null: ?currency=null

isPublished (Boolean): Filter by isPublished

True: ?isPublished=true
False: ?isPublished=false
Null: ?isPublished=null

REST Request To access the api you can use the REST controller with the path GET /v1/listings

  axios({
    method: 'GET',
    url: '/v1/listings',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // title: '<value>' // Filter by title
        // hostId: '<value>' // Filter by hostId
        // address: '<value>' // Filter by address
        // pricePerNight: '<value>' // Filter by pricePerNight
        // propertyType: '<value>' // Filter by propertyType
        // currency: '<value>' // Filter by currency
        // isPublished: '<value>' // Filter by isPublished
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listings",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"listings": [
		{
			"id": "ID",
			"title": "String",
			"amenityIds": "ID",
			"hostId": "ID",
			"mainPhoto": "String",
			"photos": "String",
			"address": "String",
			"pricePerNight": "Double",
			"description": "Text",
			"propertyType": "Enum",
			"propertyType_idx": "Integer",
			"location": "Object",
			"maxStay": "Integer",
			"minStay": "Integer",
			"currency": "String",
			"seasonalPricing": "Object",
			"approvalType": "Enum",
			"approvalType_idx": "Integer",
			"bookingPolicies": "Object",
			"cancellationPolicy": "Object",
			"languagesSupported": "String",
			"houseRules": "Text",
			"isPublished": "Boolean",
			"cityTaxPercent": "Double",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"reviews": {
				"rating": "Integer",
				"revieweeId": "ID"
			},
			"amenities": {
				"iconUrl": "String",
				"name": "String"
			}
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Update Listingcalendar` API

Update a calendar entry (availablity, pricing, reservation) for a listing date.

Rest Route

The updateListingCalendar API REST controller can be triggered via the following route:

/v1/listingcalendars/:listingCalendarId

Rest Request Parameters

The updateListingCalendar api has got 7 regular request parameters

Parameter	Type	Required	Population
listingCalendarId	ID	true	request.params?.[“listingCalendarId”]
priceOverride	Double	false	request.body?.[“priceOverride”]
minStay	Integer	false	request.body?.[“minStay”]
bookedBy	ID	false	request.body?.[“bookedBy”]
iCalUrl	String	false	request.body?.[“iCalUrl”]
externalCalendarIds	String	false	request.body?.[“externalCalendarIds”]
isAvailable	Boolean	false	request.body?.[“isAvailable”]
listingCalendarId : This id paremeter is used to select the required data object that will be updated
priceOverride :
minStay :
bookedBy :
iCalUrl :
externalCalendarIds :
isAvailable :

REST Request To access the api you can use the REST controller with the path PATCH /v1/listingcalendars/:listingCalendarId

  axios({
    method: 'PATCH',
    url: `/v1/listingcalendars/${listingCalendarId}`,
    data: {
            priceOverride:"Double",  
            minStay:"Integer",  
            bookedBy:"ID",  
            iCalUrl:"String",  
            externalCalendarIds:"String",  
            isAvailable:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingCalendar",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"listingCalendar": {
		"id": "ID",
		"priceOverride": "Double",
		"date": "Date",
		"minStay": "Integer",
		"listingId": "ID",
		"bookedBy": "ID",
		"iCalUrl": "String",
		"externalCalendarIds": "String",
		"isAvailable": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Create Listingcalendar` API

Add a calendar entry for a listing/date—controls availability or booking info for that day.

Rest Route

The createListingCalendar API REST controller can be triggered via the following route:

/v1/listingcalendars

Rest Request Parameters

The createListingCalendar api has got 8 regular request parameters

Parameter	Type	Required	Population
priceOverride	Double	false	request.body?.[“priceOverride”]
date	Date	true	request.body?.[“date”]
minStay	Integer	false	request.body?.[“minStay”]
listingId	ID	true	request.body?.[“listingId”]
bookedBy	ID	false	request.body?.[“bookedBy”]
iCalUrl	String	false	request.body?.[“iCalUrl”]
externalCalendarIds	String	false	request.body?.[“externalCalendarIds”]
isAvailable	Boolean	true	request.body?.[“isAvailable”]
priceOverride :
date :
minStay :
listingId :
bookedBy :
iCalUrl :
externalCalendarIds :
isAvailable :

REST Request To access the api you can use the REST controller with the path POST /v1/listingcalendars

  axios({
    method: 'POST',
    url: '/v1/listingcalendars',
    data: {
            priceOverride:"Double",  
            date:"Date",  
            minStay:"Integer",  
            listingId:"ID",  
            bookedBy:"ID",  
            iCalUrl:"String",  
            externalCalendarIds:"String",  
            isAvailable:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingCalendar",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"listingCalendar": {
		"id": "ID",
		"priceOverride": "Double",
		"date": "Date",
		"minStay": "Integer",
		"listingId": "ID",
		"bookedBy": "ID",
		"iCalUrl": "String",
		"externalCalendarIds": "String",
		"isAvailable": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Listingcalendar` API

Delete (soft-delete) a listing calendar entry (by host/admin).

Rest Route

The deleteListingCalendar API REST controller can be triggered via the following route:

/v1/listingcalendars/:listingCalendarId

Rest Request Parameters

The deleteListingCalendar api has got 1 regular request parameter

Parameter	Type	Required	Population
listingCalendarId	ID	true	request.params?.[“listingCalendarId”]
listingCalendarId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/listingcalendars/:listingCalendarId

  axios({
    method: 'DELETE',
    url: `/v1/listingcalendars/${listingCalendarId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingCalendar",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"listingCalendar": {
		"id": "ID",
		"priceOverride": "Double",
		"date": "Date",
		"minStay": "Integer",
		"listingId": "ID",
		"bookedBy": "ID",
		"iCalUrl": "String",
		"externalCalendarIds": "String",
		"isAvailable": "Boolean",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Listingcalendar` API

Get a calendar date entry for a listing.

Rest Route

The getListingCalendar API REST controller can be triggered via the following route:

/v1/listingcalendars/:listingCalendarId

Rest Request Parameters

The getListingCalendar api has got 1 regular request parameter

Parameter	Type	Required	Population
listingCalendarId	ID	true	request.params?.[“listingCalendarId”]
listingCalendarId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/listingcalendars/:listingCalendarId

  axios({
    method: 'GET',
    url: `/v1/listingcalendars/${listingCalendarId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingCalendar",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"listingCalendar": {
		"id": "ID",
		"priceOverride": "Double",
		"date": "Date",
		"minStay": "Integer",
		"listingId": "ID",
		"bookedBy": "ID",
		"iCalUrl": "String",
		"externalCalendarIds": "String",
		"isAvailable": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Listingcalendars` API

List calendar entries for one or more listings/dates. Used for display and availability search.

Rest Route

The listListingCalendars API REST controller can be triggered via the following route:

/v1/listingcalendars

Rest Request Parameters

Filter Parameters

The listListingCalendars api supports 2 optional filter parameters for filtering list results:

date (Date): Filter by date

Single date: ?date=2024-01-15
Multiple dates: ?date=2024-01-15&date=2024-01-20
Special: $today, $ltoday, $week, $lweek, $month, $leq-<date>, $lin-<date>
Null: ?date=null

listingId (ID): Filter by listingId

Single: ?listingId=<value>
Multiple: ?listingId=<value1>&listingId=<value2>
Null: ?listingId=null

REST Request To access the api you can use the REST controller with the path GET /v1/listingcalendars

  axios({
    method: 'GET',
    url: '/v1/listingcalendars',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // date: '<value>' // Filter by date
        // listingId: '<value>' // Filter by listingId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingCalendars",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"listingCalendars": [
		{
			"id": "ID",
			"priceOverride": "Double",
			"date": "Date",
			"minStay": "Integer",
			"listingId": "ID",
			"bookedBy": "ID",
			"iCalUrl": "String",
			"externalCalendarIds": "String",
			"isAvailable": "Boolean",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Get Listing` API

Get a property listing, including enriched amenities and available locales.

Rest Route

The getListing API REST controller can be triggered via the following route:

/v1/listings/:listingId

Rest Request Parameters

The getListing api has got 1 regular request parameter

Parameter	Type	Required	Population
listingId	ID	true	request.params?.[“listingId”]
listingId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/listings/:listingId

  axios({
    method: 'GET',
    url: `/v1/listings/${listingId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listing",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"listing": {
		"id": "ID",
		"title": "String",
		"amenityIds": "ID",
		"hostId": "ID",
		"mainPhoto": "String",
		"photos": "String",
		"address": "String",
		"pricePerNight": "Double",
		"description": "Text",
		"propertyType": "Enum",
		"propertyType_idx": "Integer",
		"location": "Object",
		"maxStay": "Integer",
		"minStay": "Integer",
		"currency": "String",
		"seasonalPricing": "Object",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingPolicies": "Object",
		"cancellationPolicy": "Object",
		"languagesSupported": "String",
		"houseRules": "Text",
		"isPublished": "Boolean",
		"cityTaxPercent": "Double",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"amenities": {
			"iconUrl": "String",
			"name": "String"
		},
		"reviews": {
			"moderationStatus": "Enum",
			"moderationStatus_idx": "Integer",
			"isPublished": "Boolean",
			"reviewText": "Text",
			"rating": "Integer",
			"revieweeId": "ID",
			"reservationId": "ID",
			"reviewerId": "ID",
			"revieweeType": "Enum",
			"revieweeType_idx": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date"
		},
		"rezervations": [
			{
				"bookingStatus": "Enum",
				"bookingStatus_idx": "Integer",
				"guestId": "ID"
			},
			{},
			{}
		]
	}
}

`Create Listinglocaletext` API

Add a localized title & description for a listing/language pair.

Rest Route

The createListingLocaleText API REST controller can be triggered via the following route:

/v1/listinglocaletexts

Rest Request Parameters

The createListingLocaleText api has got 4 regular request parameters

Parameter	Type	Required	Population
localizedDescription	Text	true	request.body?.[“localizedDescription”]
localizedTitle	String	true	request.body?.[“localizedTitle”]
listingId	ID	true	request.body?.[“listingId”]
languageCode	String	true	request.body?.[“languageCode”]
localizedDescription :
localizedTitle :
listingId :
languageCode :

REST Request To access the api you can use the REST controller with the path POST /v1/listinglocaletexts

  axios({
    method: 'POST',
    url: '/v1/listinglocaletexts',
    data: {
            localizedDescription:"Text",  
            localizedTitle:"String",  
            listingId:"ID",  
            languageCode:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingLocaleText",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"listingLocaleText": {
		"id": "ID",
		"localizedDescription": "Text",
		"localizedTitle": "String",
		"listingId": "ID",
		"languageCode": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Listingamenities` API

List all amenity options (public for guests/hosts creating listings).

Rest Route

The listListingAmenities API REST controller can be triggered via the following route:

/v1/listingamenities

Rest Request Parameters

Filter Parameters

The listListingAmenities api supports 1 optional filter parameter for filtering list results:

name (String): Filter by name

Single (partial match, case-insensitive): ?name=<value>
Multiple: ?name=<value1>&name=<value2>
Null: ?name=null

REST Request To access the api you can use the REST controller with the path GET /v1/listingamenities

  axios({
    method: 'GET',
    url: '/v1/listingamenities',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // name: '<value>' // Filter by name
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingAmenities",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"listingAmenities": [
		{
			"id": "ID",
			"iconUrl": "String",
			"name": "String",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Delete Listinglocaletext` API

Delete (soft-delete) a locale text entry for a listing/language.

Rest Route

The deleteListingLocaleText API REST controller can be triggered via the following route:

/v1/listinglocaletexts/:listingLocaleTextId

Rest Request Parameters

The deleteListingLocaleText api has got 1 regular request parameter

Parameter	Type	Required	Population
listingLocaleTextId	ID	true	request.params?.[“listingLocaleTextId”]
listingLocaleTextId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/listinglocaletexts/:listingLocaleTextId

  axios({
    method: 'DELETE',
    url: `/v1/listinglocaletexts/${listingLocaleTextId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingLocaleText",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"listingLocaleText": {
		"id": "ID",
		"localizedDescription": "Text",
		"localizedTitle": "String",
		"listingId": "ID",
		"languageCode": "String",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Listinglocaletexts` API

List all localized texts for a given listing (multi-language support).

Rest Route

The listListingLocaleTexts API REST controller can be triggered via the following route:

/v1/listinglocaletexts

Rest Request Parameters

Filter Parameters

The listListingLocaleTexts api supports 2 optional filter parameters for filtering list results:

listingId (ID): Filter by listingId

Single: ?listingId=<value>
Multiple: ?listingId=<value1>&listingId=<value2>
Null: ?listingId=null

languageCode (String): Filter by languageCode

Single (partial match, case-insensitive): ?languageCode=<value>
Multiple: ?languageCode=<value1>&languageCode=<value2>
Null: ?languageCode=null

REST Request To access the api you can use the REST controller with the path GET /v1/listinglocaletexts

  axios({
    method: 'GET',
    url: '/v1/listinglocaletexts',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // listingId: '<value>' // Filter by listingId
        // languageCode: '<value>' // Filter by languageCode
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingLocaleTexts",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"listingLocaleTexts": [
		{
			"id": "ID",
			"localizedDescription": "Text",
			"localizedTitle": "String",
			"listingId": "ID",
			"languageCode": "String",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Update Listinglocaletext` API

Update a localized title/description for a listing/language.

Rest Route

The updateListingLocaleText API REST controller can be triggered via the following route:

/v1/listinglocaletexts/:listingLocaleTextId

Rest Request Parameters

The updateListingLocaleText api has got 3 regular request parameters

Parameter	Type	Required	Population
listingLocaleTextId	ID	true	request.params?.[“listingLocaleTextId”]
localizedDescription	Text	false	request.body?.[“localizedDescription”]
localizedTitle	String	false	request.body?.[“localizedTitle”]
listingLocaleTextId : This id paremeter is used to select the required data object that will be updated
localizedDescription :
localizedTitle :

REST Request To access the api you can use the REST controller with the path PATCH /v1/listinglocaletexts/:listingLocaleTextId

  axios({
    method: 'PATCH',
    url: `/v1/listinglocaletexts/${listingLocaleTextId}`,
    data: {
            localizedDescription:"Text",  
            localizedTitle:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingLocaleText",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"listingLocaleText": {
		"id": "ID",
		"localizedDescription": "Text",
		"localizedTitle": "String",
		"listingId": "ID",
		"languageCode": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Listingamenity` API

Update an amenity (admin only).

Rest Route

The updateListingAmenity API REST controller can be triggered via the following route:

/v1/listingamenities/:listingAmenityId

Rest Request Parameters

The updateListingAmenity api has got 2 regular request parameters

Parameter	Type	Required	Population
listingAmenityId	ID	true	request.params?.[“listingAmenityId”]
iconUrl	String	false	request.body?.[“iconUrl”]
listingAmenityId : This id paremeter is used to select the required data object that will be updated
iconUrl :

REST Request To access the api you can use the REST controller with the path PATCH /v1/listingamenities/:listingAmenityId

  axios({
    method: 'PATCH',
    url: `/v1/listingamenities/${listingAmenityId}`,
    data: {
            iconUrl:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingAmenity",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"listingAmenity": {
		"id": "ID",
		"iconUrl": "String",
		"name": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Listingamenity` API

Get information for a listed amenity (public).

Rest Route

The getListingAmenity API REST controller can be triggered via the following route:

/v1/listingamenities/:listingAmenityId

Rest Request Parameters

The getListingAmenity api has got 1 regular request parameter

Parameter	Type	Required	Population
listingAmenityId	ID	true	request.params?.[“listingAmenityId”]
listingAmenityId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/listingamenities/:listingAmenityId

  axios({
    method: 'GET',
    url: `/v1/listingamenities/${listingAmenityId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingAmenity",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"listingAmenity": {
		"id": "ID",
		"iconUrl": "String",
		"name": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Listinglocaletext` API

Get localized listing title/description (by listing/language).

Rest Route

The getListingLocaleText API REST controller can be triggered via the following route:

/v1/listinglocaletexts/:listingLocaleTextId

Rest Request Parameters

The getListingLocaleText api has got 1 regular request parameter

Parameter	Type	Required	Population
listingLocaleTextId	ID	true	request.params?.[“listingLocaleTextId”]
listingLocaleTextId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/listinglocaletexts/:listingLocaleTextId

  axios({
    method: 'GET',
    url: `/v1/listinglocaletexts/${listingLocaleTextId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingLocaleText",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"listingLocaleText": {
		"id": "ID",
		"localizedDescription": "Text",
		"localizedTitle": "String",
		"listingId": "ID",
		"languageCode": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Create Listingamenity` API

Add a new amenity to the master amenity list.

Rest Route

The createListingAmenity API REST controller can be triggered via the following route:

/v1/listingamenities

Rest Request Parameters

The createListingAmenity api has got 2 regular request parameters

Parameter	Type	Required	Population
iconUrl	String	false	request.body?.[“iconUrl”]
name	String	true	request.body?.[“name”]
iconUrl :
name :

REST Request To access the api you can use the REST controller with the path POST /v1/listingamenities

  axios({
    method: 'POST',
    url: '/v1/listingamenities',
    data: {
            iconUrl:"String",  
            name:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingAmenity",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"listingAmenity": {
		"id": "ID",
		"iconUrl": "String",
		"name": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Listingamenity` API

Delete (soft-delete) an amenity (admin only).

Rest Route

The deleteListingAmenity API REST controller can be triggered via the following route:

/v1/listingamenities/:listingAmenityId

Rest Request Parameters

The deleteListingAmenity api has got 1 regular request parameter

Parameter	Type	Required	Population
listingAmenityId	ID	true	request.params?.[“listingAmenityId”]
listingAmenityId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/listingamenities/:listingAmenityId

  axios({
    method: 'DELETE',
    url: `/v1/listingamenities/${listingAmenityId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "listingAmenity",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"listingAmenity": {
		"id": "ID",
		"iconUrl": "String",
		"name": "String",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 9 - BookingManagement Service

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides extensive instruction for the usage of bookingManagement

Service Access

BookingManagement service management is handled through service specific base urls.

BookingManagement service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the bookingManagement service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/bookingmanagement-api
Staging: https://airbnb3-stage.mindbricks.co/bookingmanagement-api
Production: https://airbnb3.mindbricks.co/bookingmanagement-api

Scope

BookingManagement Service Description

Orchestrates booking, payment, calendar, changewsand dispute flows for Airbnb-style short-term rental marketplace…test Handles reservations, approval, Stripe payments, iCal sync, payment records, and the dispute/refund lifecycle with host/guest/admin visibility.

BookingManagement service provides apis and business logic for following data objects in airbnb application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows.

reservation Data Object: Represents a guest's booking for a property listing, including dates, participants, approval/payment/dispute status, and iCal sync info…

paymentRecord Data Object: Stores payment and payout records (Stripe-driven) linked to a reservation (guest booking), including platform fees, taxes, host payouts, and status updates. Immutable after creation, never hard deleted.

dispute Data Object: Represents a dispute, refund request, or booking issue reported by guest/host/admin for a reservation. Flows to admin for handling, resolves with resolutionStatus and reference to any refund/payment involved.

sys_reservationPayment Data Object: A payment storage object to store the payment life cyle of orders based on reservation object. It is autocreated based on the source object's checkout config

sys_paymentCustomer Data Object: A payment storage object to store the customer values of the payment platform

sys_paymentMethod Data Object: A payment storage object to store the payment methods of the platform customers

API Structure

Object Structure of a Successful Response

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Reservation Data Object

Represents a guest's booking for a property listing, including dates, participants, approval/payment/dispute status, and iCal sync info…

Reservation Data Object Properties

Reservation data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`listingId`	ID	false	Yes	No	-
`approvalType`	Enum	false	Yes	No	-
`bookingStatus`	Enum	false	Yes	No	-
`hostId`	ID	false	Yes	No	-
`checkOut`	Date	false	Yes	No	-
`guestId`	ID	false	Yes	No	-
`checkIn`	Date	false	Yes	No	-
`currency`	String	false	Yes	No	-
`guestCount`	Integer	false	Yes	No	-
`totalPrice`	Double	false	Yes	No	-
`iCalExportUrl`	String	false	No	No	-
`disputeStatus`	Enum	false	Yes	No	-
`bookingPoliciesSnapshot`	Object	false	Yes	No	-
`iCalImportSource`	String	false	No	No	-
`cancellationPolicySnapshot`	Object	false	Yes	No	-
`paymentConfirmation`	Enum	false	Yes	No	An automatic property that is used to check the confirmed status of the payment set by webhooks.

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

approvalType: [instant, manual]
bookingStatus: [pending, confirmed, complete, cancelled, declined]
disputeStatus: [none, requested, active, resolved]
paymentConfirmation: [pending, processing, paid, canceled]

Relation Properties

listingId hostId

In frontend, please ensure that,

listingId: ID Relation to listing.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

hostId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Filter Properties

listingId approvalType bookingStatus hostId guestId checkIn paymentConfirmation

listingId: ID has a filter named listingId
approvalType: Enum has a filter named approvalType
bookingStatus: Enum has a filter named bookingStatus
hostId: ID has a filter named hostId
guestId: ID has a filter named guestId
checkIn: Date has a filter named checkIn
paymentConfirmation: Enum has a filter named paymentConfirmation

PaymentRecord Data Object

Stores payment and payout records (Stripe-driven) linked to a reservation (guest booking), including platform fees, taxes, host payouts, and status updates. Immutable after creation, never hard deleted.

PaymentRecord Data Object Properties

PaymentRecord data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`reservationId`	ID	false	Yes	No	-
`stripeChargeId`	String	false	No	No	-
`payoutAmountHost`	Double	false	No	No	-
`paymentIntentId`	String	false	Yes	No	-
`currency`	String	false	Yes	No	-
`cityTax`	Double	false	No	No	-
`refundAmount`	Double	false	No	No	-
`amountPaid`	Double	false	Yes	No	-
`paymentStatus`	Enum	false	Yes	No	-
`platformFee`	Double	false	No	No	-
`paymentDate`	Date	false	No	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

paymentStatus: [pending, paid, refunded, failed]

Relation Properties

reservationId

In frontend, please ensure that,

reservationId: ID Relation to reservation.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Dispute Data Object

Represents a dispute, refund request, or booking issue reported by guest/host/admin for a reservation. Flows to admin for handling, resolves with resolutionStatus and reference to any refund/payment involved.

Dispute Data Object Properties

Dispute data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`reportedAt`	Date	false	Yes	No	-
`reservationId`	ID	false	Yes	No	-
`raisedBy`	ID	false	Yes	No	-
`adminId`	ID	false	No	No	-
`issueType`	String	false	Yes	No	-
`description`	Text	false	Yes	No	-
`relatedPaymentId`	ID	false	No	No	-
`resolutionStatus`	Enum	false	Yes	No	-
`resolvedAt`	Date	false	No	No	-
`refundApproved`	Boolean	false	No	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

resolutionStatus: [pending, reviewing, resolved, rejected]

Relation Properties

reservationId raisedBy adminId relatedPaymentId

In frontend, please ensure that,

reservationId: ID Relation to reservation.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

raisedBy: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

adminId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

relatedPaymentId: ID Relation to paymentRecord.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

Sys_reservationPayment Data Object

A payment storage object to store the payment life cyle of orders based on reservation object. It is autocreated based on the source object's checkout config

Sys_reservationPayment Data Object Properties

Sys_reservationPayment data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`ownerId`	ID	false	No	No	An ID value to represent owner user who created the order
`orderId`	ID	false	Yes	No	an ID value to represent the orderId which is the ID parameter of the source reservation object
`paymentId`	String	false	Yes	No	A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type
`paymentStatus`	String	false	Yes	No	A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.
`statusLiteral`	String	false	Yes	No	A string value to represent the logical payment status which belongs to the application lifecycle itself.
`redirectUrl`	String	false	No	No	A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Filter Properties

ownerId orderId paymentId paymentStatus statusLiteral redirectUrl

ownerId: ID has a filter named ownerId
orderId: ID has a filter named orderId
paymentId: String has a filter named paymentId
paymentStatus: String has a filter named paymentStatus
statusLiteral: String has a filter named statusLiteral
redirectUrl: String has a filter named redirectUrl

Sys_paymentCustomer Data Object

A payment storage object to store the customer values of the payment platform

Sys_paymentCustomer Data Object Properties

Sys_paymentCustomer data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`userId`	ID	false	No	No	An ID value to represent the user who is created as a stripe customer
`customerId`	String	false	Yes	No	A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway
`platform`	String	false	Yes	No	A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future.

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Filter Properties

userId customerId platform

userId: ID has a filter named userId
customerId: String has a filter named customerId
platform: String has a filter named platform

Sys_paymentMethod Data Object

A payment storage object to store the payment methods of the platform customers

Sys_paymentMethod Data Object Properties

Sys_paymentMethod data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`paymentMethodId`	String	false	Yes	No	A string value to represent the id of the payment method on the payment platform.
`userId`	ID	false	Yes	No	An ID value to represent the user who owns the payment method
`customerId`	String	false	Yes	No	A string value to represent the customer id which is generated on the payment gateway.
`cardHolderName`	String	false	No	No	A string value to represent the name of the card holder. It can be different than the registered customer.
`cardHolderZip`	String	false	No	No	A string value to represent the zip code of the card holder. It is used for address verification in specific countries.
`platform`	String	false	Yes	No	A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future.
`cardInfo`	Object	false	Yes	No	A Json value to store the card details of the payment method.

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Filter Properties

paymentMethodId userId customerId cardHolderName cardHolderZip platform cardInfo

paymentMethodId: String has a filter named paymentMethodId
userId: ID has a filter named userId
customerId: String has a filter named customerId
cardHolderName: String has a filter named cardHolderName
cardHolderZip: String has a filter named cardHolderZip
platform: String has a filter named platform
cardInfo: Object has a filter named cardInfo

Default CRUD APIs

Reservation Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createReservation`	`/v1/reservations`	Auto
Update	`updateReservation`	`/v1/reservations/:reservationId`	Auto
Delete	`deleteReservation`	`/v1/reservations/:reservationId`	Auto
Get	`getReservation`	`/v1/reservations/:reservationId`	Auto
List	`listReservations`	`/v1/reservations`	Auto

PaymentRecord Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createPaymentRecord`	`/v1/paymentrecords`	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	`getPaymentRecord`	`/v1/paymentrecords/:paymentRecordId`	Auto
List	`listPaymentRecords`	`/v1/paymentrecords`	Auto

Dispute Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createDispute`	`/v1/disputes`	Auto
Update	`updateDispute`	`/v1/disputes/:disputeId`	Auto
Delete	none	-	Auto
Get	`getDispute`	`/v1/disputes/:disputeId`	Auto
List	`listDisputes`	`/v1/disputes`	Auto

Sys_reservationPayment Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createReservationPayment`	`/v1/reservationpayment`	Auto
Update	`updateReservationPayment`	`/v1/reservationpayment/:sys_reservationPaymentId`	Auto
Delete	`deleteReservationPayment`	`/v1/reservationpayment/:sys_reservationPaymentId`	Auto
Get	`getReservationPayment`	`/v1/reservationpayment/:sys_reservationPaymentId`	Auto
List	`listReservationPayments`	`/v1/reservationpayments`	Auto

Sys_paymentCustomer Default APIs

Operation	API Name	Route	Explicitly Set
Create	none	-	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	`getPaymentCustomerByUserId`	`/v1/paymentcustomers/:userId`	Auto
List	`listPaymentCustomers`	`/v1/paymentcustomers`	Auto

Sys_paymentMethod Default APIs

Operation	API Name	Route	Explicitly Set
Create	none	-	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	none	-	Auto
List	`listPaymentCustomerMethods`	`/v1/paymentcustomermethods/:userId`	Auto

API Reference

`Update Dispute` API

Updates dispute fields like status, admin assignment, resolution notes. Only admin or assigned party can update (enforced by membership/role checks).

Rest Route

The updateDispute API REST controller can be triggered via the following route:

/v1/disputes/:disputeId

Rest Request Parameters

The updateDispute api has got 7 regular request parameters

Parameter	Type	Required	Population
disputeId	ID	true	request.params?.[“disputeId”]
adminId	ID	false	request.body?.[“adminId”]
issueType	String	false	request.body?.[“issueType”]
description	Text	false	request.body?.[“description”]
resolutionStatus	Enum	false	request.body?.[“resolutionStatus”]
resolvedAt	Date	false	request.body?.[“resolvedAt”]
refundApproved	Boolean	false	request.body?.[“refundApproved”]
disputeId : This id paremeter is used to select the required data object that will be updated
adminId :
issueType :
description :
resolutionStatus :
resolvedAt :
refundApproved :

REST Request To access the api you can use the REST controller with the path PATCH /v1/disputes/:disputeId

  axios({
    method: 'PATCH',
    url: `/v1/disputes/${disputeId}`,
    data: {
            adminId:"ID",  
            issueType:"String",  
            description:"Text",  
            resolutionStatus:"Enum",  
            resolvedAt:"Date",  
            refundApproved:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "dispute",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"dispute": {
		"id": "ID",
		"reportedAt": "Date",
		"reservationId": "ID",
		"raisedBy": "ID",
		"adminId": "ID",
		"issueType": "String",
		"description": "Text",
		"relatedPaymentId": "ID",
		"resolutionStatus": "Enum",
		"resolutionStatus_idx": "Integer",
		"resolvedAt": "Date",
		"refundApproved": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Paymentrecord` API

Get a payment record by ID (owner or admin only). No selectJoin for privacy. Returned for auditing or user view.

Rest Route

The getPaymentRecord API REST controller can be triggered via the following route:

/v1/paymentrecords/:paymentRecordId

Rest Request Parameters

The getPaymentRecord api has got 1 regular request parameter

Parameter	Type	Required	Population
paymentRecordId	ID	true	request.params?.[“paymentRecordId”]
paymentRecordId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/paymentrecords/:paymentRecordId

  axios({
    method: 'GET',
    url: `/v1/paymentrecords/${paymentRecordId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "paymentRecord",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"paymentRecord": {
		"id": "ID",
		"reservationId": "ID",
		"stripeChargeId": "String",
		"payoutAmountHost": "Double",
		"paymentIntentId": "String",
		"currency": "String",
		"cityTax": "Double",
		"refundAmount": "Double",
		"amountPaid": "Double",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"platformFee": "Double",
		"paymentDate": "Date",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Reservation` API

Fetch a single reservation (for guest, host, or admin). Auto-includes related listing and payments via selectJoin.

Rest Route

The getReservation API REST controller can be triggered via the following route:

/v1/reservations/:reservationId

Rest Request Parameters

The getReservation api has got 1 regular request parameter

Parameter	Type	Required	Population
reservationId	ID	true	request.params?.[“reservationId”]
reservationId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/reservations/:reservationId

  axios({
    method: 'GET',
    url: `/v1/reservations/${reservationId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Create Dispute` API

Guest/host opens a formal dispute related to a reservation. Admin is only assigned after initial review. Can only be created by guest/host of reservation (enforced in logic).

Rest Route

The createDispute API REST controller can be triggered via the following route:

/v1/disputes

Rest Request Parameters

The createDispute api has got 10 regular request parameters

Parameter	Type	Required	Population
reportedAt	Date	true	request.body?.[“reportedAt”]
reservationId	ID	true	request.body?.[“reservationId”]
raisedBy	ID	true	request.body?.[“raisedBy”]
adminId	ID	false	request.body?.[“adminId”]
issueType	String	true	request.body?.[“issueType”]
description	Text	true	request.body?.[“description”]
relatedPaymentId	ID	false	request.body?.[“relatedPaymentId”]
resolutionStatus	Enum	true	request.body?.[“resolutionStatus”]
resolvedAt	Date	false	request.body?.[“resolvedAt”]
refundApproved	Boolean	false	request.body?.[“refundApproved”]
reportedAt :
reservationId :
raisedBy :
adminId :
issueType :
description :
relatedPaymentId :
resolutionStatus :
resolvedAt :
refundApproved :

REST Request To access the api you can use the REST controller with the path POST /v1/disputes

  axios({
    method: 'POST',
    url: '/v1/disputes',
    data: {
            reportedAt:"Date",  
            reservationId:"ID",  
            raisedBy:"ID",  
            adminId:"ID",  
            issueType:"String",  
            description:"Text",  
            relatedPaymentId:"ID",  
            resolutionStatus:"Enum",  
            resolvedAt:"Date",  
            refundApproved:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "dispute",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"dispute": {
		"id": "ID",
		"reportedAt": "Date",
		"reservationId": "ID",
		"raisedBy": "ID",
		"adminId": "ID",
		"issueType": "String",
		"description": "Text",
		"relatedPaymentId": "ID",
		"resolutionStatus": "Enum",
		"resolutionStatus_idx": "Integer",
		"resolvedAt": "Date",
		"refundApproved": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Reservations` API

List reservations (bookings) for guest, host, or admin. Includes selectJoin for listing/guest/host info. Filterable by guestId, hostId, status, etc.

Rest Route

The listReservations API REST controller can be triggered via the following route:

/v1/reservations

Rest Request Parameters

Filter Parameters

The listReservations api supports 7 optional filter parameters for filtering list results:

listingId (ID): Filter by listingId

Single: ?listingId=<value>
Multiple: ?listingId=<value1>&listingId=<value2>
Null: ?listingId=null

approvalType (Enum): Filter by approvalType

Single: ?approvalType=<value> (case-insensitive)
Multiple: ?approvalType=<value1>&approvalType=<value2>
Null: ?approvalType=null

bookingStatus (Enum): Filter by bookingStatus

Single: ?bookingStatus=<value> (case-insensitive)
Multiple: ?bookingStatus=<value1>&bookingStatus=<value2>
Null: ?bookingStatus=null

hostId (ID): Filter by hostId

Single: ?hostId=<value>
Multiple: ?hostId=<value1>&hostId=<value2>
Null: ?hostId=null

guestId (ID): Filter by guestId

Single: ?guestId=<value>
Multiple: ?guestId=<value1>&guestId=<value2>
Null: ?guestId=null

checkIn (Date): Filter by checkIn

Single date: ?checkIn=2024-01-15
Multiple dates: ?checkIn=2024-01-15&checkIn=2024-01-20
Special: $today, $ltoday, $week, $lweek, $month, $leq-<date>, $lin-<date>
Null: ?checkIn=null

paymentConfirmation (Enum): An automatic property that is used to check the confirmed status of the payment set by webhooks.

Single: ?paymentConfirmation=<value> (case-insensitive)
Multiple: ?paymentConfirmation=<value1>&paymentConfirmation=<value2>
Null: ?paymentConfirmation=null

REST Request To access the api you can use the REST controller with the path GET /v1/reservations

  axios({
    method: 'GET',
    url: '/v1/reservations',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // listingId: '<value>' // Filter by listingId
        // approvalType: '<value>' // Filter by approvalType
        // bookingStatus: '<value>' // Filter by bookingStatus
        // hostId: '<value>' // Filter by hostId
        // guestId: '<value>' // Filter by guestId
        // checkIn: '<value>' // Filter by checkIn
        // paymentConfirmation: '<value>' // Filter by paymentConfirmation
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservations",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"reservations": [
		{
			"id": "ID",
			"listingId": "ID",
			"approvalType": "Enum",
			"approvalType_idx": "Integer",
			"bookingStatus": "Enum",
			"bookingStatus_idx": "Integer",
			"hostId": "ID",
			"checkOut": "Date",
			"guestId": "ID",
			"checkIn": "Date",
			"currency": "String",
			"guestCount": "Integer",
			"totalPrice": "Double",
			"iCalExportUrl": "String",
			"disputeStatus": "Enum",
			"disputeStatus_idx": "Integer",
			"bookingPoliciesSnapshot": "Object",
			"iCalImportSource": "String",
			"cancellationPolicySnapshot": "Object",
			"paymentConfirmation": "Enum",
			"paymentConfirmation_idx": "Integer",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"listingJoins": [
				{
					"title": "String",
					"amenityIds": "ID",
					"hostId": "ID",
					"mainPhoto": "String",
					"photos": "String",
					"address": "String",
					"propertyType": "Enum",
					"propertyType_idx": "Integer",
					"location": "Object"
				},
				{},
				{}
			],
			"hostDetails": [
				{
					"email": "String",
					"fullname": "String",
					"avatar": "String"
				},
				{},
				{}
			]
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Reservation` API

Guest initiates a reservation for a listing (instant or manual). Handles calendar check, approvalType, payment intent, and booking policies. Triggers Stripe checkout. Only allowed if dates are available and not conflicting. Guest is current user.

Rest Route

The createReservation API REST controller can be triggered via the following route:

/v1/reservations

Rest Request Parameters

The createReservation api has got 14 regular request parameters

Parameter	Type	Required	Population
listingId	ID	true	request.body?.[“listingId”]
approvalType	Enum	true	request.body?.[“approvalType”]
bookingStatus	Enum	true	request.body?.[“bookingStatus”]
hostId	ID	true	request.body?.[“hostId”]
checkOut	Date	true	request.body?.[“checkOut”]
checkIn	Date	true	request.body?.[“checkIn”]
currency	String	true	request.body?.[“currency”]
guestCount	Integer	true	request.body?.[“guestCount”]
totalPrice	Double	true	request.body?.[“totalPrice”]
iCalExportUrl	String	false	request.body?.[“iCalExportUrl”]
disputeStatus	Enum	true	request.body?.[“disputeStatus”]
bookingPoliciesSnapshot	Object	true	request.body?.[“bookingPoliciesSnapshot”]
iCalImportSource	String	false	request.body?.[“iCalImportSource”]
cancellationPolicySnapshot	Object	true	request.body?.[“cancellationPolicySnapshot”]
listingId :
approvalType :
bookingStatus :
hostId :
checkOut :
checkIn :
currency :
guestCount :
totalPrice :
iCalExportUrl :
disputeStatus :
bookingPoliciesSnapshot :
iCalImportSource :
cancellationPolicySnapshot :

REST Request To access the api you can use the REST controller with the path POST /v1/reservations

  axios({
    method: 'POST',
    url: '/v1/reservations',
    data: {
            listingId:"ID",  
            approvalType:"Enum",  
            bookingStatus:"Enum",  
            hostId:"ID",  
            checkOut:"Date",  
            checkIn:"Date",  
            currency:"String",  
            guestCount:"Integer",  
            totalPrice:"Double",  
            iCalExportUrl:"String",  
            disputeStatus:"Enum",  
            bookingPoliciesSnapshot:"Object",  
            iCalImportSource:"String",  
            cancellationPolicySnapshot:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Create Paymentrecord` API

Creates or logs payment record for a reservation (from payment success or admin/manual trigger). Populates from Stripe events/webhooks. Only creates; no update/delete (for compliance/audit).

Rest Route

The createPaymentRecord API REST controller can be triggered via the following route:

/v1/paymentrecords

Rest Request Parameters

The createPaymentRecord api has got 11 regular request parameters

Parameter	Type	Required	Population
reservationId	ID	true	request.body?.[“reservationId”]
stripeChargeId	String	false	request.body?.[“stripeChargeId”]
payoutAmountHost	Double	false	request.body?.[“payoutAmountHost”]
paymentIntentId	String	true	request.body?.[“paymentIntentId”]
currency	String	true	request.body?.[“currency”]
cityTax	Double	false	request.body?.[“cityTax”]
refundAmount	Double	false	request.body?.[“refundAmount”]
amountPaid	Double	true	request.body?.[“amountPaid”]
paymentStatus	Enum	true	request.body?.[“paymentStatus”]
platformFee	Double	false	request.body?.[“platformFee”]
paymentDate	Date	false	request.body?.[“paymentDate”]
reservationId :
stripeChargeId :
payoutAmountHost :
paymentIntentId :
currency :
cityTax :
refundAmount :
amountPaid :
paymentStatus :
platformFee :
paymentDate :

REST Request To access the api you can use the REST controller with the path POST /v1/paymentrecords

  axios({
    method: 'POST',
    url: '/v1/paymentrecords',
    data: {
            reservationId:"ID",  
            stripeChargeId:"String",  
            payoutAmountHost:"Double",  
            paymentIntentId:"String",  
            currency:"String",  
            cityTax:"Double",  
            refundAmount:"Double",  
            amountPaid:"Double",  
            paymentStatus:"Enum",  
            platformFee:"Double",  
            paymentDate:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "paymentRecord",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"paymentRecord": {
		"id": "ID",
		"reservationId": "ID",
		"stripeChargeId": "String",
		"payoutAmountHost": "Double",
		"paymentIntentId": "String",
		"currency": "String",
		"cityTax": "Double",
		"refundAmount": "Double",
		"amountPaid": "Double",
		"paymentStatus": "Enum",
		"paymentStatus_idx": "Integer",
		"platformFee": "Double",
		"paymentDate": "Date",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Paymentrecords` API

List payment records (reservation/guest/host or admin, includes filters if needed). Used for financial histories/exports. No selectJoin, for privacy and performance.

Rest Route

The listPaymentRecords API REST controller can be triggered via the following route:

/v1/paymentrecords

Rest Request Parameters The listPaymentRecords api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/paymentrecords

  axios({
    method: 'GET',
    url: '/v1/paymentrecords',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "paymentRecords",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"paymentRecords": [
		{
			"id": "ID",
			"reservationId": "ID",
			"stripeChargeId": "String",
			"payoutAmountHost": "Double",
			"paymentIntentId": "String",
			"currency": "String",
			"cityTax": "Double",
			"refundAmount": "Double",
			"amountPaid": "Double",
			"paymentStatus": "Enum",
			"paymentStatus_idx": "Integer",
			"platformFee": "Double",
			"paymentDate": "Date",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Delete Reservation` API

Cancels or removes a reservation (soft-delete). Guest, host or admin may delete (ownership enforced). Used for cancellations before stay begins or admin moderation.

Rest Route

The deleteReservation API REST controller can be triggered via the following route:

/v1/reservations/:reservationId

Rest Request Parameters

The deleteReservation api has got 1 regular request parameter

Parameter	Type	Required	Population
reservationId	ID	true	request.params?.[“reservationId”]
reservationId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/reservations/:reservationId

  axios({
    method: 'DELETE',
    url: `/v1/reservations/${reservationId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Reservation` API

Update an existing reservation (allowed fields: only those which do not affect core identity/relations—e.g., guestCount if update allowed, NOT dates/listingId). Used for confirming cancellation, updating status by host/guest, or marking as completed. Permission: must be guest, host, or admin.

Rest Route

The updateReservation API REST controller can be triggered via the following route:

/v1/reservations/:reservationId

Rest Request Parameters

The updateReservation api has got 5 regular request parameters

Parameter	Type	Required	Population
reservationId	ID	true	request.params?.[“reservationId”]
bookingStatus	Enum	false	request.body?.[“bookingStatus”]
iCalExportUrl	String	false	request.body?.[“iCalExportUrl”]
disputeStatus	Enum	false	request.body?.[“disputeStatus”]
iCalImportSource	String	false	request.body?.[“iCalImportSource”]
reservationId : This id paremeter is used to select the required data object that will be updated
bookingStatus :
iCalExportUrl :
disputeStatus :
iCalImportSource :

REST Request To access the api you can use the REST controller with the path PATCH /v1/reservations/:reservationId

  axios({
    method: 'PATCH',
    url: `/v1/reservations/${reservationId}`,
    data: {
            bookingStatus:"Enum",  
            iCalExportUrl:"String",  
            disputeStatus:"Enum",  
            iCalImportSource:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Disputes` API

List disputes visible to the user (as guest, host, or admin). Used for admin screening and user support view. No joins for privacy. Filterable by reservationId, raisedBy, status, etc.

Rest Route

The listDisputes API REST controller can be triggered via the following route:

/v1/disputes

Rest Request Parameters The listDisputes api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/disputes

  axios({
    method: 'GET',
    url: '/v1/disputes',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "disputes",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"disputes": [
		{
			"id": "ID",
			"reportedAt": "Date",
			"reservationId": "ID",
			"raisedBy": "ID",
			"adminId": "ID",
			"issueType": "String",
			"description": "Text",
			"relatedPaymentId": "ID",
			"resolutionStatus": "Enum",
			"resolutionStatus_idx": "Integer",
			"resolvedAt": "Date",
			"refundApproved": "Boolean",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Get Dispute` API

Fetch a dispute by ID (guest, host, assigned admin, or admin role). No joins for privacy. Used for support/moderation flows.

Rest Route

The getDispute API REST controller can be triggered via the following route:

/v1/disputes/:disputeId

Rest Request Parameters

The getDispute api has got 1 regular request parameter

Parameter	Type	Required	Population
disputeId	ID	true	request.params?.[“disputeId”]
disputeId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/disputes/:disputeId

  axios({
    method: 'GET',
    url: `/v1/disputes/${disputeId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "dispute",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"dispute": {
		"id": "ID",
		"reportedAt": "Date",
		"reservationId": "ID",
		"raisedBy": "ID",
		"adminId": "ID",
		"issueType": "String",
		"description": "Text",
		"relatedPaymentId": "ID",
		"resolutionStatus": "Enum",
		"resolutionStatus_idx": "Integer",
		"resolvedAt": "Date",
		"refundApproved": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Reservationpayment` API

This route is used to get the payment information by ID.

Rest Route

The getReservationPayment API REST controller can be triggered via the following route:

/v1/reservationpayment/:sys_reservationPaymentId

Rest Request Parameters

The getReservationPayment api has got 1 regular request parameter

Parameter	Type	Required	Population
sys_reservationPaymentId	ID	true	request.params?.[“sys_reservationPaymentId”]
sys_reservationPaymentId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/reservationpayment/:sys_reservationPaymentId

  axios({
    method: 'GET',
    url: `/v1/reservationpayment/${sys_reservationPaymentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_reservationPayment",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_reservationPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Reservationpayments` API

This route is used to list all payments.

Rest Route

The listReservationPayments API REST controller can be triggered via the following route:

/v1/reservationpayments

Rest Request Parameters

Filter Parameters

The listReservationPayments api supports 6 optional filter parameters for filtering list results:

ownerId (ID): An ID value to represent owner user who created the order

Single: ?ownerId=<value>
Multiple: ?ownerId=<value1>&ownerId=<value2>
Null: ?ownerId=null

orderId (ID): an ID value to represent the orderId which is the ID parameter of the source reservation object

Single: ?orderId=<value>
Multiple: ?orderId=<value1>&orderId=<value2>
Null: ?orderId=null

paymentId (String): A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type

Single (partial match, case-insensitive): ?paymentId=<value>
Multiple: ?paymentId=<value1>&paymentId=<value2>
Null: ?paymentId=null

paymentStatus (String): A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.

Single (partial match, case-insensitive): ?paymentStatus=<value>
Multiple: ?paymentStatus=<value1>&paymentStatus=<value2>
Null: ?paymentStatus=null

statusLiteral (String): A string value to represent the logical payment status which belongs to the application lifecycle itself.

Single (partial match, case-insensitive): ?statusLiteral=<value>
Multiple: ?statusLiteral=<value1>&statusLiteral=<value2>
Null: ?statusLiteral=null

redirectUrl (String): A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.

Single (partial match, case-insensitive): ?redirectUrl=<value>
Multiple: ?redirectUrl=<value1>&redirectUrl=<value2>
Null: ?redirectUrl=null

REST Request To access the api you can use the REST controller with the path GET /v1/reservationpayments

  axios({
    method: 'GET',
    url: '/v1/reservationpayments',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // ownerId: '<value>' // Filter by ownerId
        // orderId: '<value>' // Filter by orderId
        // paymentId: '<value>' // Filter by paymentId
        // paymentStatus: '<value>' // Filter by paymentStatus
        // statusLiteral: '<value>' // Filter by statusLiteral
        // redirectUrl: '<value>' // Filter by redirectUrl
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_reservationPayments",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_reservationPayments": [
		{
			"id": "ID",
			"ownerId": "ID",
			"orderId": "ID",
			"paymentId": "String",
			"paymentStatus": "String",
			"statusLiteral": "String",
			"redirectUrl": "String",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Reservationpayment` API

This route is used to create a new payment.

Rest Route

The createReservationPayment API REST controller can be triggered via the following route:

/v1/reservationpayment

Rest Request Parameters

The createReservationPayment api has got 5 regular request parameters

Parameter	Type	Required	Population
orderId	ID	true	request.body?.[“orderId”]
paymentId	String	true	request.body?.[“paymentId”]
paymentStatus	String	true	request.body?.[“paymentStatus”]
statusLiteral	String	true	request.body?.[“statusLiteral”]
redirectUrl	String	false	request.body?.[“redirectUrl”]
orderId : an ID value to represent the orderId which is the ID parameter of the source reservation object
paymentId : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type
paymentStatus : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.
statusLiteral : A string value to represent the logical payment status which belongs to the application lifecycle itself.
redirectUrl : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.

REST Request To access the api you can use the REST controller with the path POST /v1/reservationpayment

  axios({
    method: 'POST',
    url: '/v1/reservationpayment',
    data: {
            orderId:"ID",  
            paymentId:"String",  
            paymentStatus:"String",  
            statusLiteral:"String",  
            redirectUrl:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_reservationPayment",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_reservationPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Reservationpayment` API

This route is used to update an existing payment.

Rest Route

The updateReservationPayment API REST controller can be triggered via the following route:

/v1/reservationpayment/:sys_reservationPaymentId

Rest Request Parameters

The updateReservationPayment api has got 5 regular request parameters

Parameter	Type	Required	Population
sys_reservationPaymentId	ID	true	request.params?.[“sys_reservationPaymentId”]
paymentId	String	false	request.body?.[“paymentId”]
paymentStatus	String	false	request.body?.[“paymentStatus”]
statusLiteral	String	false	request.body?.[“statusLiteral”]
redirectUrl	String	false	request.body?.[“redirectUrl”]
sys_reservationPaymentId : This id paremeter is used to select the required data object that will be updated
paymentId : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type
paymentStatus : A string value to represent the payment status which belongs to the lifecyle of a Stripe payment.
statusLiteral : A string value to represent the logical payment status which belongs to the application lifecycle itself.
redirectUrl : A string value to represent return page of the frontend to show the result of the payment, this is used when the callback is made to server not the client.

REST Request To access the api you can use the REST controller with the path PATCH /v1/reservationpayment/:sys_reservationPaymentId

  axios({
    method: 'PATCH',
    url: `/v1/reservationpayment/${sys_reservationPaymentId}`,
    data: {
            paymentId:"String",  
            paymentStatus:"String",  
            statusLiteral:"String",  
            redirectUrl:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_reservationPayment",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_reservationPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Reservationpayment` API

This route is used to delete a payment.

Rest Route

The deleteReservationPayment API REST controller can be triggered via the following route:

/v1/reservationpayment/:sys_reservationPaymentId

Rest Request Parameters

The deleteReservationPayment api has got 1 regular request parameter

Parameter	Type	Required	Population
sys_reservationPaymentId	ID	true	request.params?.[“sys_reservationPaymentId”]
sys_reservationPaymentId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/reservationpayment/:sys_reservationPaymentId

  axios({
    method: 'DELETE',
    url: `/v1/reservationpayment/${sys_reservationPaymentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_reservationPayment",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_reservationPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Reservationpaymentbyorderid` API

This route is used to get the payment information by order id.

Rest Route

The getReservationPaymentByOrderId API REST controller can be triggered via the following route:

/v1/reservationpaymentbyorderid/:orderId

Rest Request Parameters

The getReservationPaymentByOrderId api has got 1 regular request parameter

Parameter	Type	Required	Population
orderId	ID	true	request.params?.[“orderId”]
orderId : an ID value to represent the orderId which is the ID parameter of the source reservation object. The parameter is used to query data.

REST Request To access the api you can use the REST controller with the path GET /v1/reservationpaymentbyorderid/:orderId

  axios({
    method: 'GET',
    url: `/v1/reservationpaymentbyorderid/${orderId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_reservationPayment",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_reservationPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Reservationpaymentbypaymentid` API

This route is used to get the payment information by payment id.

Rest Route

The getReservationPaymentByPaymentId API REST controller can be triggered via the following route:

/v1/reservationpaymentbypaymentid/:paymentId

Rest Request Parameters

The getReservationPaymentByPaymentId api has got 1 regular request parameter

Parameter	Type	Required	Population
paymentId	String	true	request.params?.[“paymentId”]
paymentId : A String value to represent the paymentId which is generated on the Stripe gateway. This id may represent different objects due to the payment gateway and the chosen flow type. The parameter is used to query data.

REST Request To access the api you can use the REST controller with the path GET /v1/reservationpaymentbypaymentid/:paymentId

  axios({
    method: 'GET',
    url: `/v1/reservationpaymentbypaymentid/${paymentId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_reservationPayment",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_reservationPayment": {
		"id": "ID",
		"ownerId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "String",
		"statusLiteral": "String",
		"redirectUrl": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Start Reservationpayment` API

Start payment for reservation

Rest Route

The startReservationPayment API REST controller can be triggered via the following route:

/v1/startreservationpayment/:reservationId

Rest Request Parameters

The startReservationPayment api has got 2 regular request parameters

Parameter	Type	Required	Population
reservationId	ID	true	request.params?.[“reservationId”]
paymentUserParams	Object	true	request.body?.[“paymentUserParams”]
reservationId : This id paremeter is used to select the required data object that will be updated
paymentUserParams : The user parameters that should be defined to start a stripe payment process. Must include paymentMethodId.

REST Request To access the api you can use the REST controller with the path PATCH /v1/startreservationpayment/:reservationId

  axios({
    method: 'PATCH',
    url: `/v1/startreservationpayment/${reservationId}`,
    data: {
            paymentUserParams:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"paymentResult": {
		"paymentTicketId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "Enum",
		"paymentIntentInfo": "Object",
		"statusLiteral": "String",
		"amount": "Double",
		"currency": "String",
		"success": true,
		"description": "String",
		"metadata": "Object",
		"paymentUserParams": "Object"
	}
}

`Refresh Reservationpayment` API

Refresh payment info for reservation from Stripe

Rest Route

The refreshReservationPayment API REST controller can be triggered via the following route:

/v1/refreshreservationpayment/:reservationId

Rest Request Parameters

The refreshReservationPayment api has got 2 regular request parameters

Parameter	Type	Required	Population
reservationId	ID	true	request.params?.[“reservationId”]
paymentUserParams	Object	false	request.body?.[“paymentUserParams”]
reservationId : This id paremeter is used to select the required data object that will be updated
paymentUserParams : The user parameters that should be defined to refresh a stripe payment process

REST Request To access the api you can use the REST controller with the path PATCH /v1/refreshreservationpayment/:reservationId

  axios({
    method: 'PATCH',
    url: `/v1/refreshreservationpayment/${reservationId}`,
    data: {
            paymentUserParams:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"paymentResult": {
		"paymentTicketId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "Enum",
		"paymentIntentInfo": "Object",
		"statusLiteral": "String",
		"amount": "Double",
		"currency": "String",
		"success": true,
		"description": "String",
		"metadata": "Object",
		"paymentUserParams": "Object"
	}
}

`Callback Reservationpayment` API

Refresh payment values by gateway webhook call for reservation

Rest Route

The callbackReservationPayment API REST controller can be triggered via the following route:

/v1/callbackreservationpayment

Rest Request Parameters

The callbackReservationPayment api has got 1 regular request parameter

Parameter	Type	Required	Population
reservationId	ID	false	request.body?.[“reservationId”]
reservationId : The order id parameter that will be read from webhook callback params

REST Request To access the api you can use the REST controller with the path POST /v1/callbackreservationpayment

  axios({
    method: 'POST',
    url: '/v1/callbackreservationpayment',
    data: {
            reservationId:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "POST",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"paymentResult": {
		"paymentTicketId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "Enum",
		"paymentIntentInfo": "Object",
		"statusLiteral": "String",
		"amount": "Double",
		"currency": "String",
		"success": true,
		"description": "String",
		"metadata": "Object",
		"paymentUserParams": "Object"
	}
}

`Get Paymentcustomerbyuserid` API

This route is used to get the payment customer information by user id.

Rest Route

The getPaymentCustomerByUserId API REST controller can be triggered via the following route:

/v1/paymentcustomers/:userId

Rest Request Parameters

The getPaymentCustomerByUserId api has got 1 regular request parameter

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
userId : An ID value to represent the user who is created as a stripe customer. The parameter is used to query data.

REST Request To access the api you can use the REST controller with the path GET /v1/paymentcustomers/:userId

  axios({
    method: 'GET',
    url: `/v1/paymentcustomers/${userId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_paymentCustomer",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_paymentCustomer": {
		"id": "ID",
		"userId": "ID",
		"customerId": "String",
		"platform": "String",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Paymentcustomers` API

This route is used to list all payment customers.

Rest Route

The listPaymentCustomers API REST controller can be triggered via the following route:

/v1/paymentcustomers

Rest Request Parameters

Filter Parameters

The listPaymentCustomers api supports 3 optional filter parameters for filtering list results:

userId (ID): An ID value to represent the user who is created as a stripe customer

Single: ?userId=<value>
Multiple: ?userId=<value1>&userId=<value2>
Null: ?userId=null

customerId (String): A string value to represent the customer id which is generated on the Stripe gateway. This id is used to represent the customer in the Stripe gateway

Single (partial match, case-insensitive): ?customerId=<value>
Multiple: ?customerId=<value1>&customerId=<value2>
Null: ?customerId=null

platform (String): A String value to represent payment platform which is used to make the payment. It is stripe as default. It will be used to distinguesh the payment gateways in the future.

Single (partial match, case-insensitive): ?platform=<value>
Multiple: ?platform=<value1>&platform=<value2>
Null: ?platform=null

REST Request To access the api you can use the REST controller with the path GET /v1/paymentcustomers

  axios({
    method: 'GET',
    url: '/v1/paymentcustomers',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // userId: '<value>' // Filter by userId
        // customerId: '<value>' // Filter by customerId
        // platform: '<value>' // Filter by platform
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_paymentCustomers",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_paymentCustomers": [
		{
			"id": "ID",
			"userId": "ID",
			"customerId": "String",
			"platform": "String",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`List Paymentcustomermethods` API

This route is used to list all payment customer methods.

Rest Route

The listPaymentCustomerMethods API REST controller can be triggered via the following route:

/v1/paymentcustomermethods/:userId

Rest Request Parameters

The listPaymentCustomerMethods api has got 1 regular request parameter

Parameter	Type	Required	Population
userId	ID	true	request.params?.[“userId”]
userId : An ID value to represent the user who owns the payment method. The parameter is used to query data.

Filter Parameters

The listPaymentCustomerMethods api supports 6 optional filter parameters for filtering list results:

paymentMethodId (String): A string value to represent the id of the payment method on the payment platform.

Single (partial match, case-insensitive): ?paymentMethodId=<value>
Multiple: ?paymentMethodId=<value1>&paymentMethodId=<value2>
Null: ?paymentMethodId=null

customerId (String): A string value to represent the customer id which is generated on the payment gateway.

Single (partial match, case-insensitive): ?customerId=<value>
Multiple: ?customerId=<value1>&customerId=<value2>
Null: ?customerId=null

cardHolderName (String): A string value to represent the name of the card holder. It can be different than the registered customer.

Single (partial match, case-insensitive): ?cardHolderName=<value>
Multiple: ?cardHolderName=<value1>&cardHolderName=<value2>
Null: ?cardHolderName=null

cardHolderZip (String): A string value to represent the zip code of the card holder. It is used for address verification in specific countries.

Single (partial match, case-insensitive): ?cardHolderZip=<value>
Multiple: ?cardHolderZip=<value1>&cardHolderZip=<value2>
Null: ?cardHolderZip=null

platform (String): A String value to represent payment platform which teh paymentMethod belongs. It is stripe as default. It will be used to distinguesh the payment gateways in the future.

Single (partial match, case-insensitive): ?platform=<value>
Multiple: ?platform=<value1>&platform=<value2>
Null: ?platform=null

cardInfo (Object): A Json value to store the card details of the payment method.

Single: ?cardInfo=<value>
Multiple: ?cardInfo=<value1>&cardInfo=<value2>
Null: ?cardInfo=null

REST Request To access the api you can use the REST controller with the path GET /v1/paymentcustomermethods/:userId

  axios({
    method: 'GET',
    url: `/v1/paymentcustomermethods/${userId}`,
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // paymentMethodId: '<value>' // Filter by paymentMethodId
        // customerId: '<value>' // Filter by customerId
        // cardHolderName: '<value>' // Filter by cardHolderName
        // cardHolderZip: '<value>' // Filter by cardHolderZip
        // platform: '<value>' // Filter by platform
        // cardInfo: '<value>' // Filter by cardInfo
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_paymentMethods",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_paymentMethods": [
		{
			"id": "ID",
			"paymentMethodId": "String",
			"userId": "ID",
			"customerId": "String",
			"cardHolderName": "String",
			"cardHolderZip": "String",
			"platform": "String",
			"cardInfo": "Object",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 10 - BookingManagement Service Reservation Payment Flow

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

Stripe Payment Flow For Reservation

Reservation is a data object that stores order information used for Stripe payments. The payment flow can only start after an instance of this data object is created in the database.

The ID of this data object—referenced as reservationId in the general business logic—will be used as the orderId in the payment flow.

Accessing the service API for the payment flow API

The Airbnb application doesn’t have a separate payment service; the payment flow is handled within the same service that manages orders. To access the related APIs, use the base URL of the bookingManagement service. Note that the application may be deployed to Preview, Staging, or Production. As with all API access, you should call the API using the base URL for the selected deployment.

For the bookingManagement service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/bookingmanagement-api
Staging: https://airbnb3-stage.mindbricks.co/bookingmanagement-api
Production: https://airbnb3.mindbricks.co/bookingmanagement-api

Creating the Reservation

While creating the reservation instance is part of the business logic and can be implemented according to your architecture, this instance acts as the central hub for the payment flow and its related data objects. The order object is typically created via its own API (see the Business API for the create route of reservation). The payment flow begins after the object is created.

Because of the data object’s Stripe order settings, the payment flow is aware of the following fields, references, and their purposes:

id (used as orderId or ${dataObject.objectName}Id): The unique identifier of the data object instance at the center of the payment flow.
orderIdProperty: The order identifier is read from the id property of the data object.
description: The payment description is resolved from runMScript(() => (Booking for Listing: ${this.reservation.listingId}, Guest: ${this.reservation.guestId}, Dates: ${this.reservation.checkIn} to ${this.reservation.checkOut}), {"path":"services[3].dataObjects[0].objectSettings.stripeOrder.configuration.description"}).
orderStatusProperty: bookingStatus is updated automatically by the payment flow using a mapped status value.
orderStatusUpdateDateProperty: updatedAt stores the timestamp of the latest payment status update.
orderOwnerIdProperty: guestId is used by the payment flow to verify the order owner and match it with the current user’s ID.
mapPaymentResultToOrderStatus: The order status is written to the data object instance using the following mapping.
paymentResultStarted: runMScript(() => ("pending"), {"path":"services[3].dataObjects[0].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultStarted"})
paymentResultCanceled: runMScript(() => ("cancelled"), {"path":"services[3].dataObjects[0].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultCanceled"})
paymentResultFailed: runMScript(() => ("declined"), {"path":"services[3].dataObjects[0].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultFailed"})
paymentResultSuccess: runMScript(() => (this.reservation.approvalType === 0 ? "complete" : "confirmed"), {"path":"services[3].dataObjects[0].objectSettings.stripeOrder.configuration.mapPaymentResultToOrderStatus.paymentResultSuccess"})

Before Payment Flow Starts

It is assumed that the frontend provides a “Pay” or “Checkout” button that initiates the payment flow. The following steps occur after the user clicks this button.
Note that an reservation instance must already exist to represent the order being paid, with its initial status set.

A Stripe payment flow can be implemented in several ways, but the best practice is to use a PaymentIntent and manage it jointly from the backend and frontend.
A PaymentIntent represents the intent to collect payment for a given order (or any payable entity).
In the Airbnb application, the PaymentIntent is created in the backend, while the PaymentMethod (the user’s stored card information) is created in the frontend.
Only the PaymentMethod ID and minimal metadata are stored in the backend for later reference.

The frontend first requests the current user’s saved payment methods from the backend, displays them in a list, and provides UI options to add or remove payment methods.
The user must select a Payment Method before starting the payment flow.

Listing the Payment Methods for the User

To list the payment methods of the currently logged-in user, call the following system API (unversioned):

GET /payment-methods/list

This endpoint requires no parameters and returns an array of payment methods belonging to the user — without any envelope.

const response = await fetch("$serviceUrl/payment-methods/list", {
  method: "GET",
  headers: { "Content-Type": "application/json" },
});

Example response:

[
  {
    "id": "19a5fbfd-3c25-405b-a7f7-06f023f2ca01",
    "paymentMethodId": "pm_1SQv9CP5uUv56Cse5BQ3nGW8",
    "userId": "f7103b85-fcda-4dec-92c6-c336f71fd3a2",
    "customerId": "cus_TNgWUw5QkmUPLa",
    "cardHolderName": "John Doe",
    "cardHolderZip": "34662",
    "platform": "stripe",
    "cardInfo": {
      "brand": "visa",
      "last4": "4242",
      "checks": {
        "cvc_check": "pass",
        "address_postal_code_check": "pass"
      },
      "funding": "credit",
      "exp_month": 11,
      "exp_year": 2033
    },
    "isActive": true,
    "createdAt": "2025-11-07T19:16:38.469Z",
    "updatedAt": "2025-11-07T19:16:38.469Z",
    "_owner": "f7103b85-fcda-4dec-92c6-c336f71fd3a2"
  }
]

In each payment method object, the following fields are useful for displaying to the user:

for (const method of paymentMethods) {
  const brand = method.cardInfo.brand; // use brand for displaying VISA/MASTERCARD icons
  const paymentMethodId = method.paymentMethodId; // send this when initiating the payment flow
  const cardHolderName = method.cardHolderName; // show in list
  const number = `**** **** **** ${method.cardInfo.last4}`; // masked card number
  const expDate = `${method.cardInfo.exp_month}/${method.cardInfo.exp_year}`; // expiry date
  const id = method.id; // internal DB record ID, used for deletion
  const customerId = method.customerId; // Stripe customer reference
}

If the list is empty, prompt the user to add a new payment method.

Creating a Payment Method

The payment page (or user profile page) should allow users to add a new payment method (credit card). Creating a Payment Method is a secure operation handled entirely through Stripe.js on the frontend — the backend never handles sensitive card data. After a card is successfully created, the backend only stores its reference (PaymentMethod ID) for reuse.

Stripe provides multiple ways to collect card information, all through secure UI elements. Below is an example setup — refer to the latest Stripe documentation for alternative patterns.

To initialize Stripe on the frontend, include your public key:

<script src="https://js.stripe.com/v3/?advancedFraudSignals=false"></script>

const stripe = Stripe("pk_test_51POkqt4..................");
const elements = stripe.elements();

const cardNumberElement = elements.create("cardNumber", {
  style: { base: { color: "#545454", fontSize: "16px" } },
});
cardNumberElement.mount("#card-number-element");

const cardExpiryElement = elements.create("cardExpiry", {
  style: { base: { color: "#545454", fontSize: "16px" } },
});
cardExpiryElement.mount("#card-expiry-element");

const cardCvcElement = elements.create("cardCvc", {
  style: { base: { color: "#545454", fontSize: "16px" } },
});
cardCvcElement.mount("#card-cvc-element");

// Note: cardholder name and ZIP code are collected via non-Stripe inputs (not secure).

You can dynamically show the card brand while typing:

cardNumberElement.on("change", (event) => {
  const cardBrand = event.brand;
  const cardNumberDiv = document.getElementById("card-number-element");
  cardNumberDiv.style.backgroundImage = getBrandImageUrl(cardBrand);
});

Once the user completes the card form, create the Payment Method on Stripe. Note that the expiry and CVC fields are securely handled by Stripe.js and are never readable from your code.

const { paymentMethod, error } = await stripe.createPaymentMethod({
  type: "card",
  card: cardNumberElement,
  billing_details: {
    name: cardholderName.value,
    address: { postal_code: cardholderZip.value },
  },
});

When a paymentMethod is successfully created, send its ID to your backend to attach it to the logged-in user’s account.

Use the system API (unversioned):

POST /payment-methods/add

Example:

const response = await fetch("$serviceUrl/payment-methods/add", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ paymentMethodId: paymentMethod.id }),
});

When addPaymentMethod is called, the backend retrieves or creates the user’s Stripe Customer ID, attaches the Payment Method to that customer, and stores the reference in the local database for future use.

Example response:

{
  "isActive": true,
  "cardHolderName": "John Doe",
  "userId": "f7103b85-fcda-4dec-92c6-c336f71fd3a2",
  "customerId": "cus_TNgWUw5QkmUPLa",
  "paymentMethodId": "pm_1SQw5aP5uUv56CseDGzT1dzP",
  "platform": "stripe",
  "cardHolderZip": "34662",
  "cardInfo": {
    "brand": "visa",
    "last4": "4242",
    "funding": "credit",
    "exp_month": 11,
    "exp_year": 2033
  },
  "id": "19a5ff70-4986-4760-8fc4-6b591bd6bbbf",
  "createdAt": "2025-11-07T20:16:55.451Z",
  "updatedAt": "2025-11-07T20:16:55.451Z"
}

You can append this new entry directly to the UI list or refresh the list using the listPaymentMethods API.

Deleting a Payment Method

To remove a saved payment method from the current user’s account, call the system API (unversioned):

DELETE /payment-methods/delete/:paymentMethodId

Example:

await fetch(
  `$serviceUrl/payment-methods/delete/${paymentMethodId}`,
  {
    method: "DELETE",
    headers: { "Content-Type": "application/json" },
  }
);

Starting the Payment Flow in Backend — Creation and Confirmation of the PaymentIntent Object

The payment flow is initiated in the backend through the startReservationPayment API.
This API must be called with one of the user’s existing payment methods. Therefore, ensure that the frontend forces the user to select a payment method before initiating the payment.

The startReservationPayment API is a versioned Business Logic API and follows the same structure as other business APIs.

In the Airbnb application, the payment flow starts by creating a Stripe PaymentIntent and confirming it in a single step within the backend.
In a typical (“happy”) path, when the startReservationPayment API is called, the response will include a successful or failed PaymentIntent result inside the paymentResult object, along with the reservation object.

However, in certain edge cases—such as when 3D Secure (3DS) or other bank-level authentication is required—the confirmation step cannot complete immediately.
In such cases, control should return to a frontend page to allow the user to finish the process.
To enable this, a return_url must be provided during the PaymentIntent creation step.

Although technically optional, it is strongly recommended to include a return_url.
This ensures that the frontend payment result page can display both successful and failed payments and complete flows that require user interaction.
The return_url must be a frontend URL.

The paymentUserParams parameter of the startReservationPayment API contains the data necessary to create the Stripe PaymentIntent.

Call the API as follows:

const response = await fetch(
  `$serviceUrl/v1/startreservationpayment/${orderId}`,
  {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      paymentUserParams: {
        paymentMethodId,
        return_url: `${yourFrontendReturnUrl}`,
      },
    }),
  }
);

The API response will contain a paymentResult object. If an error occurs, it will begin with { "result": "ERR" }. Otherwise, it will include the PaymentIntent information:

{
  "paymentResult": {
    "success": true,
    "paymentTicketId": "19a60f8f-eeff-43a2-9954-58b18839e1da",
    "orderId": "19a60f84-56ee-40c4-b9c1-392f83877838",
    "paymentId": "pi_3SR0UHP5uUv56Cse1kwQWCK8",
    "paymentStatus": "succeeded",
    "paymentIntentInfo": {
      "paymentIntentId": "pi_3SR0UHP5uUv56Cse1kwQWCK8",
      "clientSecret": "pi_3SR0UHP5uUv56Cse1kwQWCK8_secret_PTc3DriD0YU5Th4isBepvDWdg",
      "publicKey": "pk_test_51POkqWP5uU",
      "status": "succeeded"
    },
    "statusLiteral": "success",
    "amount": 10,
    "currency": "USD",
    "description": "Your credit card is charged for babilOrder for 10",
    "metadata": {
      "order": "Purchase-Purchase-order",
      "orderId": "19a60f84-56ee-40c4-b9c1-392f83877838",
      "checkoutName": "babilOrder"
    },
    "paymentUserParams": {
      "paymentMethodId": "pm_1SQw5aP5uUv56CseDGzT1dzP",
      "return_url": "${yourFrontendReturnUrl}"
    }
  }
}

`Start Reservationpayment` API

Start payment for reservation

Rest Route

The startReservationPayment API REST controller can be triggered via the following route:

/v1/startreservationpayment/:reservationId

Rest Request Parameters

The startReservationPayment api has got 2 regular request parameters

Parameter	Type	Required	Population
reservationId	ID	true	request.params?.[“reservationId”]
paymentUserParams	Object	true	request.body?.[“paymentUserParams”]
reservationId : This id paremeter is used to select the required data object that will be updated
paymentUserParams : The user parameters that should be defined to start a stripe payment process. Must include paymentMethodId.

REST Request To access the api you can use the REST controller with the path PATCH /v1/startreservationpayment/:reservationId

  axios({
    method: 'PATCH',
    url: `/v1/startreservationpayment/${reservationId}`,
    data: {
            paymentUserParams:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reservation",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"reservation": {
		"id": "ID",
		"listingId": "ID",
		"approvalType": "Enum",
		"approvalType_idx": "Integer",
		"bookingStatus": "Enum",
		"bookingStatus_idx": "Integer",
		"hostId": "ID",
		"checkOut": "Date",
		"guestId": "ID",
		"checkIn": "Date",
		"currency": "String",
		"guestCount": "Integer",
		"totalPrice": "Double",
		"iCalExportUrl": "String",
		"disputeStatus": "Enum",
		"disputeStatus_idx": "Integer",
		"bookingPoliciesSnapshot": "Object",
		"iCalImportSource": "String",
		"cancellationPolicySnapshot": "Object",
		"paymentConfirmation": "Enum",
		"paymentConfirmation_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"paymentResult": {
		"paymentTicketId": "ID",
		"orderId": "ID",
		"paymentId": "String",
		"paymentStatus": "Enum",
		"paymentIntentInfo": "Object",
		"statusLiteral": "String",
		"amount": "Double",
		"currency": "String",
		"success": true,
		"description": "String",
		"metadata": "Object",
		"paymentUserParams": "Object"
	}
}

Analyzing the API Response

After calling the startReservationPayment API, the most common expected outcome is a confirmed and completed payment. However, several alternate cases should be handled on the frontend.

System Error Case

The API may return a classic service-level error (unrelated to payment). Check the HTTP status code of the response. It should be 200 or 201. Any 400, 401, 403, or 404 indicates a system error.

{
  "result": "ERR",
  "status": 404,
  "message": "Record not found",
  "date": "2025-11-08T00:57:54.820Z"
}

Handle system errors on the payment page (show a retry option). Do not navigate to the result page.

Payment Error Case

The API performs both database operations and the Stripe payment operation. If the payment fails but the service logic succeeds, the API may still return a 200 OK status, with the failure recorded in the paymentResult.

In this case, show an error message and allow the user to retry.

{
  "status": "OK",
  "statusCode": "200",
  "reservation": {
    "id": "19a60f8f-eeff-43a2-9954-58b18839e1da",
    "status": "failed"
  },
  "paymentResult": {
    "result": "ERR",
    "status": 500,
    "message": "Stripe error message: Your card number is incorrect.",
    "errCode": "invalid_number",
    "date": "2025-11-08T00:57:54.820Z"
  }
}

Payment errors should be handled on the payment page (retry option). Do not go to the result page.

Happy Case

When both the service and payment result succeed, this is considered the happy path. In this case, use the reservation and paymentResult objects in the response to display a success message to the user.

amount and description values are included to help you show payment details on the result page.

{
  "status": "OK",
  "statusCode": "200",
  "order": {
    "id": "19a60f8f-eeff-43a2-9954-58b18839e1da",
    "status": "paid"
  },
  "paymentResult": {
    "success": true,
    "paymentStatus": "succeeded",
    "paymentIntentInfo": {
      "status": "succeeded"
    },
    "amount": 10,
    "currency": "USD",
    "description": "Your credit card is charged for babilOrder for 10"
  }
}

To verify success:

if (paymentResult.paymentIntentInfo.status === "succeeded") {
  // Redirect to result page
}

Note: A successful result does not trigger fulfillment immediately. Fulfillment begins only after the Stripe webhook updates the database. It’s recommended to show a short “success” toast, wait a few milliseconds, and then navigate to the result page.

Handle the happy case in the result page by sending the reservationId and the payment intent secret.

const orderId = new URLSearchParams(window.location.search).get("orderId");
const url = new URL(`$yourResultPageUrl`, location.origin);
url.searchParams.set("orderId", orderId);
url.searchParams.set("payment_intent_client_secret", currentPaymentIntent.clientSecret);
setTimeout(() => { window.location.href = url.toString(); }, 600);

Edge Cases

Although startReservationPayment is designed to handle both creation and confirmation in one step, Stripe may return an incomplete result if third-party authentication or redirect steps are required.

You must handle these cases in both the payment page and the result page, because some next actions are available immediately, while others occur only after a redirect.

If the paymentIntentInfo.status equals "requires_action", handle it using Stripe.js as shown below:

if (paymentResult.paymentIntentInfo.status === "requires_action") {
  await runNextAction(
    paymentResult.paymentIntentInfo.clientSecret,
    paymentResult.paymentIntentInfo.publicKey
  );
}

Helper function:

async function runNextAction(clientSecret, publicKey) {
  const stripe = Stripe(publicKey);
  const { error } = await stripe.handleNextAction({ clientSecret });
  if (error) {
    console.log("next_action error:", error);
    showToast(error.code + ": " + error.message, "fa-circle-xmark text-red-500");
    throw new Error(error.message);
  }
}

After handling the next action, re-fetch the PaymentIntent from Stripe, evaluate its status, show appropriate feedback, and navigate to the result page.

const { paymentIntent } = await stripe.retrievePaymentIntent(clientSecret);

if (paymentIntent.status === "succeeded") {
  showToast("Payment successful!", "fa-circle-check text-green-500");
} else if (paymentIntent.status === "processing") {
  showToast("Payment is processing…", "fa-circle-info text-blue-500");
} else if (paymentIntent.status === "requires_payment_method") {
  showToast("Payment failed. Try another card.", "fa-circle-xmark text-red-500");
}

const orderId = new URLSearchParams(window.location.search).get("orderId");
const url = new URL(`$yourResultPageUrl`, location.origin);
url.searchParams.set("orderId", orderId);
url.searchParams.set("payment_intent_client_secret", currentPaymentIntent.clientSecret);
setTimeout(() => { window.location.href = url.toString(); }, 600);

The Result Page

The payment result page should handle the following steps:

Read orderId and payment_intent_client_secret from the query parameters.
Retrieve the PaymentIntent from Stripe and check its status.
If required, handle any next_action and re-fetch the PaymentIntent.
If the status is "succeeded", display a clear visual confirmation.
Fetch the reservation instance from the backend to display any additional order or fulfillment details.

Note that paymentIntent status only gives information about the Stripe side. The reservation instance in the service should also ve updated to start the fulfillment. In most cases, the startreservationPayment api updates the status of the order using the response of the paymentIntent confirmation, but as stated above in some cases this update can be done only when the webhook executes. So in teh result page always get the final payment status in the `reservation.

To ensure that service i To fetch the reservation instance, you van use the related api which is given before, and to ensure that the service is updated with the latest status read the paymentConfirmation field of the reservation instance.

if (reservation.paymentConfirmation == "canceled") {
  // the payment is canceled, user can be informed that they should try again
} if (reservation.paymentConfirmation == "paid") {
  // service knows that payment is done, user can be informed that fullfillment started
} else {
  // it may be pending, processing
  // Fetch the object again until a canceled or paid status
}

Payment Flow via MCP (AI Chat Integration)

The payment flow is also accessible through the MCP (Model Context Protocol) AI chat interface. The bookingManagement service exposes an initiatePayment MCP tool that the AI can call when the user wants to pay for an order.

How initiatePayment Works in MCP

User asks to pay — e.g., “I want to pay for my order”
AI calls initiatePayment MCP tool with orderId (and orderType if multiple order types exist)
Tool validates the order exists, is payable, and the user is authorized
Tool returns __frontendAction with type: "payment" — this is NOT a direct payment execution
Frontend chat UI renders a PaymentActionCard with a “Pay Now” button
User clicks “Pay Now” — the frontend opens a payment modal with CheckoutForm
Standard Stripe flow proceeds (payment method selection, 3DS handling, etc.)

Frontend Action Response Format

The initiatePayment MCP tool returns:

{
  "__frontendAction": {
    "type": "payment",
    "orderId": "uuid",
    "orderType": "reservation",
    "serviceName": "bookingManagement",
    "amount": 99.99,
    "currency": "USD",
    "description": "Order description"
  },
  "message": "Payment is ready. Click the button below to proceed."
}

MCP Client Architecture

The frontend communicates with MCP tools through the MCP BFF (Backend-for-Frontend) service. The MCP BFF aggregates tool calls across all backend services and provides:

SSE Streaming: Chat messages stream via /api/chat/stream with event types: start, text, tool_start, tool_executing, tool_result, error, done
Tool Result Extraction: The frontend’s MessageBubble component inspects tool results for __frontendAction fields
Action Dispatch: The ActionCard component dispatches to type-specific cards (e.g., PaymentActionCard for type: "payment")

The PaymentActionCard component handles the rest: fetching order details, rendering the payment UI, and completing the Stripe checkout flow — all within the chat interface.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 11 - ReviewSystem Service

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides extensive instruction for the usage of reviewSystem

Service Access

ReviewSystem service management is handled through service specific base urls.

ReviewSystem service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the reviewSystem service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/reviewsystem-api
Staging: https://airbnb3-stage.mindbricks.co/reviewsystem-api
Production: https://airbnb3.mindbricks.co/reviewsystem-api

Scope

ReviewSystem Service Description

Handles double-blind, moderated reviews and rating aggregation for stays. Allows guests/hosts to review each other and listings, supports moderation, and exposes aggregate stats for listings/profiles…

ReviewSystem service provides apis and business logic for following data objects in airbnb application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows.

reviewAggregate Data Object: Cached aggregate rating stats for a listing, host, or guest. Used for fast lookup and display of averages, counts, etc.

review Data Object: Review submitted by a guest or host after a completed stay. Enables double-blind, supports moderation, and links to reservation/listing and users.

API Structure

Object Structure of a Successful Response

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

ReviewAggregate Data Object

Cached aggregate rating stats for a listing, host, or guest. Used for fast lookup and display of averages, counts, etc.

ReviewAggregate Data Object Properties

ReviewAggregate data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`revieweeId`	ID	false	Yes	No	-
`revieweeType`	Enum	false	Yes	No	-
`averageRating`	Double	false	Yes	No	-
`reviewCount`	Integer	false	Yes	No	-
`visibilityStatus`	Enum	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

revieweeType: [host, guest, listing]
visibilityStatus: [public, hidden]

Relation Properties

revieweeId

In frontend, please ensure that,

revieweeId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

Filter Properties

revieweeId revieweeType

revieweeId: ID has a filter named revieweeId
revieweeType: Enum has a filter named revieweeType

Review Data Object

Review submitted by a guest or host after a completed stay. Enables double-blind, supports moderation, and links to reservation/listing and users.

Review Data Object Properties

Review data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`moderationStatus`	Enum	false	Yes	No	-
`isPublished`	Boolean	false	Yes	No	-
`reviewText`	Text	false	Yes	No	-
`rating`	Integer	false	Yes	No	-
`blindSubmissionCode`	String	false	Yes	No	-
`revieweeId`	ID	false	Yes	No	-
`reservationId`	ID	false	Yes	No	-
`reviewerId`	ID	false	Yes	No	-
`revieweeType`	Enum	false	Yes	No	-
`submittedAt`	Date	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

moderationStatus: [pending, approved, rejected]
revieweeType: [host, guest, listing]

Relation Properties

revieweeId reservationId reviewerId

In frontend, please ensure that,

revieweeId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: No

reservationId: ID Relation to reservation.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

reviewerId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Filter Properties

revieweeId reservationId reviewerId revieweeType

revieweeId: ID has a filter named revieweeId
reservationId: ID has a filter named reservationId
reviewerId: ID has a filter named reviewerId
revieweeType: Enum has a filter named revieweeType

Default CRUD APIs

ReviewAggregate Default APIs

Operation	API Name	Route	Explicitly Set
Create	none	-	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	`getReviewAggregate`	`/v1/reviewaggregates/:reviewAggregateId`	Auto
List	`listReviewAggregates`	`/v1/reviewaggregates`	Auto

Review Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createReview`	`/v1/reviews`	Auto
Update	`updateReview`	`/v1/reviews/:reviewId`	Auto
Delete	`deleteReview`	`/v1/reviews/:reviewId`	Auto
Get	`getReview`	`/v1/reviews/:reviewId`	Auto
List	`listReviews`	`/v1/reviews`	Auto

API Reference

`Get Review` API

Retrieve a review and, if double-blind complete, return full info. Enrich with reviewer/reviewee & reservation if allowed by publish and moderation/business rules.

Rest Route

The getReview API REST controller can be triggered via the following route:

/v1/reviews/:reviewId

Rest Request Parameters

The getReview api has got 1 regular request parameter

Parameter	Type	Required	Population
reviewId	ID	true	request.params?.[“reviewId”]
reviewId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/reviews/:reviewId

  axios({
    method: 'GET',
    url: `/v1/reviews/${reviewId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "review",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"review": {
		"id": "ID",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"isPublished": "Boolean",
		"reviewText": "Text",
		"rating": "Integer",
		"blindSubmissionCode": "String",
		"revieweeId": "ID",
		"reservationId": "ID",
		"reviewerId": "ID",
		"revieweeType": "Enum",
		"revieweeType_idx": "Integer",
		"submittedAt": "Date",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Reviewaggregates` API

List aggregate rating stats for listings or user profiles (cache-friendly, e.g., for search results or admin export).

Rest Route

The listReviewAggregates API REST controller can be triggered via the following route:

/v1/reviewaggregates

Rest Request Parameters

Filter Parameters

The listReviewAggregates api supports 2 optional filter parameters for filtering list results:

revieweeId (ID): Filter by revieweeId

Single: ?revieweeId=<value>
Multiple: ?revieweeId=<value1>&revieweeId=<value2>
Null: ?revieweeId=null

revieweeType (Enum): Filter by revieweeType

Single: ?revieweeType=<value> (case-insensitive)
Multiple: ?revieweeType=<value1>&revieweeType=<value2>
Null: ?revieweeType=null

REST Request To access the api you can use the REST controller with the path GET /v1/reviewaggregates

  axios({
    method: 'GET',
    url: '/v1/reviewaggregates',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // revieweeId: '<value>' // Filter by revieweeId
        // revieweeType: '<value>' // Filter by revieweeType
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reviewAggregates",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"reviewAggregates": [
		{
			"id": "ID",
			"revieweeId": "ID",
			"revieweeType": "Enum",
			"revieweeType_idx": "Integer",
			"averageRating": "Double",
			"reviewCount": "Integer",
			"visibilityStatus": "Enum",
			"visibilityStatus_idx": "Integer",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Review` API

Guest or host submits review for completed reservation. Double-blind: published after both reviews or expiry. Moderation applies. Only allowed if session.user is guest/host of reservation and not already reviewed.

Rest Route

The createReview API REST controller can be triggered via the following route:

/v1/reviews

Rest Request Parameters

The createReview api has got 7 regular request parameters

Parameter	Type	Required	Population
moderationStatus	Enum	true	request.body?.[“moderationStatus”]
isPublished	Boolean	true	request.body?.[“isPublished”]
reviewText	Text	true	request.body?.[“reviewText”]
rating	Integer	true	request.body?.[“rating”]
revieweeId	ID	true	request.body?.[“revieweeId”]
reservationId	ID	true	request.body?.[“reservationId”]
revieweeType	Enum	true	request.body?.[“revieweeType”]
moderationStatus :
isPublished :
reviewText :
rating :
revieweeId :
reservationId :
revieweeType :

REST Request To access the api you can use the REST controller with the path POST /v1/reviews

  axios({
    method: 'POST',
    url: '/v1/reviews',
    data: {
            moderationStatus:"Enum",  
            isPublished:"Boolean",  
            reviewText:"Text",  
            rating:"Integer",  
            revieweeId:"ID",  
            reservationId:"ID",  
            revieweeType:"Enum",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "review",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"review": {
		"id": "ID",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"isPublished": "Boolean",
		"reviewText": "Text",
		"rating": "Integer",
		"blindSubmissionCode": "String",
		"revieweeId": "ID",
		"reservationId": "ID",
		"reviewerId": "ID",
		"revieweeType": "Enum",
		"revieweeType_idx": "Integer",
		"submittedAt": "Date",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Delete Review` API

Allows hard or soft-delete of review pre-publish (reviewer) or at any time (admin/moderator). Deletion triggers aggregate recalc.

Rest Route

The deleteReview API REST controller can be triggered via the following route:

/v1/reviews/:reviewId

Rest Request Parameters

The deleteReview api has got 1 regular request parameter

Parameter	Type	Required	Population
reviewId	ID	true	request.params?.[“reviewId”]
reviewId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/reviews/:reviewId

  axios({
    method: 'DELETE',
    url: `/v1/reviews/${reviewId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "review",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"review": {
		"id": "ID",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"isPublished": "Boolean",
		"reviewText": "Text",
		"rating": "Integer",
		"blindSubmissionCode": "String",
		"revieweeId": "ID",
		"reservationId": "ID",
		"reviewerId": "ID",
		"revieweeType": "Enum",
		"revieweeType_idx": "Integer",
		"submittedAt": "Date",
		"isActive": false,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Get Reviewaggregate` API

Get aggregate rating stats for listing or user profile (fast lookup cache for UI display).

Rest Route

The getReviewAggregate API REST controller can be triggered via the following route:

/v1/reviewaggregates/:reviewAggregateId

Rest Request Parameters

The getReviewAggregate api has got 1 regular request parameter

Parameter	Type	Required	Population
reviewAggregateId	ID	true	request.params?.[“reviewAggregateId”]
reviewAggregateId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/reviewaggregates/:reviewAggregateId

  axios({
    method: 'GET',
    url: `/v1/reviewaggregates/${reviewAggregateId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reviewAggregate",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"reviewAggregate": {
		"id": "ID",
		"revieweeId": "ID",
		"revieweeType": "Enum",
		"revieweeType_idx": "Integer",
		"averageRating": "Double",
		"reviewCount": "Integer",
		"visibilityStatus": "Enum",
		"visibilityStatus_idx": "Integer",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Reviews` API

List published/approved reviews for listing, host, or guest profile. Double-blind: only list reviews when available (both submitted or timer expired & published). Optional filters: revieweeId, revieweeType, reservationId.

Rest Route

The listReviews API REST controller can be triggered via the following route:

/v1/reviews

Rest Request Parameters

Filter Parameters

The listReviews api supports 4 optional filter parameters for filtering list results:

revieweeId (ID): Filter by revieweeId

Single: ?revieweeId=<value>
Multiple: ?revieweeId=<value1>&revieweeId=<value2>
Null: ?revieweeId=null

reservationId (ID): Filter by reservationId

Single: ?reservationId=<value>
Multiple: ?reservationId=<value1>&reservationId=<value2>
Null: ?reservationId=null

reviewerId (ID): Filter by reviewerId

Single: ?reviewerId=<value>
Multiple: ?reviewerId=<value1>&reviewerId=<value2>
Null: ?reviewerId=null

revieweeType (Enum): Filter by revieweeType

Single: ?revieweeType=<value> (case-insensitive)
Multiple: ?revieweeType=<value1>&revieweeType=<value2>
Null: ?revieweeType=null

REST Request To access the api you can use the REST controller with the path GET /v1/reviews

  axios({
    method: 'GET',
    url: '/v1/reviews',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // revieweeId: '<value>' // Filter by revieweeId
        // reservationId: '<value>' // Filter by reservationId
        // reviewerId: '<value>' // Filter by reviewerId
        // revieweeType: '<value>' // Filter by revieweeType
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "reviews",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"reviews": [
		{
			"id": "ID",
			"moderationStatus": "Enum",
			"moderationStatus_idx": "Integer",
			"isPublished": "Boolean",
			"reviewText": "Text",
			"rating": "Integer",
			"blindSubmissionCode": "String",
			"revieweeId": "ID",
			"reservationId": "ID",
			"reviewerId": "ID",
			"revieweeType": "Enum",
			"revieweeType_idx": "Integer",
			"submittedAt": "Date",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Update Review` API

Allows reviewer to edit own review before publish OR admin/mod to update moderation fields. Enforces state business rules.

Rest Route

The updateReview API REST controller can be triggered via the following route:

/v1/reviews/:reviewId

Rest Request Parameters

The updateReview api has got 4 regular request parameters

Parameter	Type	Required	Population
reviewId	ID	true	request.params?.[“reviewId”]
moderationStatus	Enum	false	request.body?.[“moderationStatus”]
isPublished	Boolean	false	request.body?.[“isPublished”]
reviewText	Text	false	request.body?.[“reviewText”]
reviewId : This id paremeter is used to select the required data object that will be updated
moderationStatus :
isPublished :
reviewText :

REST Request To access the api you can use the REST controller with the path PATCH /v1/reviews/:reviewId

  axios({
    method: 'PATCH',
    url: `/v1/reviews/${reviewId}`,
    data: {
            moderationStatus:"Enum",  
            isPublished:"Boolean",  
            reviewText:"Text",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "review",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"review": {
		"id": "ID",
		"moderationStatus": "Enum",
		"moderationStatus_idx": "Integer",
		"isPublished": "Boolean",
		"reviewText": "Text",
		"rating": "Integer",
		"blindSubmissionCode": "String",
		"revieweeId": "ID",
		"reservationId": "ID",
		"reviewerId": "ID",
		"revieweeType": "Enum",
		"revieweeType_idx": "Integer",
		"submittedAt": "Date",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 12 - PlatformAdmin Service

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides extensive instruction for the usage of platformAdmin

Service Access

PlatformAdmin service management is handled through service specific base urls.

PlatformAdmin service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the platformAdmin service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/platformadmin-api
Staging: https://airbnb3-stage.mindbricks.co/platformadmin-api
Production: https://airbnb3.mindbricks.co/platformadmin-api

Scope

PlatformAdmin Service Description

Administrative and compliance management backend for moderation, audit, dispute, financial oversight, localization, and GDPR in the Airbnb-style rental platform.

PlatformAdmin service provides apis and business logic for following data objects in airbnb application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows.

localizationSetting Data Object: Admin-configured valid languages/currencies for site usage and preference.

adminDisputeAction Data Object: Record of an admin's moderation/decision action on a dispute.

apiKey Data Object: Admin-generated API key for internal/external integration—has revocation, audit trail.

financialReport Data Object: System-generated or admin-generated report snapshots of platform financials for a given period (GDPR/tax).

auditLog Data Object: Immutable audit log for recording sensitive admin actions and platform changes.

gdprAction Data Object: Record of individual user GDPR/consent/export/delete request flow. Used for logs, compliance, and controls.

API Structure

Object Structure of a Successful Response

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

LocalizationSetting Data Object

Admin-configured valid languages/currencies for site usage and preference.

LocalizationSetting Data Object Properties

LocalizationSetting data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`languageCode`	String	false	Yes	No	-
`effectiveFrom`	Date	false	No	No	-
`effectiveTo`	Date	false	No	No	-
`currencyCode`	String	false	Yes	No	-
`isCurrencyActive`	Boolean	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Filter Properties

languageCode currencyCode isCurrencyActive

languageCode: String has a filter named languageCode
currencyCode: String has a filter named currencyCode
isCurrencyActive: Boolean has a filter named isCurrencyActive

AdminDisputeAction Data Object

Record of an admin's moderation/decision action on a dispute.

AdminDisputeAction Data Object Properties

AdminDisputeAction data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`disputeId`	ID	false	Yes	No	-
`actionTaken`	String	false	Yes	No	-
`notes`	Text	false	No	No	-
`adminId`	ID	false	Yes	No	-
`outcome`	String	false	No	No	-
`actionDate`	Date	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Relation Properties

disputeId adminId

In frontend, please ensure that,

disputeId: ID Relation to dispute.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

adminId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Filter Properties

disputeId adminId

disputeId: ID has a filter named disputeId
adminId: ID has a filter named adminId

ApiKey Data Object

Admin-generated API key for internal/external integration—has revocation, audit trail.

ApiKey Data Object Properties

ApiKey data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`key`	String	false	Yes	No	-
`active`	Boolean	false	Yes	No	-
`description`	String	false	No	No	-
`revokedAt`	Date	false	No	No	-
`createdBy`	ID	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Relation Properties

createdBy

In frontend, please ensure that,

createdBy: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

FinancialReport Data Object

System-generated or admin-generated report snapshots of platform financials for a given period (GDPR/tax).

FinancialReport Data Object Properties

FinancialReport data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`period`	String	false	Yes	No	-
`cityTaxByLocation`	Object	false	No	No	-
`totalPayouts`	Double	false	Yes	No	-
`createdBy`	ID	false	Yes	No	-
`totalRefunds`	Double	false	Yes	No	-
`currency`	String	false	Yes	No	-
`generatedAt`	Date	false	Yes	No	-
`totalRevenue`	Double	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Relation Properties

createdBy

In frontend, please ensure that,

createdBy: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Filter Properties

period

period: String has a filter named period

AuditLog Data Object

Immutable audit log for recording sensitive admin actions and platform changes.

AuditLog Data Object Properties

AuditLog data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`performedBy`	ID	false	Yes	No	-
`objectId`	ID	false	No	No	-
`details`	Object	false	No	No	-
`ipAddress`	String	false	No	No	-
`actionObject`	String	false	Yes	No	-
`occurredAt`	Date	false	Yes	No	-
`actionType`	String	false	Yes	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Relation Properties

performedBy

In frontend, please ensure that,

performedBy: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Filter Properties

performedBy objectId actionObject occurredAt actionType

performedBy: ID has a filter named performedBy
objectId: ID has a filter named objectId
actionObject: String has a filter named actionObject
occurredAt: Date has a filter named occurredAt
actionType: String has a filter named actionType

GdprAction Data Object

Record of individual user GDPR/consent/export/delete request flow. Used for logs, compliance, and controls.

GdprAction Data Object Properties

GdprAction data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	IsArray	Required	Secret	Description
`requestedAt`	Date	false	Yes	No	-
`status`	Enum	false	Yes	No	-
`actionType`	String	false	Yes	No	-
`userId`	ID	false	Yes	No	-
`processedAt`	Date	false	No	No	-

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

status: [pending, complete, failed]

Relation Properties

userId

In frontend, please ensure that,

userId: ID Relation to user.id

The target object is a parent object, meaning that the relation is a one-to-many relationship from target to this object.

Required: Yes

Default CRUD APIs

LocalizationSetting Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createLocalizationSetting`	`/v1/localizationsettings`	Auto
Update	`updateLocalizationSetting`	`/v1/localizationsettings/:localizationSettingId`	Auto
Delete	none	-	Auto
Get	none	-	Auto
List	`listLocalizationSettings`	`/v1/localizationsettings`	Auto

AdminDisputeAction Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createAdminDisputeAction`	`/v1/admindisputeactions`	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	none	-	Auto
List	`listAdminDisputeActions`	`/v1/admindisputeactions`	Auto

ApiKey Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createApiKey`	`/v1/apikeys`	Auto
Update	`updateApiKey`	`/v1/apikeys/:apiKeyId`	Auto
Delete	none	-	Auto
Get	none	-	Auto
List	`listApiKeys`	`/v1/apikeys`	Auto

FinancialReport Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createFinancialReport`	`/v1/financialreports`	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	`getFinancialReport`	`/v1/financialreports/:financialReportId`	Auto
List	`listFinancialReports`	`/v1/financialreports`	Auto

AuditLog Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createAuditLog`	`/v1/auditlogs`	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	`getAuditLog`	`/v1/auditlogs/:auditLogId`	Auto
List	`listAuditLogs`	`/v1/auditlogs`	Auto

GdprAction Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createGdprAction`	`/v1/gdpractions`	Auto
Update	`updateGdprAction`	`/v1/gdpractions/:gdprActionId`	Auto
Delete	none	-	Auto
Get	none	-	Auto
List	`listGdprActions`	`/v1/gdpractions`	Auto

API Reference

`Get Auditlog` API

Fetch audit log entry by ID (admin only).

Rest Route

The getAuditLog API REST controller can be triggered via the following route:

/v1/auditlogs/:auditLogId

Rest Request Parameters

The getAuditLog api has got 1 regular request parameter

Parameter	Type	Required	Population
auditLogId	ID	true	request.params?.[“auditLogId”]
auditLogId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/auditlogs/:auditLogId

  axios({
    method: 'GET',
    url: `/v1/auditlogs/${auditLogId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "auditLog",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"auditLog": {
		"id": "ID",
		"performedBy": "ID",
		"objectId": "ID",
		"details": "Object",
		"ipAddress": "String",
		"actionObject": "String",
		"occurredAt": "Date",
		"actionType": "String",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`Get Financialreport` API

Retrieve financial/tax report snapshot by ID (admin only).

Rest Route

The getFinancialReport API REST controller can be triggered via the following route:

/v1/financialreports/:financialReportId

Rest Request Parameters

The getFinancialReport api has got 1 regular request parameter

Parameter	Type	Required	Population
financialReportId	ID	true	request.params?.[“financialReportId”]
financialReportId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/financialreports/:financialReportId

  axios({
    method: 'GET',
    url: `/v1/financialreports/${financialReportId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "financialReport",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"financialReport": {
		"id": "ID",
		"period": "String",
		"cityTaxByLocation": "Object",
		"totalPayouts": "Double",
		"createdBy": "ID",
		"totalRefunds": "Double",
		"currency": "String",
		"generatedAt": "Date",
		"totalRevenue": "Double",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`Create Financialreport` API

Snapshot financial and tax data for a period. Immutable after creation.

Rest Route

The createFinancialReport API REST controller can be triggered via the following route:

/v1/financialreports

Rest Request Parameters

The createFinancialReport api has got 7 regular request parameters

Parameter	Type	Required	Population
period	String	true	request.body?.[“period”]
cityTaxByLocation	Object	false	request.body?.[“cityTaxByLocation”]
totalPayouts	Double	true	request.body?.[“totalPayouts”]
createdBy	ID	true	request.body?.[“createdBy”]
totalRefunds	Double	true	request.body?.[“totalRefunds”]
currency	String	true	request.body?.[“currency”]
totalRevenue	Double	true	request.body?.[“totalRevenue”]
period :
cityTaxByLocation :
totalPayouts :
createdBy :
totalRefunds :
currency :
totalRevenue :

REST Request To access the api you can use the REST controller with the path POST /v1/financialreports

  axios({
    method: 'POST',
    url: '/v1/financialreports',
    data: {
            period:"String",  
            cityTaxByLocation:"Object",  
            totalPayouts:"Double",  
            createdBy:"ID",  
            totalRefunds:"Double",  
            currency:"String",  
            totalRevenue:"Double",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "financialReport",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"financialReport": {
		"id": "ID",
		"period": "String",
		"cityTaxByLocation": "Object",
		"totalPayouts": "Double",
		"createdBy": "ID",
		"totalRefunds": "Double",
		"currency": "String",
		"generatedAt": "Date",
		"totalRevenue": "Double",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`List Auditlogs` API

List audit log entries (admin only). Filterable by type, performer, object, date.

Rest Route

The listAuditLogs API REST controller can be triggered via the following route:

/v1/auditlogs

Rest Request Parameters

Filter Parameters

The listAuditLogs api supports 5 optional filter parameters for filtering list results:

performedBy (ID): Filter by performedBy

Single: ?performedBy=<value>
Multiple: ?performedBy=<value1>&performedBy=<value2>
Null: ?performedBy=null

objectId (ID): Filter by objectId

Single: ?objectId=<value>
Multiple: ?objectId=<value1>&objectId=<value2>
Null: ?objectId=null

actionObject (String): Filter by actionObject

Single (partial match, case-insensitive): ?actionObject=<value>
Multiple: ?actionObject=<value1>&actionObject=<value2>
Null: ?actionObject=null

occurredAt (Date): Filter by occurredAt

Single date: ?occurredAt=2024-01-15
Multiple dates: ?occurredAt=2024-01-15&occurredAt=2024-01-20
Special: $today, $ltoday, $week, $lweek, $month, $leq-<date>, $lin-<date>
Null: ?occurredAt=null

actionType (String): Filter by actionType

Single (partial match, case-insensitive): ?actionType=<value>
Multiple: ?actionType=<value1>&actionType=<value2>
Null: ?actionType=null

REST Request To access the api you can use the REST controller with the path GET /v1/auditlogs

  axios({
    method: 'GET',
    url: '/v1/auditlogs',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // performedBy: '<value>' // Filter by performedBy
        // objectId: '<value>' // Filter by objectId
        // actionObject: '<value>' // Filter by actionObject
        // occurredAt: '<value>' // Filter by occurredAt
        // actionType: '<value>' // Filter by actionType
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "auditLogs",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"auditLogs": [
		{
			"id": "ID",
			"performedBy": "ID",
			"objectId": "ID",
			"details": "Object",
			"ipAddress": "String",
			"actionObject": "String",
			"occurredAt": "Date",
			"actionType": "String",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`List Financialreports` API

List period financial/tax reports for admin/AUDIT purposes.

Rest Route

The listFinancialReports API REST controller can be triggered via the following route:

/v1/financialreports

Rest Request Parameters

Filter Parameters

The listFinancialReports api supports 1 optional filter parameter for filtering list results:

period (String): Filter by period

Single (partial match, case-insensitive): ?period=<value>
Multiple: ?period=<value1>&period=<value2>
Null: ?period=null

REST Request To access the api you can use the REST controller with the path GET /v1/financialreports

  axios({
    method: 'GET',
    url: '/v1/financialreports',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // period: '<value>' // Filter by period
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "financialReports",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"financialReports": [
		{
			"id": "ID",
			"period": "String",
			"cityTaxByLocation": "Object",
			"totalPayouts": "Double",
			"createdBy": "ID",
			"totalRefunds": "Double",
			"currency": "String",
			"generatedAt": "Date",
			"totalRevenue": "Double",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Auditlog` API

Record an admin/platform action/event in the audit log. Called from side-effect flows, not direct user.

Rest Route

The createAuditLog API REST controller can be triggered via the following route:

/v1/auditlogs

Rest Request Parameters

The createAuditLog api has got 6 regular request parameters

Parameter	Type	Required	Population
performedBy	ID	true	request.body?.[“performedBy”]
objectId	ID	false	request.body?.[“objectId”]
details	Object	false	request.body?.[“details”]
ipAddress	String	false	request.body?.[“ipAddress”]
actionObject	String	true	request.body?.[“actionObject”]
actionType	String	true	request.body?.[“actionType”]
performedBy :
objectId :
details :
ipAddress :
actionObject :
actionType :

REST Request To access the api you can use the REST controller with the path POST /v1/auditlogs

  axios({
    method: 'POST',
    url: '/v1/auditlogs',
    data: {
            performedBy:"ID",  
            objectId:"ID",  
            details:"Object",  
            ipAddress:"String",  
            actionObject:"String",  
            actionType:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "auditLog",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"auditLog": {
		"id": "ID",
		"performedBy": "ID",
		"objectId": "ID",
		"details": "Object",
		"ipAddress": "String",
		"actionObject": "String",
		"occurredAt": "Date",
		"actionType": "String",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`Create Localizationsetting` API

Add a supported language/currency for global usage.

Rest Route

The createLocalizationSetting API REST controller can be triggered via the following route:

/v1/localizationsettings

Rest Request Parameters

The createLocalizationSetting api has got 5 regular request parameters

Parameter	Type	Required	Population
languageCode	String	true	request.body?.[“languageCode”]
effectiveFrom	Date	false	request.body?.[“effectiveFrom”]
effectiveTo	Date	false	request.body?.[“effectiveTo”]
currencyCode	String	true	request.body?.[“currencyCode”]
isCurrencyActive	Boolean	true	request.body?.[“isCurrencyActive”]
languageCode :
effectiveFrom :
effectiveTo :
currencyCode :
isCurrencyActive :

REST Request To access the api you can use the REST controller with the path POST /v1/localizationsettings

  axios({
    method: 'POST',
    url: '/v1/localizationsettings',
    data: {
            languageCode:"String",  
            effectiveFrom:"Date",  
            effectiveTo:"Date",  
            currencyCode:"String",  
            isCurrencyActive:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "localizationSetting",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"localizationSetting": {
		"id": "ID",
		"languageCode": "String",
		"effectiveFrom": "Date",
		"effectiveTo": "Date",
		"currencyCode": "String",
		"isCurrencyActive": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Admindisputeactions` API

List all moderation/decision records by admins for disputes. Filter by disputeId/adminId.

Rest Route

The listAdminDisputeActions API REST controller can be triggered via the following route:

/v1/admindisputeactions

Rest Request Parameters

Filter Parameters

The listAdminDisputeActions api supports 2 optional filter parameters for filtering list results:

disputeId (ID): Filter by disputeId

Single: ?disputeId=<value>
Multiple: ?disputeId=<value1>&disputeId=<value2>
Null: ?disputeId=null

adminId (ID): Filter by adminId

Single: ?adminId=<value>
Multiple: ?adminId=<value1>&adminId=<value2>
Null: ?adminId=null

REST Request To access the api you can use the REST controller with the path GET /v1/admindisputeactions

  axios({
    method: 'GET',
    url: '/v1/admindisputeactions',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // disputeId: '<value>' // Filter by disputeId
        // adminId: '<value>' // Filter by adminId
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "adminDisputeActions",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"adminDisputeActions": [
		{
			"id": "ID",
			"disputeId": "ID",
			"actionTaken": "String",
			"notes": "Text",
			"adminId": "ID",
			"outcome": "String",
			"actionDate": "Date",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Admindisputeaction` API

Admin records moderation/decision action on a dispute (creates audit log as side effect).

Rest Route

The createAdminDisputeAction API REST controller can be triggered via the following route:

/v1/admindisputeactions

Rest Request Parameters

The createAdminDisputeAction api has got 5 regular request parameters

Parameter	Type	Required	Population
disputeId	ID	true	request.body?.[“disputeId”]
actionTaken	String	true	request.body?.[“actionTaken”]
notes	Text	false	request.body?.[“notes”]
adminId	ID	true	request.body?.[“adminId”]
outcome	String	false	request.body?.[“outcome”]
disputeId :
actionTaken :
notes :
adminId :
outcome :

REST Request To access the api you can use the REST controller with the path POST /v1/admindisputeactions

  axios({
    method: 'POST',
    url: '/v1/admindisputeactions',
    data: {
            disputeId:"ID",  
            actionTaken:"String",  
            notes:"Text",  
            adminId:"ID",  
            outcome:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "adminDisputeAction",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"adminDisputeAction": {
		"id": "ID",
		"disputeId": "ID",
		"actionTaken": "String",
		"notes": "Text",
		"adminId": "ID",
		"outcome": "String",
		"actionDate": "Date",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Localizationsetting` API

Update a localization setting. Admin only.

Rest Route

The updateLocalizationSetting API REST controller can be triggered via the following route:

/v1/localizationsettings/:localizationSettingId

Rest Request Parameters

The updateLocalizationSetting api has got 6 regular request parameters

Parameter	Type	Required	Population
localizationSettingId	ID	true	request.params?.[“localizationSettingId”]
languageCode	String	false	request.body?.[“languageCode”]
effectiveFrom	Date	false	request.body?.[“effectiveFrom”]
effectiveTo	Date	false	request.body?.[“effectiveTo”]
currencyCode	String	false	request.body?.[“currencyCode”]
isCurrencyActive	Boolean	false	request.body?.[“isCurrencyActive”]
localizationSettingId : This id paremeter is used to select the required data object that will be updated
languageCode :
effectiveFrom :
effectiveTo :
currencyCode :
isCurrencyActive :

REST Request To access the api you can use the REST controller with the path PATCH /v1/localizationsettings/:localizationSettingId

  axios({
    method: 'PATCH',
    url: `/v1/localizationsettings/${localizationSettingId}`,
    data: {
            languageCode:"String",  
            effectiveFrom:"Date",  
            effectiveTo:"Date",  
            currencyCode:"String",  
            isCurrencyActive:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "localizationSetting",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"localizationSetting": {
		"id": "ID",
		"languageCode": "String",
		"effectiveFrom": "Date",
		"effectiveTo": "Date",
		"currencyCode": "String",
		"isCurrencyActive": "Boolean",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`Update Gdpraction` API

Compliance admin records status of a GDPR request (pending/complete/failed). No delete allowed for compliance records.

Rest Route

The updateGdprAction API REST controller can be triggered via the following route:

/v1/gdpractions/:gdprActionId

Rest Request Parameters

The updateGdprAction api has got 3 regular request parameters

Parameter	Type	Required	Population
gdprActionId	ID	true	request.params?.[“gdprActionId”]
status	Enum	false	request.body?.[“status”]
processedAt	Date	false	request.body?.[“processedAt”]
gdprActionId : This id paremeter is used to select the required data object that will be updated
status :
processedAt :

REST Request To access the api you can use the REST controller with the path PATCH /v1/gdpractions/:gdprActionId

  axios({
    method: 'PATCH',
    url: `/v1/gdpractions/${gdprActionId}`,
    data: {
            status:"Enum",  
            processedAt:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "gdprAction",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"gdprAction": {
		"id": "ID",
		"requestedAt": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"actionType": "String",
		"userId": "ID",
		"processedAt": "Date",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`List Gdpractions` API

List all GDPR/compliance records with status for audit/compliance purposes.

Rest Route

The listGdprActions API REST controller can be triggered via the following route:

/v1/gdpractions

Rest Request Parameters The listGdprActions api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/gdpractions

  axios({
    method: 'GET',
    url: '/v1/gdpractions',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "gdprActions",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"gdprActions": [
		{
			"id": "ID",
			"requestedAt": "Date",
			"status": "Enum",
			"status_idx": "Integer",
			"actionType": "String",
			"userId": "ID",
			"processedAt": "Date",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Apikey` API

Create/administer an API key (for integrations, partners, automation). Key is hashed at rest.

Rest Route

The createApiKey API REST controller can be triggered via the following route:

/v1/apikeys

Rest Request Parameters

The createApiKey api has got 5 regular request parameters

Parameter	Type	Required	Population
key	String	true	request.body?.[“key”]
active	Boolean	true	request.body?.[“active”]
description	String	false	request.body?.[“description”]
revokedAt	Date	false	request.body?.[“revokedAt”]
createdBy	ID	true	request.body?.[“createdBy”]
key :
active :
description :
revokedAt :
createdBy :

REST Request To access the api you can use the REST controller with the path POST /v1/apikeys

  axios({
    method: 'POST',
    url: '/v1/apikeys',
    data: {
            key:"String",  
            active:"Boolean",  
            description:"String",  
            revokedAt:"Date",  
            createdBy:"ID",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "apiKey",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"apiKey": {
		"id": "ID",
		"key": "String",
		"active": "Boolean",
		"description": "String",
		"revokedAt": "Date",
		"createdBy": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Apikeys` API

Show all API keys with status (hash only, never show the sensitive key string itself).

Rest Route

The listApiKeys API REST controller can be triggered via the following route:

/v1/apikeys

Rest Request Parameters The listApiKeys api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/apikeys

  axios({
    method: 'GET',
    url: '/v1/apikeys',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "apiKeys",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"apiKeys": [
		{
			"id": "ID",
			"key": "String",
			"active": "Boolean",
			"description": "String",
			"revokedAt": "Date",
			"createdBy": "ID",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Update Apikey` API

Update API key metadata or deactivate (e.g. revoke). Only admin allowed.

Rest Route

The updateApiKey API REST controller can be triggered via the following route:

/v1/apikeys/:apiKeyId

Rest Request Parameters

The updateApiKey api has got 4 regular request parameters

Parameter	Type	Required	Population
apiKeyId	ID	true	request.params?.[“apiKeyId”]
active	Boolean	false	request.body?.[“active”]
description	String	false	request.body?.[“description”]
revokedAt	Date	false	request.body?.[“revokedAt”]
apiKeyId : This id paremeter is used to select the required data object that will be updated
active :
description :
revokedAt :

REST Request To access the api you can use the REST controller with the path PATCH /v1/apikeys/:apiKeyId

  axios({
    method: 'PATCH',
    url: `/v1/apikeys/${apiKeyId}`,
    data: {
            active:"Boolean",  
            description:"String",  
            revokedAt:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "apiKey",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"apiKey": {
		"id": "ID",
		"key": "String",
		"active": "Boolean",
		"description": "String",
		"revokedAt": "Date",
		"createdBy": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

`List Localizationsettings` API

Show all currently configured languages/currencies.

Rest Route

The listLocalizationSettings API REST controller can be triggered via the following route:

/v1/localizationsettings

Rest Request Parameters

Filter Parameters

The listLocalizationSettings api supports 3 optional filter parameters for filtering list results:

languageCode (String): Filter by languageCode

Single (partial match, case-insensitive): ?languageCode=<value>
Multiple: ?languageCode=<value1>&languageCode=<value2>
Null: ?languageCode=null

currencyCode (String): Filter by currencyCode

Single (partial match, case-insensitive): ?currencyCode=<value>
Multiple: ?currencyCode=<value1>&currencyCode=<value2>
Null: ?currencyCode=null

isCurrencyActive (Boolean): Filter by isCurrencyActive

True: ?isCurrencyActive=true
False: ?isCurrencyActive=false
Null: ?isCurrencyActive=null

REST Request To access the api you can use the REST controller with the path GET /v1/localizationsettings

  axios({
    method: 'GET',
    url: '/v1/localizationsettings',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // languageCode: '<value>' // Filter by languageCode
        // currencyCode: '<value>' // Filter by currencyCode
        // isCurrencyActive: '<value>' // Filter by isCurrencyActive
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "localizationSettings",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"localizationSettings": [
		{
			"id": "ID",
			"languageCode": "String",
			"effectiveFrom": "Date",
			"effectiveTo": "Date",
			"currencyCode": "String",
			"isCurrencyActive": "Boolean",
			"isActive": true,
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID"
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Create Gdpraction` API

User/admin submits GDPR request (export/delete/consent). Logged for compliance; status may be updated by compliance admin only.

Rest Route

The createGdprAction API REST controller can be triggered via the following route:

/v1/gdpractions

Rest Request Parameters

The createGdprAction api has got 3 regular request parameters

Parameter	Type	Required	Population
actionType	String	true	request.body?.[“actionType”]
userId	ID	true	request.body?.[“userId”]
processedAt	Date	false	request.body?.[“processedAt”]
actionType :
userId :
processedAt :

REST Request To access the api you can use the REST controller with the path POST /v1/gdpractions

  axios({
    method: 'POST',
    url: '/v1/gdpractions',
    data: {
            actionType:"String",  
            userId:"ID",  
            processedAt:"Date",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "gdprAction",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"gdprAction": {
		"id": "ID",
		"requestedAt": "Date",
		"status": "Enum",
		"status_idx": "Integer",
		"actionType": "String",
		"userId": "ID",
		"processedAt": "Date",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

AIRBNB

FRONTEND GUIDE FOR AI CODING AGENTS - PART 13 - AgentHub Service

This document is a part of a REST API guide for the airbnb project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document provides extensive instruction for the usage of agentHub

Service Access

AgentHub service management is handled through service specific base urls.

AgentHub service may be deployed to the preview server, staging server, or production server. Therefore,it has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the login page (already handled in first part.).

For the agentHub service, the base URLs are:

Preview: https://airbnb3.prw.mindbricks.com/agenthub-api
Staging: https://airbnb3-stage.mindbricks.co/agenthub-api
Production: https://airbnb3.mindbricks.co/agenthub-api

Scope

AgentHub Service Description

AI Agent Hub

AgentHub service provides apis and business logic for following data objects in airbnb application. Each data object may be either a central domain of the application data structure or a related helper data object for a central concept. Note that data object concept is equal to table concept in the database, in the service database each data object is represented as a db table scheme and the object instances as table rows.

sys_agentOverride Data Object: Runtime overrides for design-time agents. Null fields use the design default.

sys_agentExecution Data Object: Agent execution log. Records each agent invocation with input, output, and performance metrics.

sys_toolCatalog Data Object: Cached tool catalog discovered from project services. Refreshed periodically.

API Structure

Object Structure of a Successful Response

HTTP Status Codes:

200 OK: Returned for successful GET, LIST, UPDATE, or DELETE operations, indicating that the request was processed successfully.
201 Created: Returned for CREATE operations, indicating that the resource was created successfully.

Success Response Format:

For successful operations, the response includes a "status": "OK" property, signaling that the request executed successfully. The structure of a successful response is outlined below:

{
  "status":"OK",
  "statusCode": 200,   
  "elapsedMs":126,
  "ssoTime":120,
  "source": "db",
  "cacheKey": "hexCode",
  "userId": "ID",
  "sessionId": "ID",
  "requestId": "ID",
  "dataName":"products",
  "method":"GET",
  "action":"list",
  "appVersion":"Version",
  "rowCount":3,
  "products":[{},{},{}],
  "paging": {
    "pageNumber":1, 
    "pageRowCount":25, 
    "totalRowCount":3,
    "pageCount":1
  },
  "filters": [],
  "uiPermissions": []
}

products: In this example, this key contains the actual response content, which may be a single object or an array of objects depending on the operation.

Additional Data

Each API may include additional data besides the main data object, depending on the business logic of the API. These will be provided in each API’s response signature.

Error Response

400 Bad Request: The request was improperly formatted or contained invalid parameters.
401 Unauthorized: The request lacked a valid authentication token; login is required.
403 Forbidden: The current token does not grant access to the requested resource.
404 Not Found: The requested resource was not found on the server.
500 Internal Server Error: The server encountered an unexpected condition.

Each error response is structured to provide meaningful insight into the problem, assisting in efficient diagnosis and resolution.

{
  "result": "ERR",
  "status": 400,
  "message": "errMsg_organizationIdisNotAValidID",
  "errCode": 400,
  "date": "2024-03-19T12:13:54.124Z",
  "detail": "String"
}

Sys_agentOverride Data Object

Runtime overrides for design-time agents. Null fields use the design default.

Sys_agentOverride Data Object Properties

Sys_agentOverride data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	Required	Secret	Description
`agentName`	String	Yes	No	Design-time agent name this override applies to.
`provider`	String	No	No	Override AI provider (e.g., openai, anthropic).
`model`	String	No	No	Override model name.
`systemPrompt`	Text	No	No	Override system prompt.
`temperature`	Double	No	No	Override temperature (0-2).
`maxTokens`	Integer	No	No	Override max tokens.
`responseFormat`	String	No	No	Override response format (text/json).
`selectedTools`	Object	No	No	Array of tool names from the catalog that this agent can use.
`guardrails`	Object	No	No	Override guardrails: { maxToolCalls, timeout, maxTokenBudget }.
`enabled`	Boolean	Yes	No	Enable or disable this agent.
`updatedBy`	ID	No	No	User who last updated this override.

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Sys_agentExecution Data Object

Agent execution log. Records each agent invocation with input, output, and performance metrics.

Sys_agentExecution Data Object Properties

Sys_agentExecution data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	Required	Secret	Description
`agentName`	String	Yes	No	Agent that was executed.
`agentType`	Enum	Yes	No	Whether this was a design-time or dynamic agent.
`source`	Enum	Yes	No	How the agent was triggered.
`userId`	ID	No	No	User who triggered the execution.
`input`	Object	No	No	Request input (truncated for large payloads).
`output`	Object	No	No	Response output (truncated for large payloads).
`toolCalls`	Integer	No	No	Number of tool calls made during execution.
`tokenUsage`	Object	No	No	Token usage: { prompt, completion, total }.
`durationMs`	Integer	No	No	Execution time in milliseconds.
`status`	Enum	Yes	No	Execution status.
`error`	Text	No	No	Error message if execution failed.

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Enum Properties

agentType: [design, dynamic]
source: [rest, sse, kafka, agent]
status: [success, error, timeout]

Filter Properties

agentName agentType source userId status

agentName: String has a filter named agentName
agentType: Enum has a filter named agentType
source: Enum has a filter named source
userId: ID has a filter named userId
status: Enum has a filter named status

Sys_toolCatalog Data Object

Cached tool catalog discovered from project services. Refreshed periodically.

Sys_toolCatalog Data Object Properties

Sys_toolCatalog data object has got following properties that are represented as table fields in the database scheme. These properties don’t stand just for data storage, but each may have different settings to manage the business logic.

Property	Type	Required	Secret	Description
`toolName`	String	Yes	No	Full tool name (e.g., service:apiName).
`serviceName`	String	Yes	No	Source service name.
`description`	Text	No	No	Tool description.
`parameters`	Object	No	No	JSON Schema of tool parameters.
`lastRefreshed`	Date	No	No	When this tool was last discovered/refreshed.

Required properties are mandatory for creating objects and must be provided in the request body if no default value, formula or session bind is set.

Filter Properties

serviceName

serviceName: String has a filter named serviceName

Default CRUD APIs

Sys_agentOverride Default APIs

Operation	API Name	Route	Explicitly Set
Create	`createAgentOverride`	`/v1/agentoverride`	Yes
Update	`updateAgentOverride`	`/v1/agentoverride/:sys_agentOverrideId`	Yes
Delete	`deleteAgentOverride`	`/v1/agentoverride/:sys_agentOverrideId`	Yes
Get	`getAgentOverride`	`/v1/agentoverride/:sys_agentOverrideId`	Yes
List	`listAgentOverrides`	`/v1/agentoverrides`	Yes

Sys_agentExecution Default APIs

Operation	API Name	Route	Explicitly Set
Create	none	-	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	`getAgentExecution`	`/v1/agentexecution/:sys_agentExecutionId`	Yes
List	`listAgentExecutions`	`/v1/agentexecutions`	Yes

Sys_toolCatalog Default APIs

Operation	API Name	Route	Explicitly Set
Create	none	-	Auto
Update	none	-	Auto
Delete	none	-	Auto
Get	`getToolCatalogEntry`	`/v1/toolcatalogentry/:sys_toolCatalogId`	Yes
List	`listToolCatalog`	`/v1/toolcatalog`	Yes

API Reference

`Get Agentoverride` API

[Default get API] — This is the designated default get API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride/:sys_agentOverrideId

Rest Request Parameters

The getAgentOverride api has got 1 regular request parameter

Parameter	Type	Required	Population
sys_agentOverrideId	ID	true	request.params?.[“sys_agentOverrideId”]
sys_agentOverrideId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/agentoverride/:sys_agentOverrideId

  axios({
    method: 'GET',
    url: `/v1/agentoverride/${sys_agentOverrideId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`List Agentoverrides` API

[Default list API] — This is the designated default list API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listAgentOverrides API REST controller can be triggered via the following route:

/v1/agentoverrides

Rest Request Parameters The listAgentOverrides api has got no request parameters.

REST Request To access the api you can use the REST controller with the path GET /v1/agentoverrides

  axios({
    method: 'GET',
    url: '/v1/agentoverrides',
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverrides",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_agentOverrides": [
		{
			"id": "ID",
			"agentName": "String",
			"provider": "String",
			"model": "String",
			"systemPrompt": "Text",
			"temperature": "Double",
			"maxTokens": "Integer",
			"responseFormat": "String",
			"selectedTools": "Object",
			"guardrails": "Object",
			"enabled": "Boolean",
			"updatedBy": "ID",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Update Agentoverride` API

[Default update API] — This is the designated default update API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The updateAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride/:sys_agentOverrideId

Rest Request Parameters

The updateAgentOverride api has got 10 regular request parameters

Parameter	Type	Required	Population
sys_agentOverrideId	ID	true	request.params?.[“sys_agentOverrideId”]
provider	String		request.body?.[“provider”]
model	String		request.body?.[“model”]
systemPrompt	Text		request.body?.[“systemPrompt”]
temperature	Double		request.body?.[“temperature”]
maxTokens	Integer		request.body?.[“maxTokens”]
responseFormat	String		request.body?.[“responseFormat”]
selectedTools	Object		request.body?.[“selectedTools”]
guardrails	Object		request.body?.[“guardrails”]
enabled	Boolean		request.body?.[“enabled”]
sys_agentOverrideId : This id paremeter is used to select the required data object that will be updated
provider : Override AI provider (e.g., openai, anthropic).
model : Override model name.
systemPrompt : Override system prompt.
temperature : Override temperature (0-2).
maxTokens : Override max tokens.
responseFormat : Override response format (text/json).
selectedTools : Array of tool names from the catalog that this agent can use.
guardrails : Override guardrails: { maxToolCalls, timeout, maxTokenBudget }.
enabled : Enable or disable this agent.

REST Request To access the api you can use the REST controller with the path PATCH /v1/agentoverride/:sys_agentOverrideId

  axios({
    method: 'PATCH',
    url: `/v1/agentoverride/${sys_agentOverrideId}`,
    data: {
            provider:"String",  
            model:"String",  
            systemPrompt:"Text",  
            temperature:"Double",  
            maxTokens:"Integer",  
            responseFormat:"String",  
            selectedTools:"Object",  
            guardrails:"Object",  
            enabled:"Boolean",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "PATCH",
	"action": "update",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`Create Agentoverride` API

[Default create API] — This is the designated default create API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The createAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride

Rest Request Parameters

The createAgentOverride api has got 9 regular request parameters

Parameter	Type	Required	Population
agentName	String	true	request.body?.[“agentName”]
provider	String	false	request.body?.[“provider”]
model	String	false	request.body?.[“model”]
systemPrompt	Text	false	request.body?.[“systemPrompt”]
temperature	Double	false	request.body?.[“temperature”]
maxTokens	Integer	false	request.body?.[“maxTokens”]
responseFormat	String	false	request.body?.[“responseFormat”]
selectedTools	Object	false	request.body?.[“selectedTools”]
guardrails	Object	false	request.body?.[“guardrails”]
agentName : Design-time agent name this override applies to.
provider : Override AI provider (e.g., openai, anthropic).
model : Override model name.
systemPrompt : Override system prompt.
temperature : Override temperature (0-2).
maxTokens : Override max tokens.
responseFormat : Override response format (text/json).
selectedTools : Array of tool names from the catalog that this agent can use.
guardrails : Override guardrails: { maxToolCalls, timeout, maxTokenBudget }.

REST Request To access the api you can use the REST controller with the path POST /v1/agentoverride

  axios({
    method: 'POST',
    url: '/v1/agentoverride',
    data: {
            agentName:"String",  
            provider:"String",  
            model:"String",  
            systemPrompt:"Text",  
            temperature:"Double",  
            maxTokens:"Integer",  
            responseFormat:"String",  
            selectedTools:"Object",  
            guardrails:"Object",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`Delete Agentoverride` API

[Default delete API] — This is the designated default delete API for the sys_agentOverride data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The deleteAgentOverride API REST controller can be triggered via the following route:

/v1/agentoverride/:sys_agentOverrideId

Rest Request Parameters

The deleteAgentOverride api has got 1 regular request parameter

Parameter	Type	Required	Population
sys_agentOverrideId	ID	true	request.params?.[“sys_agentOverrideId”]
sys_agentOverrideId : This id paremeter is used to select the required data object that will be deleted

REST Request To access the api you can use the REST controller with the path DELETE /v1/agentoverride/:sys_agentOverrideId

  axios({
    method: 'DELETE',
    url: `/v1/agentoverride/${sys_agentOverrideId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentOverride",
	"method": "DELETE",
	"action": "delete",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentOverride": {
		"id": "ID",
		"agentName": "String",
		"provider": "String",
		"model": "String",
		"systemPrompt": "Text",
		"temperature": "Double",
		"maxTokens": "Integer",
		"responseFormat": "String",
		"selectedTools": "Object",
		"guardrails": "Object",
		"enabled": "Boolean",
		"updatedBy": "ID",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": false
	}
}

`List Toolcatalog` API

[Default list API] — This is the designated default list API for the sys_toolCatalog data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listToolCatalog API REST controller can be triggered via the following route:

/v1/toolcatalog

Rest Request Parameters

Filter Parameters

The listToolCatalog api supports 1 optional filter parameter for filtering list results:

serviceName (String): Source service name.

Single (partial match, case-insensitive): ?serviceName=<value>
Multiple: ?serviceName=<value1>&serviceName=<value2>
Null: ?serviceName=null

REST Request To access the api you can use the REST controller with the path GET /v1/toolcatalog

  axios({
    method: 'GET',
    url: '/v1/toolcatalog',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // serviceName: '<value>' // Filter by serviceName
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_toolCatalogs",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_toolCatalogs": [
		{
			"id": "ID",
			"toolName": "String",
			"serviceName": "String",
			"description": "Text",
			"parameters": "Object",
			"lastRefreshed": "Date",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Get Toolcatalogentry` API

[Default get API] — This is the designated default get API for the sys_toolCatalog data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getToolCatalogEntry API REST controller can be triggered via the following route:

/v1/toolcatalogentry/:sys_toolCatalogId

Rest Request Parameters

The getToolCatalogEntry api has got 1 regular request parameter

Parameter	Type	Required	Population
sys_toolCatalogId	ID	true	request.params?.[“sys_toolCatalogId”]
sys_toolCatalogId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/toolcatalogentry/:sys_toolCatalogId

  axios({
    method: 'GET',
    url: `/v1/toolcatalogentry/${sys_toolCatalogId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_toolCatalog",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_toolCatalog": {
		"id": "ID",
		"toolName": "String",
		"serviceName": "String",
		"description": "Text",
		"parameters": "Object",
		"lastRefreshed": "Date",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

`List Agentexecutions` API

[Default list API] — This is the designated default list API for the sys_agentExecution data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The listAgentExecutions API REST controller can be triggered via the following route:

/v1/agentexecutions

Rest Request Parameters

Filter Parameters

The listAgentExecutions api supports 5 optional filter parameters for filtering list results:

agentName (String): Agent that was executed.

Single (partial match, case-insensitive): ?agentName=<value>
Multiple: ?agentName=<value1>&agentName=<value2>
Null: ?agentName=null

agentType (Enum): Whether this was a design-time or dynamic agent.

Single: ?agentType=<value> (case-insensitive)
Multiple: ?agentType=<value1>&agentType=<value2>
Null: ?agentType=null

source (Enum): How the agent was triggered.

Single: ?source=<value> (case-insensitive)
Multiple: ?source=<value1>&source=<value2>
Null: ?source=null

userId (ID): User who triggered the execution.

Single: ?userId=<value>
Multiple: ?userId=<value1>&userId=<value2>
Null: ?userId=null

status (Enum): Execution status.

Single: ?status=<value> (case-insensitive)
Multiple: ?status=<value1>&status=<value2>
Null: ?status=null

REST Request To access the api you can use the REST controller with the path GET /v1/agentexecutions

  axios({
    method: 'GET',
    url: '/v1/agentexecutions',
    data: {
    
    },
    params: {
    
        // Filter parameters (see Filter Parameters section above)
        // agentName: '<value>' // Filter by agentName
        // agentType: '<value>' // Filter by agentType
        // source: '<value>' // Filter by source
        // userId: '<value>' // Filter by userId
        // status: '<value>' // Filter by status
            }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentExecutions",
	"method": "GET",
	"action": "list",
	"appVersion": "Version",
	"rowCount": "\"Number\"",
	"sys_agentExecutions": [
		{
			"id": "ID",
			"agentName": "String",
			"agentType": "Enum",
			"agentType_idx": "Integer",
			"source": "Enum",
			"source_idx": "Integer",
			"userId": "ID",
			"input": "Object",
			"output": "Object",
			"toolCalls": "Integer",
			"tokenUsage": "Object",
			"durationMs": "Integer",
			"status": "Enum",
			"status_idx": "Integer",
			"error": "Text",
			"recordVersion": "Integer",
			"createdAt": "Date",
			"updatedAt": "Date",
			"_owner": "ID",
			"isActive": true
		},
		{},
		{}
	],
	"paging": {
		"pageNumber": "Number",
		"pageRowCount": "NUmber",
		"totalRowCount": "Number",
		"pageCount": "Number"
	},
	"filters": [],
	"uiPermissions": []
}

`Get Agentexecution` API

[Default get API] — This is the designated default get API for the sys_agentExecution data object. Frontend generators and AI agents should use this API for standard CRUD operations.

Rest Route

The getAgentExecution API REST controller can be triggered via the following route:

/v1/agentexecution/:sys_agentExecutionId

Rest Request Parameters

The getAgentExecution api has got 1 regular request parameter

Parameter	Type	Required	Population
sys_agentExecutionId	ID	true	request.params?.[“sys_agentExecutionId”]
sys_agentExecutionId : This id paremeter is used to query the required data object.

REST Request To access the api you can use the REST controller with the path GET /v1/agentexecution/:sys_agentExecutionId

  axios({
    method: 'GET',
    url: `/v1/agentexecution/${sys_agentExecutionId}`,
    data: {
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "200",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "sys_agentExecution",
	"method": "GET",
	"action": "get",
	"appVersion": "Version",
	"rowCount": 1,
	"sys_agentExecution": {
		"id": "ID",
		"agentName": "String",
		"agentType": "Enum",
		"agentType_idx": "Integer",
		"source": "Enum",
		"source_idx": "Integer",
		"userId": "ID",
		"input": "Object",
		"output": "Object",
		"toolCalls": "Integer",
		"tokenUsage": "Object",
		"durationMs": "Integer",
		"status": "Enum",
		"status_idx": "Integer",
		"error": "Text",
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID",
		"isActive": true
	}
}

After this prompt, the user may give you new instructions to update the output of this prompt or provide subsequent prompts about the project.

Airbnb-Style Rental Marketplace Backend - Frontend Development Prompts

Table of Contents

Introduction

Project Overview

Airbnb-Style Rental Marketplace Backend

How to Use Project Documents

Accessing Project Services

Service Endpoint Structure

Environment Usage Notes

Getting Started: Use the Auth Service First

Auth Service Documentation

Using the BFF (Backend-for-Frontend) Service

Key Principles of the BFF Service

BFF Service Documentation

Business Services Overview

Usage Guidance

Available Business Services

messaging Service

propertyCatalog Service

bookingManagement Service

reviewSystem Service

platformAdmin Service

agentHub Service

Connect via MCP (Model Context Protocol)

Unified MCP Endpoint

Authentication

Connecting from Cursor

Connecting from Claude Desktop

What’s Available

Conclusion

How to Use These Prompts

Frontend Development Prompts

AIRBNB

Project Introduction

Project Services Overview

API Structure

Object Structure of a Successful Response

Additional Data

Error Response

Accessing the Backend

Home Page

Initial Navigation Structure

What To Build Now

Common Reminders

AIRBNB

FRONTEND_URL

Registration Management

User Registration

Register User API

Login Management

Login Identifier Model

Login Flow

POST /login — User Login

Request Parameters

Behavior

Example

Success Response

Error Responses

POST /logout — User Logout

Behavior

Example

Notes

Success Response

GET /currentuser — Current Session

Request

Example

Success (200)

Errors

AIRBNB

Accessing the backend

After User Registration

Email Verification

POST /verification-services/email-verification/start

POST /verification-services/email-verification/complete

Mobile Verification

POST /verification-services/mobile-verification/start

POST /verification-services/mobile-verification/complete

Resetting Password

Password Reset By Email Flow

POST /verification-services/password-reset-by-email/start

`Register User` API

`POST /login` — User Login

`POST /logout` — User Logout

`GET /currentuser` — Current Session

`POST /verification-services/email-verification/start`

`POST /verification-services/email-verification/complete`

`POST /verification-services/mobile-verification/start`

`POST /verification-services/mobile-verification/complete`

POST `/verification-services/password-reset-by-email/start`

POST `/verification-services/password-reset-by-email/complete`

POST `/verification-services/password-reset-by-mobile/start`

POST `/verification-services/password-reset-by-mobile/complete`

`POST /verification-services/email-2factor-verification/start`

`POST /verification-services/email-2factor-verification/complete`

`Get User` API

`Update Profile` API

`Update Userpassword` API

`Archive Profile` API

`List Users` API

`Search Users` API

`Create User` API

`Update User` API

`Update Userrole` API

`Update Userpasswordbyadmin` API

`Delete User` API

`Create Usergroup` API

`Update Usergroup` API

`Delete Usergroup` API

`Get Usergroup` API

`List Usergroups` API

`Create Usergroupmember` API

`Delete Usergroupmember` API

`List Usergroupmembers` API