BusinessApi

MPO Version: 1.3.0

Defines a Business API, a high-level abstraction representing a specific business operation on a primary data object. It encapsulates intent (e.g., get, create, delete), parameters, trigger mechanisms, and a structured workflow composed of modular actions. Each Business API offers more expressive and decoupled control over behavior and access.

interface BusinessApi = {
  apiOptions : ApiOptions;
  authOptions : ApiAuthOptions;
  customParameters : BusinessApiParameter[];
  redisParameters : RedisApiParameter[];
  restSettings : ApiRestSettings;
  grpcSettings : ApiGrpcSettings;
  kafkaSettings : ApiKafkaSettings;
  sseSettings : ApiSseSettings;
  cronSettings : ApiCronSettings;
  selectClause : SelectClauseSettings;
  dataClause : DataClauseSettings;
  whereClause : WhereClauseSettings;
  deleteOptions : DeleteOptions;
  getOptions : GetOptions;
  listOptions : ListOptions;
  paginationOptions : PaginationOptions;
  actions : BusinessApiActionStore;
  workflow : BusinessWorkflow;
}

ApiOptions

MPO Version: 1.3.0

Main configuration section for a Business API. This object includes essential attributes such as naming, access control, event handling, input generation, and fallback strategies. In many cases, configuring this section alone is sufficient to define the primary behavior of an API entry point.

interface ApiOptions = {
  dataObjectName : LocalDataObjectName;
  dataViewName : String;
  crudType : CrudTypes;
  name : String;
  apiDescription : Text;
  frontendDocument : Text;
  raiseApiEvent : Boolean;
  raiseDbLevelEvents : Boolean;
  autoParams : Boolean;
  readFromEntityCache : Boolean;
  blockMcp : Boolean;
  isDefaultApi : Boolean;
}

CrudTypes

CrudTypes define the fundamental operation mode of a route. Each route is classified by a CRUD type that reflects its intended data operation: create, update, read, or delete.

const CrudTypes = {
  create: "create",
  update: "update",
  get: "get",
  list: "list",
  delete: "delete",
};

LocalDataObjectName

MPO Version: 1.3.0

Represents a reference to a data object within the same service. The value must be a simple object name; not a qualified reference in the format 'serviceName:objectName'.

interface LocalDataObjectName = {
}

ApiAuthOptions

MPO Version: 1.3.0

Defines core authentication and authorization settings for a Business API. These settings cover session validation, role and ownership checks, and access scope (e.g., tenant vs. SaaS-level). While these options are sufficient for most use cases, more fine-grained access control—such as conditional permissions or contextual ownership—should be implemented using explicit access control actions (e.g., PermissionCheckAction, MembershipCheckAction, ObjectPermissionCheckAction).

interface ApiAuthOptions = {
  apiInSaasLevel : Boolean;
  M2MAllowed : Boolean;
  loginRequired : Boolean;
  ownershipCheck : Boolean;
  parentOwnershipChecks : String[];
  absoluteRoles : String[];
  checkRoles : String[];
  defaultPermissions : String[];
}

BusinessApiParameter

MPO Version: 1.3.0

Defines a customizable input parameter for a Business API. Parameters are extracted from the incoming request, transformed and validated, and then written directly to the API context under this.<name>. These parameters may originate from any request part (e.g., body, query, session), and can be combined with Redis-based or auto-generated parameters.

interface BusinessApiParameter = {
  name : String;
  type : DataTypes;
  required : Boolean;
  defaultValue : AnyComplex;
  httpLocation : RequestLocations;
  dataPath : String;
  transform : MScript;
  hidden : Boolean;
  description : Text;
}

RedisApiParameter

MPO Version: 1.3.0

Defines a parameter whose value is fetched from Redis before Business API execution begins. The result is written directly to the context as this.<name>, making it accessible like any other parameter. This is useful for injecting server-side or cached state without requiring the client to send it explicitly.

interface RedisApiParameter = {
  name : String;
  type : DataTypes;
  required : Boolean;
  defaultValue : AnyComplex;
  redisKey : String;
}

ApiRestSettings

MPO Version: 1.3.0

Defines the REST controller configuration for a Business API. REST is the default HTTP interface in Mindbricks. These settings allow enabling/disabling REST access and customizing the endpoint path.

interface ApiRestSettings = {
  hasRestController : Boolean;
  configuration : ApiRestSettingsConfig;
}

ApiRestSettingsConfig

MPO Version: 1.3.0

Customizes the REST endpoint path for a Business API. If omitted or set to $default, Mindbricks auto-generates the path based on the API name and crudType.

interface ApiRestSettingsConfig = {
  routePath : String;
  forcePOSTMethod : Boolean;
}

ApiGrpcSettings

MPO Version: 1.3.0

Enables gRPC interface for the Business API. Useful for high-performance service-to-service communication.

interface ApiGrpcSettings = {
  hasGrpcController : Boolean;
  configuration : ApiGrpcSettingsConfig;
}

ApiGrpcSettingsConfig

MPO Version: 1.3.0

Configuration for gRPC method behavior and response format.

interface ApiGrpcSettingsConfig = {
  responseFormat : GrpcApiResponseFormat;
  responseType : GrpcApiResponseType;
}

GrpcApiResponseFormat

Controls the structure of the gRPC response.

const GrpcApiResponseFormat = {
  dataItem: "dataItem",
  fullResponse: "fullResponse",
};

GrpcApiResponseType

Controls whether the gRPC method returns a single message or a stream.

const GrpcApiResponseType = {
  single: "single",
  stream: "stream",
};

ApiKafkaSettings

MPO Version: 1.3.0

Configures Kafka as a trigger mechanism for the Business API. This supports both asynchronous processing and integration-based event handling (e.g., storage triggers, audit flows).

interface ApiKafkaSettings = {
  hasKafkaController : Boolean;
  configuration : ApiKafkaSettingsConfig;
}

ApiKafkaSettingsConfig

MPO Version: 1.3.0

Configuration object for Kafka topic bindings for triggering the Business API.

interface ApiKafkaSettingsConfig = {
  requestTopicName : String;
  responseTopicName : String;
}

ApiSseSettings

MPO Version: 1.3.0

Enables Server-Sent Events (SSE) streaming for a Business API, allowing the API to stream its response as chunks or emit progress events over an SSE connection. The REST endpoint continues to serve single request-response. The SSE endpoint is a companion for responses that are too large or too slow for a single HTTP response.

interface ApiSseSettings = {
  hasSseController : Boolean;
  configuration : ApiSseSettingsConfig;
}

ApiSseSettingsConfig

MPO Version: 1.3.0

SSE connection configuration, including response mode, timeout, chunk size, optional custom stream source, and optional Kafka progress listeners for remote process tracking.

interface ApiSseSettingsConfig = {
  responseMode : SseResponseMode;
  timeout : Integer;
  chunkSize : Integer;
  streamSource : StreamSourceConfig;
  kafkaProgressListeners : KafkaProgressListener[];
}

SseResponseMode

Defines how the SSE endpoint delivers data to the client.

const SseResponseMode = {
  stream: "stream",
  events: "events",
};

StreamSourceConfig

MPO Version: 1.3.0

Declares the source of chunked data for SSE streaming when the default list-based streaming is not applicable. Only needed for non-list APIs or when data comes from an external source (lib function, iterator action, SSE/WS relay).

interface StreamSourceConfig = {
  sourceType : StreamSourceType;
  libFunctionName : String;
  iteratorAction : String;
  relayUrl : MScript;
  relayAuth : MScript;
}

StreamSourceType

Defines the type of custom stream source for SSE streaming. Only needed when the default list-based streaming is not sufficient.

const StreamSourceType = {
  libFunction: "libFunction",
  iteratorAction: "iteratorAction",
  sseRelay: "sseRelay",
  wsRelay: "wsRelay",
};

KafkaProgressListener

MPO Version: 1.3.0

Configures a Kafka topic subscription for receiving progress updates from remote processes during an SSE connection. Messages are filtered by a correlation ID and relayed as SSE events to the client.

interface KafkaProgressListener = {
  topic : String;
  correlationField : MScript;
  kafkaFilterField : String;
  eventName : String;
  payloadMapping : MScript;
  completeWhen : MScript;
}

ApiCronSettings

MPO Version: 1.3.0

Schedules the Business API for periodic execution using a cron expression. Ideal for background jobs or recurring tasks.

interface ApiCronSettings = {
  hasCronController : Boolean;
  configuration : ApiCronSettingsConfig;
}

ApiCronSettingsConfig

MPO Version: 1.3.0

Cron configuration for scheduling Business API execution.

interface ApiCronSettingsConfig = {
  cronExpression : String;
}

SelectClauseSettings

MPO Version: 1.3.0

Defines which fields are included in the response of a Business API. Use this to limit returned properties for performance or visibility. This only affects the output of get and list APIs.

interface SelectClauseSettings = {
  selectProperties : PropRefer[];
  selectJoins : SelectJoin[];
}

SelectJoin

MPO Version: 1.3.0

Select join is a definition object for a join from the main object to another related data object to select additional properties from it.

interface SelectJoin = {
  joinName : String;
  condition : MScript;
  joinedDataObject : DataObjectName;
  selector : String;
  properties : PropRefer[];
  sortBy : SortByItem[];
  topPick : Integer;
}

SortByItem

MPO Version: 1.3.0

Sort clause configuration for list operations.

interface SortByItem = {
  property : PropRefer;
  order : SortOrder;
  name : String;
}

SortOrder

Defines sorting direction — ascending (asc) or descending (desc).

const SortOrder = {
  asc: "asc",
  desc: "desc",
};

DataClauseSettings

MPO Version: 1.3.0

Defines additional data values to be used in create or update operations. This clause augments the auto-generated data object by injecting or overriding values from context.

interface DataClauseSettings = {
  customData : DataMapItem[];
}

WhereClauseSettings

MPO Version: 1.3.0

Defines how records are filtered in a Business API. This includes:- selectBy: strict selection logic based on required field equality - fullWhereClause: an optional override for complex, flexible query logic - additionalClauses: optional conditional query fragments that are always appended to the WHERE clause, whether it is derived from selectBy or fullWhereClause. Use selectBy when your selection logic is static and business-critical (e.g., ['id']). Use fullWhereClause when the WHERE clause needs to be built dynamically using MScript. additionalClauses allow context-aware filtering such as role-based visibility or soft-delete exclusion.

interface WhereClauseSettings = {
  selectBy : PropRefer[];
  fullWhereClause : MScript;
  additionalClauses : ExtendedClause[];
}

ExtendedClause

MPO Version: 1.3.0

Defines an optional filtering clause that is dynamically included in the query when certain conditions are met. Enables route-level filtering to adapt to session, context, or other logic at runtime.

interface ExtendedClause = {
  name : String;
  doWhen : MScript;
  excludeWhen : MScript;
  whereClause : MScript;
}

DeleteOptions

MPO Version: 1.3.0

Defines behavior for delete-type Business APIs, including soft deletion logic.

interface DeleteOptions = {
  useSoftDelete : Boolean;
}

GetOptions

MPO Version: 1.3.0

Options specific to get-type Business APIs for customizing how a single record is fetched.

interface GetOptions = {
  setAsRead : DataMapItem[];
}

ListOptions

MPO Version: 1.3.0

Behavioral options for Business APIs of type list. These control sorting, grouping, filtering, and caching logic.

interface ListOptions = {
  listSortBy : SortByItem[];
  listGroupBy : PropRefer[];
  topPick : Integer;
  queryCache : Boolean;
  setAsRead : DataMapItem[];
  permissionFilters : ListPermissionFilter[];
  membershipFilters : ListMembershipFilter[];
  searchFilter : ListSearchFilter;
  jointFilters : ListJointFilterSettings;
  queryFiltersActive : Boolean;
}

ListPermissionFilter

MPO Version: 1.3.0

Permission-based filter that operate on list queries before execution. This is used for object based permissions assigned to a specific role or user

interface ListPermissionFilter = {
  name : String;
  condition : MScript;
  permission : String;
}

ListMembershipFilter

MPO Version: 1.3.0

A settings object to add a membership filter to the WHERE clause of the list. If given more than any one membership of all will be enough to select the object.

interface ListMembershipFilter = {
  name : String;
  dataObjectName : DataObjectName;
  objectKeyIdField : PropRefer;
  userKey : MScript;
  checkFor : MScript;
  condition : MScript;
}

ListSearchFilter

MPO Version: 1.3.0

Searches one or more records from the main data object and uses the id array in the where clause of the list. The search is made in elastic search index and the result id array is appended to the where clause of the main query.

interface ListSearchFilter = {
  hasSearchFilter : Boolean;
  condition : MScript;
  keyword : MScript;
  searchProperties : PropRefer[];
}

ListJointFilterSettings

MPO Version: 1.3.0

The settings definition for a list api to define any joint filter and combine them with an AND or OR operator

interface ListJointFilterSettings = {
  operator : FilterOperator;
  filters : ListJointFilter[];
}

FilterOperator

Filter combination is used to define how any multiple id arrayy based list filters will be combined

const FilterOperator = {
  AND: "AND",
  OR: "OR",
};

ListJointFilter

MPO Version: 1.3.0

ListJointFilter definition object for a joint filter from the main object to another related data object to filter the main list result. This is like lefy join in the where clause. If you want to filter your list result with a criteria which is evaluated in a related object other than main object, you can use joint filter.

interface ListJointFilter = {
  name : String;
  condition : MScript;
  joinedDataObject : DataObjectName;
  selector : String;
  whereClause : MScript;
}

PaginationOptions

MPO Version: 1.3.0

Defines how pagination is handled in list-type Business APIs.

interface PaginationOptions = {
  paginationEnabled : Boolean;
  defaultPageRowCount : Integer;
}

BusinessApiActionStore

MPO Version: 1.3.0

Represents the centralized registry of all executable logic units (actions) that can be used inside a Business API's workflow. Each action is categorized by purpose and referenced by name within the workflow stages. This store enables declarative composition of API behavior, including data manipulation, inter-service communication, access control, AI operations, and more.

interface BusinessApiActionStore = {
  fetchObjectActions : FetchObjectAction[];
  fetchStatsActions : FetchStatsAction[];
  fetchParentActions : FetchParentAction[];
  searchObjectActions : SearchObjectAction[];
  fetchFromElasticActions : FetchFromElasticAction[];
  collateListsActions : CollateListsAction[];
  functionCallActions : FunctionCallAction[];
  arrowFunctionActions : ArrowFunctionAction[];
  listMapActions : ListMapAction[];
  interserviceCallActions : InterserviceCallAction[];
  createCrudActions : CreateCrudAction[];
  createBulkCrudActions : CreateBulkCrudAction[];
  deleteCrudActions : DeleteCrudAction[];
  updateCrudActions : UpdateCrudAction[];
  apiCallActions : ApiCallAction[];
  aiCallActions : AiCallAction[];
  membershipCheckActions : MembershipCheckAction[];
  permissionCheckActions : PermissionCheckAction[];
  objectPermissionActions : ObjectPermissionCheckAction[];
  readJwtTokenActions : ReadJwtTokenAction[];
  validationActions : ValidationAction[];
  addToContextActions : AddToContextAction[];
  addToResponseActions : AddToResponseAction[];
  removeFromResponseActions : RemoveFromResponseAction[];
  renderDataActions : RenderDataAction[];
  dataToFileActions : DataToFileAction[];
  redirectActions : RedirectAction[];
  createJWTTokenActions : CreateJWTTokenAction[];
  createObjectActions : CreateObjectAction[];
  createBucketTokenActions : CreateBucketTokenAction[];
  publishEventActions : PublishEventAction[];
  readFromRedisActions : ReadFromRedisAction[];
  writeToRedisActions : WriteToRedisAction[];
  sendMailActions : SendMailAction[];
  sendSmsActions : SendSmsAction[];
  sendPushNotificationActions : SendPushNotificationAction[];
  refineByAiActions : RefineByAiAction[];
  paymentActions : PaymentAction[];
  verifyWebhookActions : VerifyWebhookAction[];
  integrationActions : IntegrationAction[];
  loopActions : LoopAction[];
  parallelActions : ParallelAction[];
  cartValidationActions : CartValidationAction[];
  cartCheckoutActions : CartCheckoutAction[];
  couponValidationActions : CouponValidationAction[];
  emitSseEventActions : EmitSseEventAction[];
  iteratorActions : IteratorAction[];
}

FetchObjectAction

MPO Version: 1.3.0

Fetches one or more records from a foreign or related data object and stores the result in the context or response. Supports key-based lookup or complex query filtering. Commonly used to enrich the current object with external data before proceeding with workflow logic. It can return null or raise a 404 error when no objects found according to isRequired property.

interface FetchObjectAction extends BusinessApiAction = {
  targetObject : DataObjectName;
  matchValue : MScript;
  localKey : PropRefer;
  whereClause : MScript;
  properties : PropRefer[];
  isArray : Boolean;
  isRequired : Boolean;
}

FetchStatsAction

MPO Version: 1.3.0

An action used to compute inline aggregate statistics (e.g., count, min, max, sum) from a data object. Ideal for Business APIs that need quick numerical insights tied to context. Use for simple stat enrichment for single or multiple bindings; for complex use cases, consider dedicated stat APIs or BFF services. Note that this action collects the stat values from elastc search using aggregations features.

interface FetchStatsAction extends BusinessApiAction = {
  targetObject : DataObjectName;
  matchValue : MScript;
  localKey : PropRefer;
  whereClause : MScript;
  stats : String[];
  bucketBy : PropRefer;
}

FetchParentAction

MPO Version: 1.3.0

Fetches selected properties from a parent object related to the current object in context. Typically used to enrich the response or inform access and validation logic with values inherited from a higher-level entity (e.g., organization, project). The parentObject can be a local data object (same service) or a remote data object (different service). For remote parent objects, the action automatically fetches from Elasticsearch, enabling seamless inter-service parent data retrieval. Important: A relation to the parent object must be defined in the current dbObject's properties for this action to work.

interface FetchParentAction extends BusinessApiAction = {
  parentObject : DataObjectName;
  properties : PropRefer[];
}

SearchObjectAction

MPO Version: 1.3.0

Searches one or more records from the main data object or a foreign or related data object and stores the result in the context as an id array. The search is made in elastic search index and the returned id array can be used in the where clause of the main query.

interface SearchObjectAction extends BusinessApiAction = {
  targetObject : DataObjectName;
  keyword : MScript;
  searchProperties : PropRefer[];
}

FetchFromElasticAction

MPO Version: 1.3.0

Fetches data object data from its elastic search index, using a given elastic raw search body, and returning elastic response as half baked, an items array for normalized hits result and an aggreagtions object in elastic search aggregation resul format. Top_hits style aggregations are also normalized as items array.

interface FetchFromElasticAction extends BusinessApiAction = {
  targetObject : DataObjectName;
  body : MScript;
}

CollateListsAction

MPO Version: 1.3.0

Use CollateListsAction to collate a list of objects to another list of objects like aggregating an adress list to a user list.

interface CollateListsAction extends BusinessApiAction = {
  sourceList : MScript;
  targetList : MScript;
  sourceKey : String;
  targetKey : String;
  nameInTarget : String;
  targetIsArray : Boolean;
}

FunctionCallAction

MPO Version: 1.3.0

Defines a reusable logic step that calls a library-defined function using MScript syntax. This action allows for custom transformation, enrichment, or computation during the execution of a Business API. It is often used to prepare derived values, calculate totals, or apply shared service logic prior to validation or response shaping.

interface FunctionCallAction extends BusinessApiAction = {
  callScript : MScript;
}

ArrowFunctionAction

MPO Version: 1.3.0

This action defines a reusable function and sets it to the context with the contextPropertyName name.

interface ArrowFunctionAction extends BusinessApiAction = {
  parameterNames : String[];
  functionBody : Text;
}

ListMapAction

MPO Version: 1.3.0

This action crerates a new list out of a current list by mapping its items with MScript. The new list is stored to contextPropertyName

interface ListMapAction extends BusinessApiAction = {
  sourceList : MScript;
  itemName : String;
  mapScript : MScript;
}

InterserviceCallAction

MPO Version: 1.3.0

Calls another Business API defined in a different microservice. This enables inter-service coordination within a Mindbricks-powered system. The response can be extracted into the context or added to the API response. This action supports dynamic parameters and flexible response handling.

interface InterserviceCallAction extends BusinessApiAction = {
  targetService : String;
  targetApi : String;
  apiParameters : DataMapItem[];
  responseProperty : String;
  isArray : Boolean;
}

CreateCrudAction

MPO Version: 1.3.0

Defines an embedded creation operation for a related data object—typically a child or associated entity—within a Business API. These actions enable transactional or cascading object creation as part of a larger business operation. Often used when the main API creates or updates a parent object and simultaneously needs to initialize dependent records (e.g., child tasks, audit logs, attachments). The childObject can belong to the same service (local) or to another service (remote). For remote objects, the action automatically routes to the target service's M2M edge function using machine-to-machine authentication, ensuring secure inter-service communication. In multi-tenant scenarios, the tenant codename is automatically propagated to the remote service.

interface CreateCrudAction extends BusinessApiAction = {
  childObject : DataObjectName;
  dataClause : ApiAggregateData[];
}

ApiAggregateData

MPO Version: 1.3.0

Defines a single property-value pair used to populate a related data object during an aggregated operation. This structure is used in CreateCrudAction and UpdateCrudAction to specify how each property of the child object should be assigned—either statically or dynamically—from the API execution context.

interface ApiAggregateData = {
  dataProperty : PropRefer;
  dataValue : MScript;
}

CreateBulkCrudAction

MPO Version: 1.3.0

Defines a bulk creation operation for multiple related data objects—typically child or associated entities—within a Business API. These actions enable transactional bulk object creation as part of a larger business operation. Often used when the main API needs to create multiple child records at once (e.g., bulk creating child tasks, audit logs, or attachments). The objects parameter is an MScript expression that evaluates to an array of objects, where each object contains the property-value mappings for a single record to be created. The childObject can belong to the same service (local) or to another service (remote). For remote objects, the action automatically routes to the target service's M2M edge function using machine-to-machine authentication, ensuring secure inter-service communication. In multi-tenant scenarios, the tenant codename is automatically propagated to the remote service.

interface CreateBulkCrudAction extends BusinessApiAction = {
  childObject : DataObjectName;
  objects : MScript;
}

DeleteCrudAction

MPO Version: 1.3.0

Defines an embedded delete operation to remove related records—typically child or connected entities—within a Business API. This action allows declarative, conditional deletion of external data objects that are linked to the primary object. It is typically used for cascading deletes, cleanup logic, or enforcing referential integrity in business processes. The childObject can belong to the same service (local) or to another service (remote). For remote objects, the action automatically routes to the target service's M2M edge function (m2mDelete{ObjectName}ByQuery) using machine-to-machine authentication, ensuring secure inter-service communication. In multi-tenant scenarios, the tenant codename is automatically propagated to the remote service.

interface DeleteCrudAction extends BusinessApiAction = {
  childObject : DataObjectName;
  whereClause : MScript;
}

UpdateCrudAction

MPO Version: 1.3.0

Defines an embedded update operation for related data objects—typically child or connected entities—within a Business API. This action is used when the API needs to selectively update external records based on a condition. It is commonly applied after creating or modifying a parent object to ensure consistency or to propagate business state changes across related objects. The childObject can belong to the same service (local) or to another service (remote). For remote objects, the action automatically routes to the target service's M2M edge function (m2mUpdate{ObjectName}ByQuery) using machine-to-machine authentication, ensuring secure inter-service communication. In multi-tenant scenarios, the tenant codename is automatically propagated to the remote service.

interface UpdateCrudAction extends BusinessApiAction = {
  childObject : DataObjectName;
  whereClause : MScript;
  dataClause : ApiAggregateData[];
}

ApiCallAction

MPO Version: 1.3.0

Calls an external or internal HTTP API during Business API execution. This is ideal for integrating with third-party services or internal utility endpoints. The fetched result is stored in context and optionally written to the response. Input and output transformation are supported.

interface ApiCallAction extends BusinessApiAction = {
  apiCallRequest : HTTPRequest;
  isArray : Boolean;
  apiFetchProperty : String;
}

HTTPRequest

MPO Version: 1.3.0

Defines a reusable HTTP request configuration to interact with a remote service and retrieve a JSON response. This object is used across the platform for scenarios such as remote authentication, remote data access, and integration with external APIs (CRUD operations, searches, etc.).

interface HTTPRequest = {
  httpRequestUrl : String;
  httpRequestMethod : HTTPRequestMethods;
  tokenLocation : RequestLocations;
  tokenName : String;
  tokenValue : String;
  httpRequestParameters : HTTPRequestParameters;
  cacheResponse : Boolean;
}

HTTPRequestMethods

An enum representing the HTTP method to use in a request.

const HTTPRequestMethods = {
  GET: "GET",
  POST: "POST",
  PUT: "PUT",
  PATCH: "PATCH",
  DELETE: "DELETE",
};

HTTPRequestParameters

MPO Version: 1.3.0

Defines the parameters to be sent with an HTTP request. This includes data sent in the request body, query string, headers, or cookies.

interface HTTPRequestParameters = {
  httpRequestBody : DataMapItem[];
  httpRequestQuery : DataMapItem[];
  httpRequestHeaders : DataMapItem[];
  httpRequestCookies : DataMapItem[];
}

AiCallAction

MPO Version: 1.3.0

Invokes an AI model such as OpenAI or Anthropic to perform text generation, refinement, classification, or summarization. The prompt is composed from a template and context, and the result is stored in the context and optionally exposed in the response.

interface AiCallAction extends BusinessApiAction = {
  promptTemplate : AIPromptTemplate;
  isArray : Boolean;
  aiFetchProperty : String;
  responseFormat : String;
  model : String;
}

AIPromptTemplate

MPO Version: 1.3.0

Defines the structure of an AI prompt using a two-part design: a static system-level instruction and a dynamic user message populated via MScript from the current context. Used in AiCallAction to guide AI model behavior.

interface AIPromptTemplate = {
  systemPrompt : Text;
  userPrompt : MScript;
}

MembershipCheckAction

MPO Version: 1.3.0

Defines access control based on membership rules configured on a data object. This is used when access to a Business API operation depends on whether the current user is a member of a related entity, such as a project, team, or organization. The dataObjectName field specifies which object’s membership rules should be applied—if omitted, the main data object of the Business API is used by default. This action supports direct and nested membership checks, such as validating access to a parent organization while updating a child project.

interface MembershipCheckAction extends BusinessApiAction = {
  dataObjectName : DataObjectName;
  objectKey : MScript;
  userKey : MScript;
  checkFor : MScript;
  checkType : ApiCheckType;
  errorMessage : String;
}

ApiCheckType

Defines how the result of a validation, permission, or membership check is used within the Business API lifecycle.

const ApiCheckType = {
  storedCheck: "storedCheck",
  liveCheck: "liveCheck",
};

PermissionCheckAction

MPO Version: 1.3.0

Defines a global permission check that evaluates whether the user holds specific platform or service-level permissions. This check is not tied to any particular object instance and is useful for validating roles such as canAccessAdminPanel, canExportData, or canSendEmails. You can either enforce the result immediately or store it in context for conditional usage later in the flow.

interface PermissionCheckAction extends BusinessApiAction = {
  permissionName : String;
  checkType : ApiCheckType;
}

ObjectPermissionCheckAction

MPO Version: 1.3.0

Performs a permission check scoped to a specific object instance. It evaluates whether the current user has the required permissions on the resolved object, based on all applicable sources: directly assigned object permissions, inherited permissions from parent contexts (e.g., user or role permissions), and dynamic ABAC rules that intersect with the object’s attributes. This check is used when fine-grained, instance-level authorization is required.

interface ObjectPermissionCheckAction extends BusinessApiAction = {
  permissionName : String[];
  readObjectIdFrom : MScript;
  checkType : ApiCheckType;
}

ReadJwtTokenAction

MPO Version: 1.3.0

Defines a read jwt token operation from either context, session or request and write its payload to the context with the contextPropertyName after validating it. The token signature should be in HMAC format. The token payload may be used for allowing access to an object via a signed token instead of standard authentication. This is typically used for public or limited-access sharing workflows (e.g., view-only links). Once the token payload is in context any other validations may be performed using the payload values in further actions.

interface ReadJwtTokenAction extends BusinessApiAction = {
  readTokenFrom : MScript;
  jwtKey : MScript;
  isRequired : Boolean;
  statusCheck : MScript;
}

ValidationAction

MPO Version: 1.3.0

Defines a flexible business rule that performs a dynamic condition check during Business API execution. Unlike permission or membership checks, a ValidationAction is fully script-based and domain-specific, allowing complex logical conditions such as subscription status, object states, quota limits, feature flags, or compliance rules. If the validation fails, the system either throws an error (liveCheck) or stores the result in context for later decision-making (storedCheck).

interface ValidationAction extends BusinessApiAction = {
  description : Text;
  shouldBeTrue : Boolean;
  checkType : ApiCheckType;
  validationScript : MScript;
  errorMessage : String;
  errorStatus : ErrorStatus;
}

ErrorStatus

Mindbricks error status codes represent standardized HTTP-style error responses used across all controller types. These codes provide consistent semantic feedback for route errors, especially in REST APIs.

const ErrorStatus = {
  400: "400",
  401: "401",
  403: "403",
  404: "404",
  500: "500",
};

AddToContextAction

MPO Version: 1.3.0

Adds one or more calculated values to the runtime context (this) at a specific point in the Business API flow. This is typically used to prepare values that will be referenced in later actions, such as computed totals, enriched properties, or temporary flags. The values are evaluated via MScript and written under the names you specify.

interface AddToContextAction extends BusinessApiAction = {
  context : ContextData[];
}

ContextData

MPO Version: 1.3.0

ContextData is a container object to represent any key-value pair to write or read to/from context.

interface ContextData = {
  contextName : String;
  contextValue : MScript;
}

AddToResponseAction

MPO Version: 1.3.0

Adds one or more properties from the current context to the final response object after the main operation completes. This is useful when some values are computed or fetched indirectly (e.g., session-based, Redis-loaded, or generated) and need to be exposed in the API response explicitly.

interface AddToResponseAction extends BusinessApiAction = {
  context : ContextData[];
}

RemoveFromResponseAction

MPO Version: 1.3.0

Removes one or more properties from the final API response before it is returned to the client. This is useful for eliminating internal, sensitive, or unnecessary fields that were added by earlier actions or populated from context. Commonly used to enforce privacy, avoid leaking implementation details, or to conform to specific output schemas.

interface RemoveFromResponseAction extends BusinessApiAction = {
  properties : String[];
}

RenderDataAction

MPO Version: 1.3.0

Generates a formatted string output by applying a predefined template to structured data using MScript. This is typically used to render email bodies, documents, files, or markdown/html content from API context values. The rendered result is saved into context (with contextPropertyName) and can be reused in subsequent actions such as email sending, file export, or response shaping.

interface RenderDataAction extends BusinessApiAction = {
  inputData : MScript;
  template : String;
}

DataToFileAction

MPO Version: 1.3.0

Converts a given input into a downloadable file format such as CSV, JSON, or PDF. The data is prepared using an MScript expression and can be either returned to the client immediately or saved for internal use. Use this action when you need to export structured output from a Business API response or context.

interface DataToFileAction extends BusinessApiAction = {
  inputData : MScript;
  outputFormat : FileFormats;
  sendToClient : Boolean;
}

FileFormats

Specifies supported output formats for content generation, serialization, or export. These are primarily text-based formats, suitable for structured data, document rendering, and developer-facing outputs.

const FileFormats = {
  json: "json",
  xml: "xml",
  csv: "csv",
  tsv: "tsv",
  txt: "txt",
  html: "html",
  md: "md",
  yaml: "yaml",
  yml: "yml",
  svg: "svg",
  pdf: "pdf",
  rtf: "rtf",
  log: "log",
  tex: "tex",
};

RedirectAction

MPO Version: 1.3.0

Redirects the client to a new URL after the API execution. This is often used in web-based flows like OAuth callbacks, login success handlers, or conditional navigation.

interface RedirectAction extends BusinessApiAction = {
  redirectUrl : HTTPRequest;
}

CreateJWTTokenAction

MPO Version: 1.3.0

Generates a signed JWT token from a given payload. This token can be stored in context or included in the API response for client use. Typically used for authentication or temporary session flows.

interface CreateJWTTokenAction extends BusinessApiAction = {
  JWTKey : MScript;
  payload : MScript;
}

CreateObjectAction

MPO Version: 1.3.0

Constructs an in-memory JavaScript object from key-value pairs and writes it to the context. This action does not persist data to the database. It is typically used to prepare structured data for use in other actions such as sending emails, rendering templates, API calls, or forming response objects.

interface CreateObjectAction extends BusinessApiAction = {
  payload : ObjectData[];
  mergeObject : MScript;
}

ObjectData

MPO Version: 1.3.0

Represents a single property assignment used when constructing a new object via CreateObjectAction. The value is evaluated dynamically from context.

interface ObjectData = {
  key : String;
  value : MScript;
}

CreateBucketTokenAction

MPO Version: 1.3.0

Generates a signed JWT token including a standard bucket permission paylod. This token can be stored in context or included in the API response for client use. Typically used for accessing Mindbricks Bucket service.

interface CreateBucketTokenAction extends BusinessApiAction = {
  bucketPermissions : BucketPermission[];
}

BucketPermission

MPO Version: 1.3.0

An object to define an access to a specific bucket with a specific permission.

interface BucketPermission = {
  bucketName : String;
  bucketId : MScript;
  permissionType : BucketPermissionType;
  isPublic : Boolean;
}

BucketPermissionType

An enum type to define the access right of a bucket token.

const BucketPermissionType = {
  read: "read",
  write: "write",
};

PublishEventAction

MPO Version: 1.3.0

Publishes a message to an event topic (such as a message bus, queue, or pub/sub channel) as part of the Business API flow. This action is used to emit domain events or trigger asynchronous workflows that are consumed by other services or systems. The payload is defined using MScript and can include structured data from the API context.

interface PublishEventAction extends BusinessApiAction = {
  topic : String;
  message : MScript;
}

ReadFromRedisAction

MPO Version: 1.3.0

Reads a value from Redis using a dynamically computed key and writes the result into the context under a specified property name (contextPropertyName). This action is typically used to retrieve session data, temporary values, or cached results that are needed later in the API flow. The retrieved value becomes accessible to other actions using this.<contextName>.

interface ReadFromRedisAction extends BusinessApiAction = {
  redisKey : MScript;
}

WriteToRedisAction

MPO Version: 1.3.0

Writes a value to Redis under a computed key. The value is defined via MScript and can include dynamic data from the current context. This is typically used for storing transient data such as verification tokens, process state, or temporary API results.

interface WriteToRedisAction extends BusinessApiAction = {
  redisKey : MScript;
  message : MScript;
}

SendMailAction

MPO Version: 1.3.0

Sends an email using a configured email provider. The subject, body, and recipient addresses are defined via MScript and can be dynamically constructed from context. This action is commonly used for transactional notifications, confirmations, or alerts.

interface SendMailAction extends BusinessApiAction = {
  provider : String;
  subject : MScript;
  body : MScript;
  to : MScript;
  from : MScript;
  cc : MScript;
}

SendSmsAction

MPO Version: 1.3.0

Sends an SMS message using a configured SMS provider. The recipient phone number, message content, and sender ID are defined using MScript expressions. Useful for OTPs, short notifications, or alerts.

interface SendSmsAction extends BusinessApiAction = {
  provider : String;
  subject : MScript;
  body : MScript;
  to : MScript;
  from : MScript;
}

SendPushNotificationAction

MPO Version: 1.3.0

Sends a push notification using a configured provider (e.g., Firebase, OneSignal). Subject and body are rendered via MScript and sent to the recipient device or user ID. Suitable for in-app or mobile alerts.

interface SendPushNotificationAction extends BusinessApiAction = {
  provider : String;
  subject : MScript;
  body : MScript;
  to : MScript;
  from : MScript;
}

RefineByAiAction

MPO Version: 1.3.0

Refines or transforms a given text using an AI provider such as OpenAI or Anthropic. The action supports adjustable refinement depth via temperature and mode, and allows instruction control through a system prompt. The result is stored in the context and can be reused in rendering, messaging, or responses. Use this for rephrasing, summarizing, tone-shifting, or grammar correction.

interface RefineByAiAction extends BusinessApiAction = {
  provider : String;
  inputData : MScript;
  systemPrompt : String;
  temperature : Double;
  mode : String;
}

PaymentAction

MPO Version: 1.3.0

Calls the proper native payment gateway functions according to the current stage of payment lifecycle. Currently Stripe is supported natively, for other gateways use integrations.

interface PaymentAction extends BusinessApiAction = {
  gateway : String;
  stage : PaymentStage;
}

PaymentStage

The target stage of the payment lifecycle on which the action's decision for next step to be executed is based.

const PaymentStage = {
  simple: "simple",
  start: "start",
  complete: "complete",
  refresh: "refresh",
  callback: "callback",
};

VerifyWebhookAction

MPO Version: 1.3.0

Verifies a webhook call of a provider with its signature secret and reads the parameeters and writes them to the context.

interface VerifyWebhookAction extends BusinessApiAction = {
  provider : String;
  secretKey : MScript;
}

IntegrationAction

MPO Version: 1.3.0

Calls a native API integration provided by Mindbricks (e.g., AWS S3, Airtable, Stripe, Asana). Each integration exposes a set of predefined actions, and this object triggers one of them with dynamically computed parameters. The result is stored in the context and can be used in follow-up steps. This allows low-code access to third-party systems using structured inputs.

interface IntegrationAction extends BusinessApiAction = {
  provider : IntegrationProvider;
  action : String;
  parameters : IntegrationParameter[];
}

IntegrationParameter

MPO Version: 1.3.0

Defines a single named input to be passed to a native integration provider action. Parameter values are evaluated using MScript and can be derived from session, context, or external input.

interface IntegrationParameter = {
  parameterName : String;
  parameterValue : MScript;
}

LoopAction

MPO Version: 1.3.0

Defines a repeated execution block within a Business API workflow. It loops over the result of an MScript expression and executes a list of actions for each item. The current item is exposed as a local variable named by loopItemName, directly accessible in MScript. Loop actions can be nested to support multi-level iteration, enabling hierarchical or grid-like data processing patterns.

interface LoopAction extends BusinessApiAction = {
  loopFor : MScript;
  loopItemName : String;
  isParallel : Boolean;
  actions : String[];
}

ParallelAction

MPO Version: 1.3.0

Defines a non-blocking execution group in which multiple actions are executed in parallel. Each action runs independently using the same input context. Parallel actions are useful for concurrent fetches, validations, or other side-effect-free logic. This action can also include nested ParallelAction or LoopAction steps, enabling concurrent or branched execution across multiple layers of the workflow.

interface ParallelAction extends BusinessApiAction = {
  actions : String[];
}

CartValidationAction

MPO Version: 1.3.0

Validates a shopping cart before checkout. Checks that items exist, stock is available, prices are valid, and minimum order requirements are met. The validation results are written to the context for use in subsequent actions.

interface CartValidationAction extends BusinessApiAction = {
  validations : CartValidationType[];
  failFast : Boolean;
}

CartValidationType

Types of validations that can be performed on a shopping cart before checkout.

const CartValidationType = {
  itemsExist: "itemsExist",
  stockAvailable: "stockAvailable",
  pricesValid: "pricesValid",
  minimumOrderMet: "minimumOrderMet",
  shippingAddressValid: "shippingAddressValid",
  promotionsValid: "promotionsValid",
};

CartCheckoutAction

MPO Version: 1.3.0

Processes shopping cart checkout. Handles inventory reservation, promotion usage recording, order creation, and cart clearing. The checkout result is written to the context.

interface CartCheckoutAction extends BusinessApiAction = {
  stage : CartCheckoutStage;
  clearCartAfterCheckout : Boolean;
  recordPromotionUsage : Boolean;
}

CartCheckoutStage

Stages of the shopping cart checkout process.

const CartCheckoutStage = {
  validate: "validate",
  process: "process",
  finalize: "finalize",
};

CouponValidationAction

MPO Version: 1.3.0

Validates a coupon code for eligibility. Checks code validity, expiration dates, usage limits, minimum order requirements, and calculates the discount amount. Results are written to the context.

interface CouponValidationAction extends BusinessApiAction = {
  checkUsageLimits : Boolean;
  checkExpiration : Boolean;
  calculateDiscount : Boolean;
}

EmitSseEventAction

MPO Version: 1.3.0

Emits a custom SSE event during the workflow. The event name and payload are declaratively configured. When the API is called via REST (no SSE context), this action is a silent no-op.

interface EmitSseEventAction extends BusinessApiAction = {
  eventName : String;
  data : MScript;
}

IteratorAction

MPO Version: 1.3.0

A generic streaming action whose method returns an async iterable. The sourceScript MScript expression must evaluate to an object with Symbol.asyncIterator (async generator, readable stream, etc.). Designed for custom streaming logic that isn't covered by AiCallAction.

interface IteratorAction extends BusinessApiAction = {
  sourceScript : MScript;
}

BusinessWorkflow

MPO Version: 1.3.0

Defines the execution flow milestones of a Business API. Only one of the sub-flows (create, update, delete, get, list) will be populated, based on the crudType of the API. Each workflow contains ordered arrays of action ids to be executed at predefined lifecycle milestones (e.g., after reading parameters, after the main DB operation). These workflows allow complete control of the API's logic and are fully compatible with visual workflow editors.

interface BusinessWorkflow = {
  create : CreateBusinessWorkflow;
  update : UpdateBusinessWorkflow;
  delete : DeleteBusinessWorkflow;
  get : GetBusinessWorkflow;
  list : ListBusinessWorkflow;
}

CreateBusinessWorkflow

MPO Version: 1.3.0

Defines the standard execution milestones for a create-type Business API. Each field represents a milestone (a fixed lifecycle stage), and its value is an ordered list of action ids executed by the API manager. These steps include all default, hardcoded logic (e.g., session handling, parameter extraction, DB insert) while leaving space for user-defined actions after each milestone. You can modify this workflow programmatically or visually.

interface CreateBusinessWorkflow = {
  afterStartBusinessApi : String[];
  afterReadParameters : String[];
  afterTransposeParameters : String[];
  afterCheckParameters : String[];
  afterCheckBasicAuth : String[];
  afterBuildDataClause : String[];
  afterMainCreateOperation : String[];
  afterBuildOutput : String[];
  afterSendResponse : String[];
  afterApiEvent : String[];
}

UpdateBusinessWorkflow

MPO Version: 1.3.0

Defines the execution milestones for an update-type Business API, used to modify an existing record. Each field represents a fixed lifecycle milestone. Custom action ids placed under a milestone will be executed in order after that point. These workflows enable full customization of business logic without overriding default update behavior, and they support visual modeling of logic steps.

interface UpdateBusinessWorkflow = {
  afterStartBusinessApi : String[];
  afterReadParameters : String[];
  afterTransposeParameters : String[];
  afterCheckParameters : String[];
  afterCheckBasicAuth : String[];
  afterBuildWhereClause : String[];
  afterFetchInstance : String[];
  afterCheckInstance : String[];
  afterBuildDataClause : String[];
  afterMainUpdateOperation : String[];
  afterBuildOutput : String[];
  afterSendResponse : String[];
  afterApiEvent : String[];
}

DeleteBusinessWorkflow

MPO Version: 1.3.0

Defines the execution milestones for a delete-type Business API, which removes or soft-deletes a single record. Each field corresponds to a lifecycle milestone. Custom actions inserted at any milestone are executed in order after that point. This enables fine-grained control over logic such as confirmation checks, permission gating, logging, or external integrations—without needing to override the default deletion behavior.

interface DeleteBusinessWorkflow = {
  afterStartBusinessApi : String[];
  afterReadParameters : String[];
  afterTransposeParameters : String[];
  afterCheckParameters : String[];
  afterCheckBasicAuth : String[];
  afterBuildWhereClause : String[];
  afterFetchInstance : String[];
  afterCheckInstance : String[];
  afterMainDeleteOperation : String[];
  afterBuildOutput : String[];
  afterSendResponse : String[];
  afterApiEvent : String[];
}

GetBusinessWorkflow

MPO Version: 1.3.0

Defines the execution milestones for a get-type Business API, which retrieves a single record. Each milestone represents a predefined point in the API lifecycle. Action ids listed under a milestone will be executed in the given order immediately after that point is reached. This structure enables customized behaviors like access control, derived property enrichment, or API shaping without overriding core logic.

interface GetBusinessWorkflow = {
  afterStartBusinessApi : String[];
  afterReadParameters : String[];
  afterTransposeParameters : String[];
  afterCheckParameters : String[];
  afterCheckBasicAuth : String[];
  afterBuildWhereClause : String[];
  afterMainGetOperation : String[];
  afterCheckInstance : String[];
  afterBuildOutput : String[];
  afterSendResponse : String[];
  afterApiEvent : String[];
}

ListBusinessWorkflow

MPO Version: 1.3.0

Defines the execution milestones for a list-type Business API, which returns a paginated set of records. Each field represents a fixed lifecycle milestone. Action ids added to a milestone will be executed in order after that point. This structure enables modular extension of logic for filtering, permission enforcement, data enrichment, and more—without overriding the main query behavior.

interface ListBusinessWorkflow = {
  afterStartBusinessApi : String[];
  afterReadParameters : String[];
  afterTransposeParameters : String[];
  afterCheckParameters : String[];
  afterCheckBasicAuth : String[];
  afterBuildWhereClause : String[];
  afterMainListOperation : String[];
  afterBuildOutput : String[];
  afterSendResponse : String[];
  afterApiEvent : String[];
}