# Variables API

Variables API là một cửa hàng key-value nhanh cho trạng thái tạm thời. Khác với
bộ nhớ (được đánh chỉ mục, có thể tìm kiếm và có cấu trúc), biến được tối ưu
cho truy cập đọc/ghi nhanh — hoàn hảo cho bộ đếm, cờ và trạng thái phiên.

## Các endpoint

### POST /var

Đặt hoặc cập nhật một biến.

```bash
curl -X POST https://synapse.schaefer.zone/var \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "last_session_at", "value": "2026-06-27T14:00:00Z"}'
```

### GET /var/:key

Lấy một biến đơn lẻ.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var/last_session_at
```

Phản hồi:

```json
{ "key": "last_session_at", "value": "2026-06-27T14:00:00Z", "updated_at": "..." }
```

### GET /var

Liệt kê tất cả biến.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var
```

### DELETE /var/:key

Xóa một biến.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/var/last_session_at
```

## Khi nào dùng Biến so với Bộ nhớ

| Trường hợp | Sử dụng |
|----------|-----|
| Tên người dùng, sở thích | Bộ nhớ (có thể tìm kiếm, có cấu trúc) |
| Timestamp phiên cuối | Biến (trạng thái tạm thời) |
| Bộ đếm (ví dụ tin nhắn đã gửi) | Biến (cập nhật thường xuyên) |
| Trạng thái quy trình ("đã xong bước 3/5") | Biến (tạm thời) |
| Ghi chú dự án dạng dài | Bộ nhớ (đánh chỉ mục toàn văn) |
| Script tái sử dụng | Cửa hàng script (đặt tên, đánh phiên bản) |

## Mẫu phổ biến

### Theo dõi phiên cuối

```bash
# At session end
curl -X POST .../var -d '{"key": "last_session_at", "value": "'$(date -Iseconds)'"}'

# At session start
LAST=$(curl .../var/last_session_at | jq -r .value)
curl .../memory/diff?since=$(date -d "$LAST" +%s)
```

### Mẫu bộ đếm

```bash
# Increment
N=$(curl .../var/api_calls | jq -r .value)
curl -X POST .../var -d "{\"key\": \"api_calls\", \"value\": $((N+1))}"
```

### Cờ tính năng

```bash
curl -X POST .../var -d '{"key": "feature_x_enabled", "value": "true"}'

# Check
ENABLED=$(curl .../var/feature_x_enabled | jq -r .value)
if [ "$ENABLED" = "true" ]; then ... fi
```

## Bước tiếp theo

- [Memory API](/docs/api/memory) — cho dữ liệu có cấu trúc, có thể tìm kiếm
- [Cron & Scheduler](/docs/api/cron)