API Reference

Base URL: https://afferens.com

Authentication

Every request requires your API key in the X-API-KEY header. Get your key from the dashboard.

X-API-KEY: AFF-77-YOURNAME

Endpoints

GET/api/perception

Returns structured sensory perception data. Each call consumes Sense Tokens based on the modality.

Query Parameters

modality

string

VISION · SPATIAL · ACOUSTIC · ENVIRONMENTAL · MOLECULAR · INTEROCEPTION. Omit for all.

limit

integer

Number of events to return. Max 10. Default 1.

Sense Token Cost per Call

VISION14

SPATIAL10

ACOUSTIC8

ENVIRONMENTAL6

MOLECULAR18

INTEROCEPTION5

Response

{
  "status": 200,
  "data": [{
    "timestamp": "2026-04-14T12:00:00.000Z",
    "entity_id": "ENT-0x1A3F",
    "type": "VISION",
    "modality": "VISION",
    "classification": "vessel",
    "confidence": 0.9124,
    "spatial_coords": { "x": 26.07, "y": -90.72, "z": 58.31 },
    "sense_tokens_consumed": 14
  }],
  "count": 1,
  "api_version": "v1.0.0"
}

POST/api/actuation

Send a command to a physical node. Costs 5 Sense Tokens per command.

Body

target_node_id

string

ID of the node to command (e.g. IPHONE-IOS-01).

command_type

string

CAPTURE_FRAME · TRIGGER_ALARM · MOVE_TO · ROTATE_CAMERA · LOCK · UNLOCK · ADJUST_SENSOR · SHUTDOWN_NODE

parameters

object

Optional command-specific parameters.

curl https://afferens.com/api/actuation \
  -X POST \
  -H "X-API-KEY: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_node_id":"IPHONE-IOS-01","command_type":"CAPTURE_FRAME"}'

Code Examples

curl

curl https://afferens.com/api/perception \
  -H "X-API-KEY: YOUR_KEY" \
  -G \
  -d "modality=vision" \
  -d "limit=1"

python

import requests

response = requests.get(
    "https://afferens.com/api/perception",
    headers={"X-API-KEY": "YOUR_KEY"},
    params={"modality": "vision", "limit": 1}
)

data = response.json()
print(data)

Error Codes

401Missing or invalid API key

403API key is inactive

404No data found for the requested modality