API Reference

Download .txt

Base URL: https://afferens.com

MCP Server

Connect Afferens to any MCP-compatible AI assistant — Claude, Cursor, Windsurf — in under a minute. No setup beyond adding your key. Free demo tool requires no key at all.

Claude Code
claude mcp add afferens -e AFFERENS_API_KEY=YOUR_KEY -- npx -y @afferens/mcp-server
Claude Desktop · Cursor · Windsurf
{
  "mcpServers": {
    "afferens": {
      "command": "npx",
      "args": ["-y", "@afferens/mcp-server"],
      "env": { "AFFERENS_API_KEY": "YOUR_KEY" }
    }
  }
}
Available Tools
afferens_demo
none
Live perception data across all 6 modalities. No key needed.
afferens_perceive
API key
Query live events by modality (VISION · SPATIAL · ACOUSTIC · ENVIRONMENTAL · MOLECULAR · INTEROCEPTION) with limit filtering.

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. Send X-Client-Timezone to get local display fields alongside UTC.

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-05-11T05:55:00.112250+00:00",
    "timestamp_utc": "2026-05-11T05:55:00.112250+00:00",
    "timestamp_local": "May 11, 2026, 1:55:00 PM",
    "timestamp_timezone": "Asia/Kuala_Lumpur",
    "ingested_at": "2026-05-11T05:55:00.112250+00:00",
    "ingested_at_utc": "2026-05-11T05:55:00.112250+00:00",
    "ingested_at_local": "May 11, 2026, 1:55:00 PM",
    "ingested_at_timezone": "Asia/Kuala_Lumpur",
    "entity_id": "LIVE-VIS-MP0SH76G",
    "type": "VISION",
    "modality": "VISION",
    "classification": "iphone_camera_coco",
    "confidence": 1,
    "spatial_coords": { "model": "coco-ssd", "object_count": 1 },
    "source_node_id": "IPHONE-IOS-01",
    "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