A mandatory layer is a layer in your design that you designate as a required field for any generation made via the API.
When a layer is marked as mandatory, the Abyssale API will reject any generation request that does not provide a new value for that specific layer. This feature acts as a critical safeguard to prevent accidental generations with placeholder data (e.g., "Your Name Here") and ensures that every visual created through your automation is complete and correct.
This setting only affects API-based generation and has no effect on designs created or edited manually within the Design Builder, or variation generated from the other methods (Quick generation, Spreadsheet, Dynamic image url)
Key Benefits
Enforce Data Integrity: Guarantee that essential elements like names, job titles, product images, or prices are always populated in your automated visuals.
Simplify Development: Receive clear, actionable error messages from the API when a required field is missing, making it faster to debug your integration.
Build Robust Workflows: Programmatically identify which fields are required for a given template, allowing you to build more intelligent user interfaces or data validation logic.
How to Set a Layer as Mandatory
You can enable this feature from within the settings of a specific design.
Open your design.
In the right panel bar, click the Settings tab.
In the settings panel, navigate to the "Layer Configuration" section.
You will see a list of all layers in your design. Select the layer you want to make mandatory.
Enable the toggle switch for the option labeled "Mark Layer as Mandatory (API Generation Only)".
Click Save to apply your changes.
Repeat this process for any other layers you wish to enforce as mandatory.
Working with Mandatory Layers in the API
Once a layer is set as mandatory, your API integration will need to handle it in two ways:
Identifying Mandatory Layers
Before making a generation call, you can determine which layers are required by querying the design details.
Make a GET request to the /designs/{template_id} endpoint. In the JSON response, each layer will now contain a settings object. If a layer is mandatory, is_mandatory will be set to true.
Example JSON Response:
You can use this flag in your code to validate data or dynamically build a form that indicates required fields to the end-user.
Making a Generation Call
When making a POST request to generate a new visual, you must provide a new value in the payload for every layer where is_mandatory is true.
Important: The default value saved in the template is not sufficient. The API requires an explicit value in the request body.
If you fail to provide a value for a mandatory layer, the API will reject the request with a 422 Unprocessable Entity status code and a descriptive error message.
Example Error Response:
Invalid parameters: elements.layer_name.payload: Mandatory field is required. Default value is: VALUE
By handling this error, you can build a resilient system that prompts for the missing data or flags an issue for review.