Integrate APIs
APIs let your app read data from external systems or invoke their capabilities. Momen turns the configured inputs and response schema into bindable data so the same API can be reused by pages, Actionflows, and AI Agents.
Before you start
Have the provider’s API documentation ready and identify:
- Request method and full URL
- Path, query, header, and body parameters
- Required fields, data types, and example values
- Example success and error responses
- Authentication method
If a request requires an API key, token, or private credential that must stay off the client, call the API from an Actionflow and bind a Secret. Do not bind sensitive credentials on a page or in a frontend action.
Configure an API
Add a configuration
Open Action → API, select Add config, and give the API a recognizable name.
Choose an operation type
The operation type determines the API’s primary use in the editor:
| Operation type | Use |
|---|---|
| Query | Read external data and use it as a page or list data source |
| Mutation | Create, update, delete, or perform another request with side effects through a frontend action or Actionflow node |
For a Query API, you can also configure its pagination method, page-number field, page-size field, and initial page number when the endpoint supports pagination.
Define the request
Enter edit mode, choose the request method, and enter the URL. Add parameters in the location required by the endpoint:
- Path for dynamic URL segments
- Query for URL query parameters
- Headers for request headers
- Body for request data
Set each field’s name, type, required state, and debug value. The body has one root value and can contain nested object or list fields.
Send a debug request
Select Debug, provide test values, and select Send. Verify the request, response status, and response data against the provider’s documentation.
After a successful request, open Advanced:
- Review the request parameters inferred from the debug request.
- Review the field structure for successful and failed responses.
- For an existing API, compare the user configuration, inferred configuration, and merged configuration.
- Select Save config when the structures are correct.
Momen treats 2xx responses as successful and 4xx or 5xx responses as failed. Callers expose bindable fields from the response structures saved here.
Decode special fields
Set an encoding when a response field is not directly usable:
| Encoding | Use |
|---|---|
| URL media encoding | Convert an image or other media URL into Momen media data |
| Base64 media encoding | Parse Base64 media content and convert it into Momen media data |
| JSON string encoding | Parse an escaped JSON string into an object or list |
For example, an endpoint may return:
{
"profile": "{\"name\":\"Ada\",\"level\":3}"
}After applying JSON string encoding to profile, its name and level fields become available for binding.
Publish the API
API edits are saved automatically but must be published before they take effect at runtime. Both Update preview and Sync changes publish the latest API, Actionflow, AI Agent, and other backend configurations. Update preview also refreshes the frontend preview.
When changing inputs or response fields already used by a page, Actionflow, or AI Agent, review every caller for compatibility.
Use an API
Use it as a data source
A Query API can provide data to a page, List, or another supported data-source location. Select the API, bind its inputs, and choose the response field that supplies the data.
If the endpoint supports pagination, also bind the page-number, page-size, or load-more settings defined in the API configuration.
Call it from a frontend action
A Mutation API can be called from a page or component:
- Add Call API under a Trigger.
- Select the API and bind its inputs.
- Under On success, read the successful response from
Context → Action results → Call API. - Under On failure, show an error message or add other error handling.
Call it from an Actionflow
Add an API node to the Actionflow, select the API, and bind its inputs. Later nodes can read the successful result; the failure branch can record the error, retry, or run compensation logic.
An API node has a 60-second limit from request start until the complete response is received. See Build Actionflows for the other timeout rules.
Use it as an AI Agent tool
Add the API under the AI Agent’s tools and provide a clear tool name, purpose, and parameter descriptions. The model decides whether to call it based on the conversation.
Do not rely on model tool selection for a mandatory business step such as creating an order. Put fixed steps in an Actionflow and expose that Actionflow as a tool instead. See Build AI Agents.
Troubleshooting
- Debug works, but the caller fails: Confirm that the API is published, the caller’s input types match the current configuration, and every required input has a value.
- Response fields are unavailable for binding: Debug the API again, verify the success or failure response structure under Advanced, and save the configuration.
- Existing callers fail after a response change: Check whether pages, Actionflows, or AI Agents still reference a removed field or an old field type.
- A media or JSON field cannot be decoded: Verify that the actual field content matches the selected encoding.
- The request times out: Confirm that the provider returns the complete response within the limit. For longer work, use the provider’s asynchronous API and obtain the result through a later query or Webhook.