Proxy Agents — SpiderIQ

POST/api/v1/proxy/agents/heartbeat

Agent heartbeat

Submit agent heartbeat with modem statuses.

Should be called every 30 seconds.

The response includes:

Pending commands to execute
Config updates (if any)

Headers required:

X-Location-Code: Location code (e.g., 'ua-odessa-1')
X-Agent-Key: Agent API key

Parameters

Name	In	Type	Required	Description
`x-location-code`	header	string	true	Location code
`x-agent-key`	header	string	true	Agent API key

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/agents/heartbeat' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "location_code": "string",
  "agent_version": "string",
  "uptime_seconds": 0,
  "modems": [
    {
      "imei": "string",
      "public_ip": "string",
      "signal_strength": 0,
      "status": "online",
      "is_healthy": true,
      "error_message": "string",
      "requests_since_last_heartbeat": 0,
      "bytes_since_last_heartbeat": 0,
      "speed_test": {}
    }
  ],
  "system_stats": {}
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/proxy/agents/heartbeat",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"location_code": "string", "agent_version": "string", "uptime_seconds": 0, "modems": [{"imei": "string", "public_ip": "string", "signal_strength": 0, "status": "online", "is_healthy": true, "error_message": "string", "requests_since_last_heartbeat": 0, "bytes_since_last_heartbeat": 0, "speed_test": {}}], "system_stats": {}},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/agents/heartbeat", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"location_code": "string", "agent_version": "string", "uptime_seconds": 0, "modems": [{"imei": "string", "public_ip": "string", "signal_strength": 0, "status": "online", "is_healthy": true, "error_message": "string", "requests_since_last_heartbeat": 0, "bytes_since_last_heartbeat": 0, "speed_test": {}}], "system_stats": {}})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"location_code": "string", "agent_version": "string", "uptime_seconds": 0, "modems": [{"imei": "string", "public_ip": "string", "signal_strength": 0, "status": "online", "is_healthy": true, "error_message": "string", "requests_since_last_heartbeat": 0, "bytes_since_last_heartbeat": 0, "speed_test": {}}], "system_stats": {}}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/proxy/agents/heartbeat", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/proxy/agents/commands/{command_id}/complete

Complete a command

Report command completion.

Call this after executing a command received in the heartbeat response.

Headers required:

X-Location-Code: Location code
X-Agent-Key: Agent API key

Parameters

Name	In	Type	Required	Description
`command_id`	path	string	true
`x-location-code`	header	string	true	Location code
`x-agent-key`	header	string	true	Agent API key

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/agents/commands/{command_id}/complete' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "success": true,
  "result": {},
  "error_message": "string",
  "duration_seconds": 0.0
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/proxy/agents/commands/{command_id}/complete",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"success": true, "result": {}, "error_message": "string", "duration_seconds": 0.0},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/agents/commands/{command_id}/complete", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"success": true, "result": {}, "error_message": "string", "duration_seconds": 0.0})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"success": true, "result": {}, "error_message": "string", "duration_seconds": 0.0}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/proxy/agents/commands/{command_id}/complete", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/proxy/agents/modems/register

Register a new modem

Register a new modem discovered by the agent.

Called when a new USB modem is detected.

Headers required:

X-Location-Code: Location code
X-Agent-Key: Agent API key

Parameters

Name	In	Type	Required	Description
`imei`	query	string	true
`proxy_port`	query	integer	true
`iccid`	query	any	false
`phone_number`	query	any	false
`carrier`	query	any	false
`usb_port`	query	any	false
`x-location-code`	header	string	true	Location code
`x-agent-key`	header	string	true	Agent API key

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/agents/modems/register' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/proxy/agents/modems/register",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/agents/modems/register", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/proxy/agents/modems/register", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/proxy/agents/sms/log

Log an SMS message

Log an incoming or outgoing SMS message.

Headers required:

X-Location-Code: Location code
X-Agent-Key: Agent API key

Parameters

Name	In	Type	Required	Description
`modem_id`	query	string	true
`direction`	query	string	true
`message`	query	string	true
`phone_number`	query	any	false
`sms_id_on_device`	query	any	false
`x-location-code`	header	string	true	Location code
`x-agent-key`	header	string	true	Agent API key

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/agents/sms/log' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/proxy/agents/sms/log",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/agents/sms/log", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/proxy/agents/sms/log", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error