Skip to main content
All CollectionsIntegration
Public API: I/O Ports
Public API: I/O Ports
Updated over 2 months ago

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

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

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.

Did this answer your question?