> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ardenstats.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocol

# Agent Telemetry Protocol

Technical specification for the Arden telemetry event format.

## Protocol Overview

Arden uses a minimal, language-agnostic JSON protocol for logging AI agent telemetry events. It follows syslog semantics with no server-side deduplication.

## Event Schema

### Required Fields

| Field   | Type          | Format                           | Description                             |
| ------- | ------------- | -------------------------------- | --------------------------------------- |
| `agent` | string        | `^(?:[aAsS]-)?[0-9a-fA-F]{1,8}$` | Agent identifier (case-insensitive hex) |
| `bid`   | integer       | Micro-cents                      | Usage cost (6 decimal places implicit)  |
| `time`  | integer       | Epoch milliseconds UTC           | Event timestamp                         |
| `data`  | object/string | ≤1KB                             | Metadata payload or base64 string       |

### Optional Fields

| Field  | Type    | Format          | Description                              |
| ------ | ------- | --------------- | ---------------------------------------- |
| `user` | string  | ULID (26 chars) | User identifier (auto-filled from token) |
| `mult` | integer | -               | Reserved multiplier for future pricing   |

### Server-Generated Fields

| Field      | Type   | Description               |
| ---------- | ------ | ------------------------- |
| `event_id` | string | UUID-7 assigned by server |

## Agent ID Format

Agent IDs support optional prefixes:

* `A-` or `a-` = Real agent
* `S-` or `s-` = Simulated agent
* No prefix = Bare hex string accepted

Examples:

* `A-1234abcd` (real agent)
* `s-5678ef90` (simulated agent)
* `deadbeef` (bare hex)

## Data Payload

The `data` field accepts two formats:

### 1. Object Format (Recommended)

```json
{
  "data": {
    "task": "code_review",
    "duration": 1500,
    "tokens": 2048
  }
}
```

**Constraints:**

* Flat key-value pairs only
* Total JSON size ≤ 1KB
* Values must be strings or integers

### 2. Base64 Format

```json
{
  "data": "SGVsbG8gV29ybGQ="
}
```

**Constraints:**

* Base64-encoded string
* Decoded size ≤ 1KB
* For arbitrary binary data

## Complete Event Example

```json
{
  "agent": "A-1234abcd",
  "user": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "time": 1642781234567,
  "bid": 1000,
  "mult": 1,
  "data": {
    "task": "code_review",
    "duration": 1500,
    "language": "python",
    "lines_changed": 42
  }
}
```

## Validation Rules

### Agent Validation

* Must exist in the system database
* Case-insensitive matching
* Hex characters only (0-9, A-F, a-f)
* Length: 1-8 characters (excluding prefix)

### User Validation

* Must be valid ULID format (26 characters)
* Auto-filled from Bearer token if missing
* Required if no valid token provided

### Time Validation

* Must be valid epoch milliseconds
* UTC timezone assumed
* Future timestamps accepted

### Bid Validation

* Non-negative integer
* Represents micro-cents (1000 = \$0.01)
* Default: 0 if not specified

### Data Validation

* Total size limit: 1KB
* Object format: flat key-value pairs only
* String format: valid base64 encoding

## Error Responses

### Validation Errors

```json
{
  "status": "rejected",
  "accepted_count": 0,
  "rejected_count": 1,
  "rejected": [
    {"index": 0, "error": "unknown_agent"}
  ]
}
```

### Common Error Codes

* `unknown_agent` - Agent not registered
* `invalid_user` - User ULID invalid/missing
* `missing_required_field` - Required field absent
* `bad_data_size` - Data exceeds 1KB limit
* `validation_error` - Schema validation failed

## Batch Processing

Send up to 100 events in a single request:

```json
[
  {
    "agent": "A-1234abcd",
    "bid": 1000,
    "time": 1642781234567,
    "data": {"task": "review"}
  },
  {
    "agent": "A-1234abcd", 
    "bid": 1500,
    "time": 1642781234890,
    "data": {"task": "debug"}
  }
]
```

**Batch Rules:**

* Maximum 100 events per request
* Each event validated independently
* Partial success returns 207 status
* Event IDs returned in order (accepted events only)

## Security Requirements

* **Transport**: HTTPS required (TLS 1.3)
* **Authentication**: Optional Bearer token
* **Validation**: Server-side schema validation
* **Rate limiting**: Applied per IP/token

## Protocol Versioning

* Current version: v1
* Endpoint: `/api/events`
* Breaking changes will increment version
* Backward compatibility maintained when possible

## Implementation Notes

### Timestamps

Always use current timestamp when sending events:

```javascript
// JavaScript
const timestamp = Date.now();

// Python
import time
timestamp = int(time.time() * 1000)

// Go
timestamp := time.Now().UnixMilli()
```

### Error Handling

Always check response status and handle errors:

```javascript
const response = await fetch('/api/events', {
  method: 'POST',
  body: JSON.stringify(event)
});

if (!response.ok) {
  const error = await response.json();
  console.error('Event submission failed:', error);
}
```

### Deduplication

The protocol intentionally does **not** perform deduplication. Each event is treated as unique, even if identical to previous events.

## Testing

Use the CLI to validate event format:

```bash
# Validate single event
arden events send --agent "test" --bid 1000 --dry-run --print

# Validate batch events
arden events send --file events.json --dry-run --print
```

## Migration from Legacy Formats

If migrating from other telemetry systems, ensure:

* Agent IDs match the hex format requirement
* Timestamps are in epoch milliseconds
* Data payloads are flattened to key-value pairs
* File sizes are under 1KB per event