Public API: I/O Ports | Arcules Knowledge Base

Overview

The I/O Ports API provides access to manage and monitor the state of input/output ports on connected devices. This API allows developers to query the current state of multiple I/O ports and update their state if needed. It is useful in scenarios such as managing the operational status of connected devices or sensors in a video surveillance or monitoring system.

Key Use Cases:

Querying the status of multiple I/O ports in real-time.
Changing the state of a specific I/O port to trigger actions on connected devices.

Prerequisites:

Devices related to the API features covered in this article, including I/O network relays, must first be registered with an Arcules gateway appliance. These devices should also be online and have an active internet connection.
Gateway appliance(s) should be online and have an active internet connection.
Users must have the following roles assigned in the Arcules web portal:
- API User Role: To be able to use both I/O and Audio functionalities through our API.
- I/O Relay Operator Role: To be able to use the I/O functionalities of our API.

API Endpoint

Endpoint 1: Query I/O Ports Status

HTTP Method: GET

URL: https://msapi.arcules.com/v1/ioports?portIds={portId1},{portId2}

Authentication: OAuth 2.0 Bearer Token

Request Parameters

Parameter	Type	Description	Required
portIds	string	A comma-separated list of unique port IDs to query the state for.	Yes

Sample Request

GET /v1/ioports?portIds=72af2eb5-e0c6-44b7-a122-e34b89e8880b,2945cd45-3197-4b5c-a01f-7c6ae2cd132b
Host: msapi.arcules.com
Authorization: Bearer {token}

Sample Response

{
  "2945cd45-3197-4b5c-a01f-7c6ae2cd132b": {
    "state": "low",
    "lastUpdated": 1726183188281
  },
  "72af2eb5-e0c6-44b7-a122-e34b89e8880b": {
    "state": "low",
    "lastUpdated": 1726183188281
  }
}

Endpoint 2: Update I/O Port State

HTTP Method: PATCH

URL: https://msapi.arcules.com/v1/ioport/{portId}

Authentication: OAuth 2.0 Bearer Token

Request Parameters

Parameter	Type	Description	Required
portId	string	The unique ID of the I/O port to be updated.	Yes

Sample Request

PATCH /v1/ioport/ad545e36-1179-4013-a901-af5550e6e113
Host: msapi.arcules.com
Authorization: Bearer {token}
Content-Length: 20
{
  "state": "pulse",
  "duration": 500
}

Sample Response

204 No Content

Error Handling

Error Code	Message	Description
200	OK	The request was successful.
204	No Content	The request was successful but there is no content to send for this request.
400	Bad Request	The request was invalid or cannot be processed.
401	Unauthorized	Missing or invalid JWT.
403	Forbidden	API users lack the necessary permissions.
404	Not Found	The requested resource could not be found.
429	Too Many Requests	API rate limit has been exceeded.
5xx	Server Error	The server encountered an issue processing the request.

Additional Resources

FAQ

Q: How do I authenticate?

A: Use your OAuth 2.0 Bearer Token in the request header. See the Authentication Guide for more details.

Q: How can I obtain the portId value?

A: You can retrieve the portId values from the response of the /v1/devices endpoint.

Q: Can I retrieve historical states of an I/O port?

A: No, the I/O Ports API only provides the current state of the port. For historical data, you'll need to implement your own logging mechanism or use additional services.

Q: How frequently are port states updated?

A: Port states are updated in real-time, but lastUpdated indicates the timestamp (in milliseconds since the epoch) of the most recent update.

Q: What states can I set for the I/O ports?

A: You can set the following states for the I/O ports:

high: The output port is set to an active state.
low: The output port is set to an inactive state.
pulse: A temporary pulse is applied to the port. When using this state, you must also specify the duration in seconds, which determines how long the pulse should last.

Q: How do I know if the state change was successful?

A: For a successful state change, the API will return a 204 No Content response, indicating the state was updated without errors. If there was an issue, you'll receive an error code with additional details.

Q: What happens if I don't include a duration with the pulse state?

A: If you set the state to pulse without specifying a duration, the request will fail, and you will receive a 400 Bad Request response indicating that the duration parameter is missing.

Q: Can I revert the state of an I/O port after sending a pulse?

A: The pulse state automatically reverts to the previous state after the specified duration has passed. No additional action is needed to reset it.