Install from s&box GitHub source
YAML Source is the Network Storage authoring standard.
Use the s&box Library Manager install for auto-updates. GitHub is best for agents, source review, contributions, and manual installs.

REST API Reference

All Network Storage REST endpoints are served from `https://api.sboxcool.com`. The library handles these URLs automatically — you only need this reference when ...

# REST API Reference

All Network Storage REST endpoints are served from `https://api.sboxcool.com`. The library handles these URLs automatically — you only need this reference when calling the API from external tools, scripts, or non-s&box runtimes.

**Base URL:** `https://api.sboxcool.com`
**Current version:** `v3` (also available on `v1` — same handlers, deprecated)

## Authentication

Most endpoints require an API key. Pass it via:

- **Header:** `x-api-key: sbox_ns_your_key`
- **Query param:** `?apiKey=sbox_ns_your_key`

Dedicated servers with a secret key use `x-api-key` for the secret and `x-public-key` for the public key.

---

## Queries

Run a dashboard query by ID and return the result.

```
GET /v3/queries/{projectId}/{queryId}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `projectId` | string | Your project ID |
| `queryId` | string | Query ID (e.g. `query_f5e3a2aff202`) |

**Auth:** Public API key. Secret-key queries require `x-api-key` with the dedicated server secret.

**Response (leaderboard):**

```json
{
  "entries": [
    { "key": "76561198000000001", "value": 1500.0, "rank": 1 },
    { "key": "76561198000000002", "value": 1200.0, "rank": 2 }
  ],
  "count": 2,
  "generatedAt": "2026-06-12T10:00:00Z",
  "ttl": 60
}
```

**Response (count):**

```json
{
  "count": 42,
  "generatedAt": "2026-06-12T10:00:00Z",
  "ttl": 60
}
```

**Response (sum/average):**

```json
{
  "sum": 125000.0,
  "average": 2976.19,
  "count": 42,
  "generatedAt": "2026-06-12T10:00:00Z",
  "ttl": 60
}
```

**Errors:**

| Code | Meaning |
|------|---------|
| `NOT_FOUND` | Query does not exist or belongs to a different project |
| `UNAUTHORIZED` | Missing or invalid API key |
| `SECRET_KEY_REQUIRED` | Query requires a dedicated-server secret key |

---

## Endpoints

Execute a server-side endpoint (read → validate → write).

```
POST /v3/endpoints/{projectId}/{endpointSlug}
GET  /v3/endpoints/{projectId}/{endpointSlug}
POST /v3/endpoints/{projectId}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `projectId` | string | Your project ID |
| `endpointSlug` | string | Endpoint slug (e.g. `load-profile`, `cast-line`) |

**Auth:** Public API key. Endpoints that modify player data require an s&box auth session or proxy call.

**Request body (POST):**

```json
{
  "ore_id": "moon_ore",
  "kg": 5.2
}
```

**Response:**

```json
{
  "ok": true,
  "data": {
    "xp": 150,
    "level": 3
  }
}
```

---

## Game Values

Load server-authoritative constants and tables.

```
GET /v3/values/{projectId}
```

**Auth:** Public API key.

**Response:**

```json
{
  "groups": {
    "progression": { "xp_per_level": 100, "max_level": 50 }
  },
  "tables": {
    "ore_types": {
      "rows": [
        { "name": "Moon Ore", "tier": 1, "base_price": 10.0 }
      ]
    }
  }
}
```

---

## Collection Data (Read/Write)

Directly read or write collection documents. For player-facing gameplay, prefer endpoints.

### Read a document

```
GET /v3/storage/{projectId}/{collectionId}/{key}
```

### Write a document

```
POST /v3/storage/{projectId}/{collectionId}/{key}
```

### Delete a document

```
DELETE /v3/storage/{projectId}/{collectionId}/{key}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `projectId` | string | Your project ID |
| `collectionId` | string | Collection name (e.g. `players`) |
| `key` | string | Document key (e.g. Steam ID `76561198000000001`) |

**Auth:** Public API key for reads. Writes require endpoint-controlled collection or secret key.

---

## Save Slot Records

Multi-record per-player collections (e.g. save slots).

### List records

```
GET /v3/storage/{projectId}/{collectionId}/{steamId}/records
```

### Create a record

```
POST /v3/storage/{projectId}/{collectionId}/{steamId}/records
```

### Rename a record

```
PATCH /v3/storage/{projectId}/{collectionId}/{steamId}/records/{recordId}
```

### Delete a record

```
DELETE /v3/storage/{projectId}/{collectionId}/{steamId}/records/{recordId}
```

---

## Global Collections (Append/List)

For global leaderboards, shared logs, and append-only collections.

### Append a record

```
POST /v3/storage/{projectId}/{collectionId}/append
```

### List records

```
GET /v3/storage/{projectId}/{collectionId}/list
```

### Get a specific record

```
GET /v3/storage/{projectId}/{collectionId}/record/{recordId}
```

---

## Ledger

Read the per-player operation ledger (audit trail).

```
GET /v3/storage/{projectId}/{collectionId}/{steamId}/ledger
```

---

## Rate Limits

Read rate limit configuration for a project.

```
GET /v3/storage/{projectId}/rate-limits
```

---

## Auth Sessions

Create and manage s&box authentication sessions for player identity verification.

### Create session

```
POST /v3/auth-sessions/{projectId}/create
```

### Refresh session

```
POST /v3/auth-sessions/{projectId}/refresh
```

### Re-authenticate session

```
POST /v3/auth-sessions/{projectId}/reauth
```

### Revoke session

```
POST /v3/auth-sessions/{projectId}/revoke
```

**Alias:** `/v3/sessions/{projectId}/...` (same handlers).

See [s&box Auth](/wiki/network-storage-v3/sbox-auth) for the full auth flow.

---

## Security Config

Read the project's security configuration (client write restrictions, allowed origins).

```
GET /v3/security-config/{projectId}
```

---

## Stats & Analytics

### Player stats heartbeat

```
POST /v3/storage/{projectId}/stats/heartbeat
```

### Get player stats

```
GET /v3/storage/{projectId}/stats/{steamId}
```

### Analytics event

```
POST /v3/storage/{projectId}/analytics/events
```

---

## Management API (Dedicated Server / CI)

Requires a dedicated-server secret key. Used by the Sync Tool, CI pipelines, and server-side automation.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v3/manage/{projectId}/game-values` | Read game values |
| `PUT` | `/v3/manage/{projectId}/game-values` | Write game values |
| `GET` | `/v3/manage/{projectId}/endpoints` | Read endpoint definitions |
| `PUT` | `/v3/manage/{projectId}/endpoints` | Write endpoint definitions |
| `PATCH` | `/v3/manage/{projectId}/endpoints` | Patch endpoint definition |
| `GET` | `/v3/manage/{projectId}/collections` | Read collection schemas |
| `PUT` | `/v3/manage/{projectId}/collections` | Write collection schemas |
| `PATCH` | `/v3/manage/{projectId}/collections` | Patch collection schema |
| `GET` | `/v3/manage/{projectId}/workflows` | Read workflow definitions |
| `PUT` | `/v3/manage/{projectId}/workflows` | Write workflow definitions |
| `PATCH` | `/v3/manage/{projectId}/workflows` | Patch workflow definition |
| `GET` | `/v3/manage/{projectId}/rate-limit-rules` | Read rate limit rules |
| `PUT` | `/v3/manage/{projectId}/rate-limit-rules` | Write rate limit rules |
| `GET` | `/v3/manage/{projectId}/settings` | Read project settings |
| `PUT` | `/v3/manage/{projectId}/settings` | Write project settings |
| `GET` | `/v3/manage/{projectId}/config` | Read project config |
| `GET` | `/v3/manage/{projectId}/tests` | Read test definitions |
| `PUT` | `/v3/manage/{projectId}/tests` | Write test definitions |
| `POST` | `/v3/manage/{projectId}/test-endpoint` | Run a single endpoint test |
| `POST` | `/v3/manage/{projectId}/suggest-tests` | AI-suggest test cases |
| `POST` | `/v3/manage/{projectId}/run-tests` | Run all tests |
| `POST` | `/v3/manage/{projectId}/auto-test` | Auto-test with generated inputs |
| `GET` | `/v3/manage/{projectId}/validate` | Validate source files |
| `POST` | `/v3/manage/{projectId}/source-upgrade` | Upgrade source format |
| `DELETE` | `/v3/manage/{projectId}/keys` | Destroy and rotate API keys |
| `POST` | `/v3/manage/{projectId}/package-sync` | Sync game package |
| `GET` | `/v3/manage/{projectId}/game-package` | Read game package |
| `GET` | `/v3/manage/{projectId}/sync-jobs/{jobId}` | Check sync job status |
| `POST` | `/v3/manage/{projectId}/sync/preflight` | Preflight sync check |
| `PUT` | `/v3/manage/{projectId}/sync` | Execute sync |

---

## Pages API

Read published broadcast/page content for in-game display.

```
GET /api/pages/{projectId}/{pageSlug}
```

---

## Deprecated Routes (v0/v1)

The `v0` routes use the `/api/storage/` prefix. The `v1` routes mirror `v3` exactly. Both are deprecated — use `v3`.

| v0 (deprecated) | v3 equivalent |
|-----------------|---------------|
| `GET /api/storage/{projectId}/queries/{queryId}` | `GET /v3/queries/{projectId}/{queryId}` |
| `GET /api/storage/{projectId}/{collectionId}/{key}` | `GET /v3/storage/{projectId}/{collectionId}/{key}` |
| `POST /api/storage/{projectId}/{collectionId}/{key}` | `POST /v3/storage/{projectId}/{collectionId}/{key}` |
| `DELETE /api/storage/{projectId}/{collectionId}/{key}` | `DELETE /v3/storage/{projectId}/{collectionId}/{key}` |

---

## Error Responses

All endpoints return errors in this format:

```json
{
  "error": {
    "code": "ENDPOINT_NOT_FOUND",
    "message": "Endpoint not found. Check the URL slug and HTTP method match your endpoint configuration."
  }
}
```

Common error codes: `UNAUTHORIZED`, `NOT_FOUND`, `ENDPOINT_NOT_FOUND`, `SECRET_KEY_REQUIRED`, `RATE_LIMITED`, `VALIDATION_ERROR`.

See [Error Codes](/wiki/network-storage-v3/error-codes) for the full list.