API Reference

Download .txt

Base URL: https://afferens.com

MCP Server

Afferens runs as a standard stdio MCP server, so any MCP client can use it. Each client registers servers its own way — configs for the common ones below. Swap in your API key; everything else is exact. The free afferens_demo tool needs no key.

Claude Code
claude mcp add afferens -e AFFERENS_API_KEY=YOUR_KEY -- npx -y @afferens/mcp-server
Codex — ~/.codex/config.toml
[mcp_servers.afferens]
command = "npx"
args = ["-y", "@afferens/mcp-server"]
[mcp_servers.afferens.env]
AFFERENS_API_KEY = "YOUR_KEY"
OpenClaw
openclaw mcp set afferens '{"command":"npx","args":["-y","@afferens/mcp-server"],"env":{"AFFERENS_API_KEY":"YOUR_KEY"}}'
Cursor · Windsurf · Cline · Claude Desktop
{
  "mcpServers": {
    "afferens": {
      "command": "npx",
      "args": ["-y", "@afferens/mcp-server"],
      "env": { "AFFERENS_API_KEY": "YOUR_KEY" }
    }
  }
}

Config file — Cursor ~/.cursor/mcp.json · Windsurf ~/.codeium/windsurf/mcp_config.json · Cline and Claude Desktop via their MCP settings.

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_live_0123456789abcdef0123456789abcdef

Endpoints

GET/api/perception

Returns verified, structured perception. Each reading carries a polish-derived confidence and a verified flag — confirmed across multiple frames (frames), never a single-frame guess. An empty result is the honest "no live sensor" state, never fabricated. Each call consumes Sense Tokens based on the modality. Timestamps auto-localize to your account's timezone (set automatically the first time you connect a node) — pass ?tz= only to override.

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": "cup",
    "confidence": 0.9,
    "verified": true,
    "frames": 5,
    "bbox": [0.41, 0.62, 0.12, 0.18],
    "spatial_coords": { "x": 0.47, "y": 0.71 },
    "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 · optional
Defaults to your most recently active node — omit it and Afferens targets your node automatically. Pass to command a specific node.
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 '{"command_type":"CAPTURE_FRAME"}'

Code Examples

curl · Windows PowerShell: use curl.exe (plain curl is an Invoke-WebRequest alias)
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