awaBerry API Documentation -> awaBerry AGENTIC API Documentation

APIRequests API Documentation

API Summary

The API provides secure access to awaBerry Agentic - to automate calls to your connected devices with awaBerry. It is necessary to setup at least one project in the awaBerry web application in the section "Agentic". The API allows clients to authenticate using a project key and secret, initialize sessions, connect to devices, execute commands, and retrieve results. All endpoints use JSON for requests and responses, and require proper authentication for access.

  • Authentication via projectkey and projectsecret
  • Session management with tokens
  • Device connection and status checks
  • Command execution and result retrieval
  • All requests use Content-Type: application/json
  • Base URL: https://agentic.awaberry.net/apirequests

Base URL: https://agentic.awaberry.net/apirequests

API Methods Overview

Method Name Description
/getProject Retrieve project details using project key and secret.
/initSession Initialize a new API session and get a session token.
/startDeviceConnection Start a connection to a device with a session token.
/getDeviceConnectionStatus Check if a device is connected for a session.
/disconnectDeviceConnection Disconnect a device session.
/getLastCommandCalled Retrieve the last command that was called on a device.
/executeCommand Execute a command on a connected device.
/getAdditionalCommandResults Get more results for a long-running command.
/startDeviceConnectionWebsocket Start a websocket connection to a device with a session token.
/getWebSocket Get a websocket for advanced device communication.

Test the API

Go to API Test Page

Test the websocket

Go to API Test Page

/getProject

Description: Retrieves project details including project ID, name, description, creation and update dates, and the decrypted agent project setup. Requires a valid projectkey and the cleartext projectsecret. If the credentials are invalid or the project does not exist, an error is returned.

Request: 
{
  "projectkey": "string",
  "projectsecret": "string"
}
Response: 
{
  "projectid": "string",
  "projectname": "string",
  "projectdescription": "string",
  "datecreated": "string",
  "dateupdated": "string",
  "agentprojectsetup": "[{\"deviceuuid\": \"string\", \"mayBeRoot\": true/false}, ...]"
}

Note: agentprojectsetup is a JSON string array and should be parsed before use.

/initSession

Description: Initializes a new API session and returns a session token. Requires projectkey and cleartext projectsecret. Validates credentials, decrypts project and API setup, and creates a session token. The session token is used for subsequent device and command operations.

Request: 
{
  "projectkey": "string",
  "projectsecret": "string"
}
Response: 
{
  "sessionToken": "string"
}

Note: The property is sessionToken (not token).

/startDeviceConnection

Description: Initiates a connection to a device identified by deviceuuid using a valid sessionToken. Checks if the device is already connected; if not, starts the connection process. Returns true if the device is connected, otherwise false.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string"
}
Response: 
true | false

/getDeviceConnectionStatus

Description: Checks the connection status of a device for a given sessionToken and deviceuuid. Returns true if the device is connected, otherwise false.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string"
}
Response: 
true | false

/disconnectDeviceConnection

Description: Disconnects a device session for the specified sessionToken and deviceuuid. If the session or device entry does not exist, returns false. On successful disconnect, returns true.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string"
}
Response: 
{
  "disconnected": true | false
}

/getLastCommandCalled

Description: Retrieves the last command that was executed on a device for a given session. Requires sessionToken and deviceuuid. Returns the command string that was last called on the specified device.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string"
}
Response: 
{
  "lastCommand": "string"
}

/executeCommand

Description: Executes a command on a connected device using the provided sessionToken, deviceuuid, and command. Returns the result and whether the command ended on the terminal. If the command is still running, endedOnTerminal will be false.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string",
  "command": "string"
}
Response: 
{
  "lastCommandEndedOnTerminal": "...",
  "lastCommandEndedOnTerminal": true | false
}

/getAdditionalCommandResults

Description: Retrieves additional results for a long-running command that has not yet ended on the terminal. Requires sessionToken and deviceuuid. Returns the latest result and whether the command has finished.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string"
}
Response: 
{
  "lastCommandEndedOnTerminal": "...",
  "lastCommandEndedOnTerminal": true | false
}

/startDeviceConnectionWebsocket

Description: Initiates a websocket connection to a device identified by deviceuuid using a valid sessionToken. Returns true if the device is connected, otherwise false.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string"
}
Response: 
true | false

/getWebSocket

Description: Returns a websocket for advanced device communication. Requires a valid session token and deviceuuid.

Request: 
{
  "sessionToken": "string",
  "deviceuuid": "string"
}
Response: 
WebSocket connection

Notes & Requirements

  • Demo credentials: demokey and demosecret are accepted for demo access.
  • Demo device: demodevice is available for demo sessions.
  • UUID format is required for projectkey, projectsecret, and deviceuuid (except demo values).
  • All requests and responses use JSON format.
  • Error responses use HTTP status codes and descriptive messages.

Up to User Manual Main Page