---
url: https://developers.webzenk.kr/api/storage.md
---
# 데이터 저장

| | 경로 | 인증 | 설명 |
|---|---|---|---|
| GET | `/v1/storage` | 유저 | 내 키 전체 |
| GET | `/v1/storage/{key}` | 유저 | 값 하나 |
| PUT | `/v1/storage/{key}` | 유저 | 저장 |
| POST | `/v1/storage/batch` | 유저 | 여러 키 저장 (최대 20개, 전부 성공 또는 전부 실패) |
| DELETE | `/v1/storage/{key}` | 유저 | 삭제 |
| GET | `/v1/players/{id}/public` | 유저 | 다른 유저의 공개 키 |

키: 1~64자 `[A-Za-z0-9_.-]` · 값: JSON (기본 64KB) · 유저당 키 100개

## 읽기

GET `/v1/storage/{key}` — 없으면 `404 NOT_FOUND`

```json
{ "key": "save", "value": { "stage": 3, "items": [] }, "is_public": false, "version": 4, "updated_at": 1795055466 }
```

GET `/v1/storage` → `{ "items": [ 위와 같은 항목 … ] }`

## 저장

PUT `/v1/storage/{key}`

```json
{ "value": { "stage": 4 }, "version": 4, "is_public": false }
```

→ `{ "key": "save", "version": 5 }`

* `version`: 새 키는 `0`, 그다음은 마지막으로 읽거나 쓴 값. 다르면 `409 VERSION_CONFLICT` + `details.current_version`
* `is_public: true`면 다른 유저가 `/v1/players/{id}/public`으로 읽을 수 있습니다.

POST `/v1/storage/batch` — `{ "items": [ { "key", "value", "version", "is_public"? }, … ] }` → `{ "items": [ { "key", "version" }, … ] }`

## 삭제

DELETE `/v1/storage/{key}?version=5` — `version`을 생략하면 무조건 삭제

## 오류

| 오류 | 뜻 |
|---|---|
| `409 VERSION_CONFLICT` | 다른 기기가 먼저 저장함 — 다시 읽어 합친 뒤 저장 |
| `413 VALUE_TOO_LARGE` | 값 크기 초과 |
| `422 STORAGE_KEY_LIMIT` | 키 개수 초과 |
