Remote API
This article provides an overview of the Remote API's capabilities, offering insights into how it can be utilized to manage and automate your integration workflows. For detailed information on specific functions and parameter configurations and to explore the full potential of the API, please refer to the comprehensive Remote API documentation. Instructions for accessing the documentation are provided below.
Understanding Remote API
The Remote API is a powerful tool that allows you to access and manage key functionalities remotely through a structured web interface or programmatically. Beyond just using the platform interface, you can, for example, initiate tasks and manage workflows by making API calls from other applications capable of interacting with APIs. This means you can integrate the Remote API with external tools, automation systems, or custom applications, enabling seamless interaction and automation across different environments.
Whether you’re monitoring orchestrators, retrieving agent data, or executing tasks, the Remote API gives you the flexibility to do so from within the platform or via external systems, helping you streamline and optimize your integration processes.
Authorization
Generating the API key, commonly referred to as a token, is crucial for authorizing interactions with the remote API. This token is essential for making API calls and is included in the Authorization parameter to ensure secure access. Here’s how you can manage and use the API token:
Begin by accessing the Company Detail section. Select the Token in the Allow control option to generate a Remote control token automatically. Use this token as your Authorization API key. This process ensures you have the necessary credentials to interact with the Remote API effectively and safely.
Integray Remote API documentation
To access the Remote API documentation, navigate to the Home page of the Integray platform. Locate your company and click the pencil icon next to the company name to open the Company Details. In the Remote Control section, click the Open Remote API documentation button.
Clicking on this button will grant you access to the comprehensive Remote API documentation, where you can explore detailed information on managing and utilizing the API for your integration needs.
The documentation is divided into two sections. The Endpoints section provides a detailed look at the various API endpoints, illustrating how to perform actions and retrieve data effectively. Following this, the Schemas section delves into the data structures that define and govern the exchange of information between your applications and the Remote API.
Endpoints
In the Integray Remote API, endpoints are divided into several main groups based on functionality. Each endpoint group shares a consistent structure, including a description, defined HTTP method, request parameters, and structured responses detailing expected outcomes. The main groups are:
Agent
Get agents: This endpoint returns a list of the company's agents, including both active and inactive ones. It provides comprehensive information about each agent, facilitating efficient management and monitoring of agent activities.
Orchestrator
Set status: Updates the status of the orchestrator, enabling you to control your operational state.
Get status: Retrieves the orchestrator's current status, providing insights into its operational state. It allows you to monitor the orchestrator's status.
Task
Get tasks: This endpoint retrieves a list of tasks within the company, allowing you to view and manage various tasks.
Start task: Initiates the execution of a task that requires on-demand processing. This endpoint triggers the execution of the specified task, facilitating real-time task processing.
Kill: Terminates the execution of running task runs associated with a specific task. This endpoint allows you to stop task runs in progress.
Clean: Removes scheduled task runs from the processing queue that haven't been picked up by the orchestrator yet.
Set runnability: Modifies a task's runnability status, enabling you to control whether the task is eligible for execution.
Task run
Get logs: Retrieves logs generated during the execution of a specific task run, providing insights into the execution process. You can filter logs by minimum log level to focus on relevant information.
Restart: Restarts a task run as scheduled, initiating a new execution cycle for the specified task run. It is useful for re-triggering task runs.
Restart as Parked: Restarts a task run as scheduled, initiating a new execution cycle for the specified task run. The newly created task run is in the parked state.
Get Level: Retrieves the restart level of a task run, indicating the number of times the task run has been restarted.
Get task run: Retrieves detailed information about a specific task run, including its status, execution history, and associated metadata. It facilitates comprehensive monitoring and analysis of task executions.
Get task runs: Retrieves a list of task runs based on various criteria, such as task, status, date range, and count. It supports flexible filtering to facilitate the targeted retrieval of task execution data.
Get task run statuses: Retrieves a list of possible task run statuses, providing insight into the states a task run can transition through during its lifecycle.
Schemas
The Schemas section within the Integray Remote API documentation is an essential reference for understanding the data structure used across various API calls. Each schema defines the data models, outlining the properties, types, and constraints that govern how data is exchanged between the API and client applications.
Each schema is structured to ensure consistency and predictability when sending or receiving data via the API. Understanding these data models helps you accurately format your requests and correctly parse the API responses. By leveraging these schemas, you can integrate the Remote API more effectively into your systems, ensuring that data is properly structured and handled.
Example
Retrieving the current status of the Orchestrator
To view the current status of an orchestrator, navigate to the GET status endpoint under the Orchestrator category. You must input the required parameter CompanySlug to specify which company's orchestrator you are querying and include the Authorization token for authentication. The request can be sent by clicking the Send API Request button.
The current status will be displayed under the Responses section.
Updating the status of the Orchestrator
To modify the orchestrator's state, use the Set status endpoint within the same Orchestrator category. You need to provide the CompanySlug and Authorization token and also specify the desired state by setting the isRunnable attribute in the request body to either true (to activate) or false (to deactivate). The request can be executed by clicking the Send API Request button.
You will see the success status in the response area if the request is successful.
