API Interface

Beyond the Web UI and Command-Line Interface (CLI), the ConHive Agent provides a powerful RESTful API. This interface allows developers to programmatically access agent functionalities, manage modules, retrieve data, and integrate the agent into custom applications, automation workflows, or third-party orchestration tools.

Prerequisites

Before using the API, ensure the following conditions are met:

1. Agent Running: The ConHive Agent must be installed and actively running on the target device.
2. Network Accessibility: Your client machine must have network connectivity to the agent’s host and the configured HTTP port (default: 5050). Check firewalls if necessary.
3. Valid Credentials: You need the username and password for a valid agent user account.
   • Note: Default credentials might be specified during initial setup or located within the agent’s configuration files (consult the Configuration guide if unsure).

Base URL Structure

All API requests should target the agent’s base URL, which follows this pattern:

http://<AGENT_HOST>:<PORT>/api/v1/

• Replace <AGENT_HOST> with the IP address or resolvable hostname of the device running the agent.
• Replace <PORT> with the agent’s configured HTTP listener port (typically 5050 by default).
• When making requests from the same machine as the agent, you can usually use localhost for <AGENT_HOST>.

Authentication: Obtaining and Using Bearer Tokens

Most API endpoints are protected and require authentication using a JSON Web Token (JWT), commonly referred to as a Bearer Token. You must first obtain this token by authenticating with your user credentials.

Step 1: Request an Authentication Token

To get a token, send an HTTP POST request to the /agentusers/loginusertoagent endpoint, providing your username and password in the JSON request body.

# Example using curl to authenticate and receive a token
curl -X POST \
  'http://localhost:5050/api/v1/agentusers/loginusertoagent' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "your_agent_username",
    "password": "your_agent_password"
  }'

Expected Successful Response:

The server will respond with a JSON object containing the token and user details upon successful authentication.

{
  "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3...", // This is your JWT Bearer Token
  "user": {
    "id": "usr-...",
    "username": "your_agent_username"
    // ... other user details
  }
}

Tip: Extracting the Token with jq If you have the jq command-line JSON processor installed, you can easily extract just the token value:

# Ensure jq is installed (e.g., sudo apt install jq / brew install jq)
TOKEN=$(curl -s -X POST \
  'http://localhost:5050/api/v1/agentusers/loginusertoagent' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"username": "your_agent_username", "password": "your_agent_password"}' \
  | jq -r '.token')

# Verify the token variable (optional)
echo $TOKEN

The -s flag in curl silences progress output, and -r in jq outputs the raw string without quotes.

Step 2: Use the Token in Subsequent Requests

For every request to a protected API endpoint, you must include the obtained JWT in the Authorization HTTP header, prefixed with Bearer .

Header Format:

Authorization: Bearer <YOUR_JWT_TOKEN>

Replace <YOUR_JWT_TOKEN> with the actual token string you received in Step 1.

Making API Requests: Examples

Here are practical examples using curl to interact with the API. These assume you have obtained a token and stored it in a variable named TOKEN (as shown in the jq tip above).

Example 1: Get Device Status

Retrieve current status information from the device status module.

# Assuming TOKEN variable holds your Bearer Token
curl -X GET \
  'http://localhost:5050/api/v1/devicestatus/get' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}"

Example 2: Start an Audio Recording

Initiate an audio recording session via the audio files module.

# Assuming TOKEN variable holds your Bearer Token
curl -X POST \
  'http://localhost:5050/api/v1/audiofiles/audiorecordstart' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "duration": 5,              # Duration of the recording in seconds
    "fileExtension": "flac"     # Desired audio file format (e.g., flac, wav, mp3)
  }'

Example 3: Check Audio Recording Status

Query the status of an ongoing or recently completed audio recording.

# Assuming TOKEN variable holds your Bearer Token
curl -X GET \
  'http://localhost:5050/api/v1/audiofiles/audiorecordstatus' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${TOKEN}"

Interactive API Exploration (Swagger UI)

The most convenient way to explore the full API surface, view detailed request/response models, and test endpoints interactively is through the built-in Swagger UI documentation.

Access it via your browser at: http://<AGENT_HOST>:<PORT>/docs

(Example using localhost: http://localhost:5050/docs)