# StaticSave API for Developers & AI Agents

StaticSave provides two primary integration methods for automated tools, CLI scripts, and AI agents:
1. **Model Context Protocol (MCP Server)**: Native AI tool calling for ChatGPT, Claude Desktop, Cursor, Antigravity, and Windsurf via standard JSON-RPC 2.0 (supports both authenticated hosting and anonymous temporary hosting).
2. **REST API Endpoints**: HTTP endpoints for CLI scripts, backends, and agents (supports both authenticated account operations and anonymous temporary hosting).

---

## 1. Model Context Protocol (MCP Server)

Connect StaticSave directly to AI assistants (ChatGPT, Claude Desktop, Cursor, Antigravity, Windsurf). The MCP server supports full account management as well as instant temporary hosting.

- **Base URL**: `https://mcp.staticsave.com`
- **Authenticated URL (ChatGPT / Remote)**: `https://mcp.staticsave.com?token=ss_your_api_token_here`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Server Card (Discovery)**: `https://staticsave.com/.well-known/mcp/server-card.json`
- **MCP Server Landing Page**: `https://staticsave.com/mcp-server`

### Available MCP Tools

#### Temporary Hosting (No Auth Required)
- `create_temporary_file`: Anonymous instant hosting with auto-generated UTC timestamp verification (`https://temp.staticsave.com/{hash}.{ext}`). Works without needing an API token.

#### Authenticated Account Tools (Requires Token)
- `get_account_info`: Retrieve account overview (total module folders, total hosted static files, premium status, and remaining limits).
- `list_folders`: Retrieve all active module folders in user's account.
- `create_folder`: Create a new module folder (4 to 15 lowercase alphanumeric characters, single hyphens in between allowed).
- `delete_folder`: Permanently delete a module folder and all files inside it.
- `list_files`: List hosted files with optional folder filtering and pagination.
- `get_file`: Retrieve the raw file content, visibility status, views, creation date, and last update timestamp of a hosted static file.
- `create_file`: Create or overwrite a static file or image under a module folder with configurable visibility (`public`, `unlisted`, `private`).
- `update_file`: Update an existing hosted static file or image with new content and optional visibility change.
- `delete_file`: Permanently delete a hosted static file.

### Quick Setup

#### ChatGPT (Custom MCP Server)
- **URL**: `https://mcp.staticsave.com?token=ss_your_api_token_here`
- **Auth**: Choose "OAuth or no authentication" (leave OAuth settings blank). Check confirmation and save.

#### Claude Desktop / Cursor / Antigravity (`mcpServers`)
```json
{
  "mcpServers": {
    "staticsave": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.staticsave.com",
        "--header",
        "Authorization: Bearer ss_your_api_token_here"
      ]
    }
  }
}
```

---

## 2. REST API Endpoints

Integrate StaticSave into automated scripts, curl commands, or backend workflows via standard HTTP endpoints.

### Option A: Temporary Hosting Endpoint (No Authentication Required)

Temporarily host text files or images without sign-up, API key, or CAPTCHA.

- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/temporary-hosting`
- **Headers**: `Content-Type: application/x-www-form-urlencoded`

#### Parameters
- `content` (required): Text content or raw Base64-encoded image string (max 30,000 characters / ~22 KB binary). For images, do not include the `data:image/...;base64,` prefix.
- `pagetype` (required): File extension:
  - Text/Code: `css`, `js`, `json`, `xml`, `txt`, `md`
  - Images: `webp`, `jpg`
- `utc-date-within-10-seconds` (required): Current ISO 8601 UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`) within 10 seconds of server time.

#### Returns
- **Success**: `{ status: true, message: string, url: "https://temp.staticsave.com/{hash}.{ext}" }`
- **Error**: `{ status: false, message: string }`

---

### Option B: Authenticated REST API (Personal API Token)

Users can generate a personal API token from their **Account Profile** (`/profile`) for persistent hosting, folder organization, and file lifecycle management.

#### Base URL & Authentication
- **Base Endpoint**: `https://api.staticsave.com/api`
- **Header**: `Authorization: Bearer ss_your_api_token_here`
- **Content-Type**: `application/x-www-form-urlencoded`
- **CDN Public Delivery**: `https://cdn.staticsave.com/{folder}/{filename}.{extension}`

#### File Visibility Levels (`public`, `unlisted`, `private`)
- **`public` (Default)**: File is indexed in public directories and directly accessible on global CDN.
- **`unlisted`**: File is hidden from directory/search listings, but accessible via direct CDN link.
- **`private` (Premium Only)**: Restricted visibility for premium members (falls back to `unlisted` on free accounts).

#### Rate Limits & Agent Guidelines
- **Automatic Limits in All Responses**: Every authenticated API response (`/user/action`, `/user/data`, and MCP tools) automatically returns the `limits` object containing remaining folders, files per folder, and total account files. You do NOT need to ping `account=1` repeatedly to check available capacity.
- **Sequential Calls Only**: Never send parallel or burst requests.
- **Pace Updates**: Pause briefly (~2s) between file updates to the same asset.
- **No Redundant Calls**: Only update files when content has changed.
- **Handle HTTP 429**: Back off gracefully if rate limit is encountered.

#### Account Limits Response Schema (`limits`)
Returned automatically in all authenticated responses:
```json
{
  "limits": {
    "remaining_folders": 1,
    "remaining_files": 4,
    "max_files_per_folder": 5,
    "folders": [
      {
        "name": "myfolder",
        "remaining_files": 4
      }
    ]
  }
}
```

---

#### Authenticated Endpoints Reference

##### 1. Account Info
Retrieve account folder count, total file count, premium plan status, and full remaining limits.
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/data`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `account=1` (required)
- **Returns**: `{ status: true, message: string, folders: number, files: number, premium: boolean, remaining_folders: number, remaining_files: number, files_per_folder_limit: number, limits: object }`

---

##### 2. List Folders
Retrieve all active module folders for your account.
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/data`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `folders=1` (required)
- **Returns**: `{ status: true, message: string, folders: [{ custom: string, date: string, pagecounts: number, lastupdate: string }] }`

---

##### 3. Create Folder
Create a new module folder (4 to 15 lowercase alphanumeric characters, single hyphens in between allowed).
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/action`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `addcustom=1` (required)
  - `customname` (required, 4–15 chars, lowercase alphanumeric with single hyphens in between)
- **Returns**: `{ status: true, message: string, folder: string }`

---

##### 4. Delete Folder
Permanently remove a module folder and all files hosted inside it.
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/action`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `deletecustom=1` (required)
  - `custom` (required, folder name)
- **Returns**: `{ status: true, message: string }`

---

##### 5. List Files
Retrieve your hosted files with optional pagination and folder filtering.
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/data`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `pages=1` (required)
  - `custom` (optional, filter by specific folder)
  - `limit` (optional, default 50)
  - `offset` (optional, default 0)
- **Returns**: `{ status: true, message: string, total: number, pages: [{ id: number, custom: string, pagename: string, pagetype: string, visibility: string, date: string, lastupdate: string }] }`

---

##### 6. Get File Content & Detail
Retrieve the content, analytics, and metadata of a hosted static file.
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/data`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `pagedetail=1` (required)
  - `custom` (required, folder name)
  - `pagename` (required, file name without extension)
  - `pagetype` (required: `css`, `js`, `json`, `xml`, `txt`, `md`, `webp`, `jpg`)
- **Returns**: `{ status: true, message: string, page: { custom: string, pagename: string, pagetype: string, views: number, date: string, lastupdate: string, content: string, visibility: string, banned: number } }`

---

##### 7. Create File
Create and publish a new static file or image under an existing folder.
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/action`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `addpage=1` (required)
  - `custom` (required, target folder name)
  - `pagename` (required, 4–15 alphanumeric chars, without extension)
  - `pagetype` (required: `css`, `js`, `json`, `xml`, `txt`, `md`, `webp`, `jpg`)
  - `content` (required, up to 30,000 characters):
    - **Code/Text files**: Raw text/code string.
    - **Images (`webp`, `jpg`)**: Base64-encoded string (max ~22KB binary). Automatically decoded by CDN into raw binary with proper MIME headers.
  - `visibility` (optional: `public` [default], `unlisted`, `private` [premium only])
- **Returns**: `{ status: true, message: string, file: string }`
- **CDN URL**: `https://cdn.staticsave.com/{custom}/{pagename}.{pagetype}`

---

##### 8. Update File
Overwrite the content of an existing file or image (purges CDN edge cache).
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/action`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `pageedit=1` (required)
  - `custom` (required, folder name)
  - `pagename` (required, file name without extension)
  - `pagetype` (required: `css`, `js`, `json`, `xml`, `txt`, `md`, `webp`, `jpg`)
  - `content` (required, up to 30,000 characters raw text or Base64 string)
  - `visibility` (optional: `public`, `unlisted`, `private`)
- **Returns**: `{ status: true, message: string }`

---

##### 9. Delete File
Permanently remove an existing hosted file.
- **Method**: `POST`
- **Endpoint**: `https://api.staticsave.com/api/user/action`
- **Headers**: `Authorization: Bearer ss_your_api_token_here`
- **Parameters**:
  - `deletepage=1` (required)
  - `custom` (required, folder name)
  - `pagename` (required, file name without extension)
  - `pagetype` (required, file extension)
- **Returns**: `{ status: true, message: string }`
