Early Access  

This feature is not enabled for all users. If you’d like to try it out, please email our support team for early access.

Qntrl’s Inbound REST Web Service allows you to create custom API endpoints that external users or systems can call to perform specific actions inside Qntrl. When a user triggers the API, Qntrl receives the request and processes it based on the configured logic in a

Function script or Circuit.

Key Highlights  

• Custom Endpoints: Define REST API URLs specific to your business workflows. Example: https://<qntrl-domain>/webservice/<org_id>/<custom-endpoint>      

• Secure Access: Support for OAuth and API Key authentication.
• Smart Logic: Trigger custom scripts (Functions) or automated flows (Circuits).
  

If you want to customize your domain, use qntrls whitelabelling feature.

1. External system sends API request.
   
2. Qntrl receives and authenticates the request.
3. Configured logic is executed via Function or Circuit.
4. Response is sent back, and related actions are triggered inside Qntrl.
   

Create a Module     

1. Navigate to(settings) >> WEB SERVICES >> Inbound >> Select REST.
2. Click New Inbound REST.
3. Fill in the following fields:
   
1. 
   Name: Provide a logical name for the module (e.g., jobs, layouts). This helps group related APIs together.
   
2. 
   Base URI: Define the base path for the APIs in this module (e.g., /jobs). This prefix will appear in all API endpoints created under this module.
   
3. 
   Authentication Type: Qntrl uses the selected authentication type to validate incoming API requests. You can choose one of the following:
1. 
   OAuth: Secure the API with OAuth scopes or global tokens for the organization.
2. 
   API Key: Token-based authentication method. Add the API key in your request headers. Learn how to generate an API key.
4. 
   Description: Add a brief description of the module or the purpose of the APIs it contains.
   
4. Click Create.
   

Once the module is created, a configuration window will open to define the API endpoint details.

Configure the API Endpoint     

• Name: Provide a name for the API endpoint.

• URL: Define the endpoint path (e.g., /create). This will be appended to the module’s base URI.
• Preview: The system auto-generates the complete URL based on the base URI and endpoint path.
  Example: https://qntrl.com/webservice/668909960/jobs/create
• Method: Select the HTTP method — GET, POST, PUT, DELETE, OPTIONS, or PATCH.
• Resource Type: Choose the type of handler to execute when this API is called.

• Function: Use a function script to process the request.

• Select an existing REST-type function or create a new one.
• If creating a new function, write the script in the editor. The function will automatically be added to the Functions module with a generated name (you can rename it later).
• Inside the function script, you can define how the incoming request should be handled and what response should be returned.

• Circuit: Trigger a predefined Circuit when the API is hit. Circuits do not support file handling or response configuration (like success/error messages).

• Resource: Select the specific function or circuit to associate with the endpoint.

      

Function vs Circuit: How Resource Execution Works     

Function Resource

• The script can access and process request parameters, headers, body content, and file uploads.
  
• You can define and return custom success or error responses with messages and HTTP status codes.
• Files sent in the request can be handled as binary inputs.
• This is ideal for use cases that require input validation, dynamic processing, or data manipulation.
  

Circuit Resource

• The API triggers a predefined Qntrl Circuit.
• The circuit receives the request parameters as input data, but cannot manipulate the request or perform validations.
• File handling is not supported.
• Response customization (e.g., HTTP status codes, custom messages) is not available.

Configure Request Components     

• Request Params: Define the parameters to be passed as query or path values.
• Param Name: Name of the input parameter.
• Type: Select the data type (e.g., String, Number).
• Allowed Regex: Set restrictions for the parameter values.
• Min Length: Define the minimum length of the input.
• Max Length: Define the maximum length of the input.
• Default Value: Fallback value if input is not provided.
• Mandatory: Specify whether the parameter is mandatory. If a mandatory parameter is missing, an error will occur.

      

• Request Headers: Define custom headers for additional validation:
• Configuration options are the same as request parameters.

• Request Body: Choose the body format that best suits your API:
• None: No request body.
• Raw: Free-form data (e.g., JSON, XML).
• Supports only Min/Max length and Mandatory validation.
• x-www-form-urlencoded: Key-value body format (like parameters inside the body).
• File: Allows binary file uploads (supported only when the resource type is Function.)

• Select Policy: Control the number of allowed requests using a rate-limiting policy.
• Select the rate limit policy: Choose an existing policy or click Add New Policy.
• To add a new policy:
• Policy Name: Label for the policy.
• Request Allowed: Max number of requests allowed.
• Minutes: Time window for rate limit (e.g., 100 per 1 minute).
• Per IP:
• Checked: Limit applies per IP address.
• Unchecked: Limit applies globally.
• Error Code: Code returned when the limit is exceeded.
• Message: Define the error message to be sent to the user if the defined limit is reached.
• Click Save. A new policy will be created.

Save and Publish     

• Click Save to create the endpoint.
• It will appear on the left side under Resources, where you can edit or delete it anytime.
• The endpoint is now ready to receive API requests and run the linked function or circuit.

      

• If any validation fails for request params, headers, or body, Qntrl will reject the request.

• Warnings and errors can be handled and returned only when using Function as the resource.

• Circuits provide only basic automation triggers without detailed input/output control.