# Afferens API — LLM Reference

Afferens is the Universal Sensory Layer (USL) for AI agents. It provides structured, real-world physical perception data via a REST API. AI agents use Afferens to receive grounded sensor context — reducing hallucination and enabling real-world decision making.

Base URL: https://afferens.com
Auth: X-API-KEY header on every request
Free tier: 10,000 Sense Tokens on signup, no card required

---

## MCP Server

Connect Afferens to any MCP-compatible AI assistant (Claude, Cursor, Windsurf) in under a minute.

### Claude Code
```
claude mcp add afferens -e AFFERENS_API_KEY=YOUR_KEY -- npx -y @afferens/mcp-server
```

### Claude Desktop · Cursor · Windsurf
```json
{
  "mcpServers": {
    "afferens": {
      "command": "npx",
      "args": ["-y", "@afferens/mcp-server"],
      "env": { "AFFERENS_API_KEY": "YOUR_KEY" }
    }
  }
}
```

### Available Tools
- afferens_demo — Live perception data across all 6 modalities. No key needed.
- afferens_perceive — Query live events by modality with limit filtering. Requires API key.
- afferens_ingest — Push sensor data from a node into the network. Requires API key.
- afferens_actuate — Send commands to physical nodes. Requires API key.

---

## Authentication

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

X-API-KEY: AFF-77-YOURNAME

---

## Endpoints

### GET /api/perception
Returns structured sensory perception data. Each call consumes Sense Tokens based on modality.
Send X-Client-Timezone to get local display fields alongside UTC.

Query parameters:
- modality (string, optional): VISION | SPATIAL | ACOUSTIC | ENVIRONMENTAL | MOLECULAR | INTEROCEPTION — omit for all
- limit (integer, optional): number of events to return, max 10, default 1

Sense Token cost per call:
| Modality      | Tokens |
|---------------|--------|
| VISION        | 14     |
| SPATIAL       | 10     |
| ACOUSTIC      | 8      |
| ENVIRONMENTAL | 6      |
| MOLECULAR     | 18     |
| INTEROCEPTION | 5      |

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, required): ID of the node to command (e.g. IPHONE-IOS-01)
- command_type (string, required): 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"}'
```

### GET /api/demo
Public demo endpoint. No API key required. Returns live canned sensory data.

Query parameters:
- modality (string, optional): same values as /api/perception

### POST /api/ingest
Push live sensor data from a node into the Afferens network.

Body:
- modality (string, required): VISION | SPATIAL | ACOUSTIC | ENVIRONMENTAL | MOLECULAR | INTEROCEPTION
- data (object, required): sensor payload
- classification (string, optional): label for this reading

### GET /api/commands
Nodes poll this to receive pending commands.

Query parameters:
- node_id (string, required): the node's ID

---

## Code Example

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

---

## Error Codes

| Code | Meaning                              |
|------|--------------------------------------|
| 401  | Missing or invalid API key           |
| 402  | Free tier token limit reached        |
| 403  | API key inactive                     |
| 404  | No data found for requested modality |
| 429  | Rate limit exceeded                  |

---

Sign up: https://afferens.com/signup
Pricing: https://afferens.com/pricing
Docs: https://afferens.com/docs