API Documentation - Reocities

Reocities API Documentation

Authentication

All API requests require authentication. You need to be logged in to use the API endpoints.

API Key Management

API keys are persistent and don't expire unless revoked by you.

Manage your API keys here - Generate, view, regenerate, or revoke keys as needed.

Include your API key in the X-API-Key header for all requests.

File Upload

POST /api/upload

Upload a single file to your website directory.

Parameters:

  • file (file, required) - The file to upload
  • folder (string, optional) - Target folder path
  • overwrite (boolean, optional) - Whether to overwrite existing files

Example Request:

curl -X POST "https://reocities.xyz/api/upload" \
  -H "X-API-Key: your-api-key" \
  -F "file=@/path/to/your/file.html" \
  -F "folder=subfolder" \
  -F "overwrite=true"

Response:

{
  "success": true,
  "message": "File uploaded successfully",
  "filename": "file.html",
  "path": "subfolder/file.html",
  "size": 1024
}
POST /api/upload/bulk

Upload multiple files at once (max 10 files per request).

Parameters:

  • files[] (file array, required) - Array of files to upload
  • folder (string, optional) - Target folder path
  • overwrite (boolean, optional) - Whether to overwrite existing files

Limits:

  • • Maximum 10 files per request
  • • Maximum 10MB per file
  • • Maximum 50MB total per request
  • • Rate limit: 5 requests per minute

Example Request:

curl -X POST "https://reocities.xyz/api/upload/bulk" \
  -H "X-API-Key: your-api-key" \
  -F "files[]=@/path/to/file1.html" \
  -F "files[]=@/path/to/file2.css" \
  -F "files[]=@/path/to/file3.js" \
  -F "folder=assets"

Response:

{
  "success": true,
  "message": "3 files uploaded successfully",
  "uploaded": [
    {
      "filename": "file1.html",
      "path": "assets/file1.html",
      "size": 1024,
      "status": "success"
    },
    {
      "filename": "file2.css",
      "path": "assets/file2.css",
      "size": 2048,
      "status": "success"
    },
    {
      "filename": "file3.js",
      "path": "assets/file3.js",
      "size": 512,
      "status": "success"
    }
  ],
  "failed": [],
  "total_size": 3584
}

File Management

GET /api/files

List all files in your website directory.

Parameters:

  • folder (string, optional) - Specific folder to list
  • recursive (boolean, optional) - Include subdirectories
DELETE /api/files

Delete a file or folder.

Parameters:

  • path (string, required) - Path to file or folder to delete
POST /api/folders

Create a new folder.

Parameters:

  • name (string, required) - Folder name
  • parent (string, optional) - Parent folder path

Key-Value Store

Instant per-site storage for counters, leaderboards, and saved JSON. Get your tokens at /kv. The read token is public (get, list, incr); the write token is secret (set, delete).

/api/kv
curl "https://www.reocities.xyz/api/kv?action=incr&key=hits&token=READ_TOKEN"
curl "https://www.reocities.xyz/api/kv?action=set&key=msg&value=hi&token=WRITE_TOKEN"

Browser library: <script src="/static/js/reokv.js"></script> then ReoKV(token) with methods get, set, setJSON, getJSON, incr, del, list. Limits: 64KB per value, 2000 keys, 120 ops per minute.

Error Codes

400 Bad Request

Invalid parameters or malformed request

401 Unauthorized

Missing or invalid API key

403 Forbidden

Access denied or rate limit exceeded

413 Payload Too Large

File size or request size exceeds limits

429 Too Many Requests

Rate limit exceeded

Rate Limits & Usage

Per-Minute Rate Limits:

  • • Single Upload: 10 requests per minute
  • • Bulk Upload: 5 requests per minute
  • • File Operations: 20 requests per minute

Daily Limits:

  • • Default: 1000 API calls per day
  • • Premium Users: 5000 API calls per day
  • • Limits reset at midnight UTC
  • • View your current usage