# Publish to Promptbox — API v2.0
Publish apps at **https://apps.promptbox.cn/** and documents/media at **https://www.promptbox.cn/publish/**. No account or API key is required to create a publication. Everything expires after 30 days; successful app updates restart that clock.
- Endpoint: `POST https://promptbox.cn/api/publish.php`
- [Capabilities JSON](https://promptbox.cn/api/publish.php?action=capabilities)
- [All API superpowers](https://promptbox.cn/api/docs.html)
- [OpenClaw publishing skill](https://promptbox.cn/skills/promptbox-publish/SKILL.md)
- [Agent discovery guide](https://promptbox.cn/robots.txt)
To install the OpenClaw skill, [download the skill ZIP](https://promptbox.cn/skills/promptbox-publish.zip) and extract its `SKILL.md` into `~/.openclaw/skills/promptbox-publish/` (or your OpenClaw workspace's `skills/promptbox-publish/`). Start a new OpenClaw session so it discovers the skill. The skill contains instructions only; it does not install software or add publishing credentials.
## Publish a web app
Upload one HTML file or a ZIP with `index.html` at the root. Supply `mode=app` and a `directory` of 1–80 ASCII letters, digits, underscores or hyphens, starting with a letter or digit. A duplicate gets `_2`, `_3`, etc. HTML uploads become `index.html`.
```bash
curl https://promptbox.cn/api/publish.php \
-F 'mode=app' -F 'directory=my-app' -F 'file=@app.html'
curl https://promptbox.cn/api/publish.php \
-F 'mode=app' -F 'directory=my-app' -F 'file=@app.zip'
```
For a self-contained request, send UTF-8 HTML as JSON:
```bash
curl https://promptbox.cn/api/publish.php \
-H 'Content-Type: application/json' \
--data '{"mode":"app","directory":"hello","text":"HelloHello world
"}'
```
Creation returns HTTP **201**, for example:
```json
{"ok":true,"mode":"app","directory":"hello","url":"https://apps.promptbox.cn/hello/","token":"","updated":false,"files_written":["index.html"],"removed_files":[],"bytes":65,"expires_at":"","deleted_expired":0}
```
Save the returned UUID `token` privately. It authorizes changes to this app; possession is ownership. The server stores only its SHA-256 lookup key in private storage outside the web root. Do not embed it in app code, URLs or public output. Always use the returned directory and URL, since the requested directory may have received a suffix.
### Limits and safe extraction
Apps allow **25 MiB per upload**, **25 MiB total expanded/resulting app**, and **1,000 files**. ZIP entry counts and expanded sizes are checked before extraction. Excessive compression ratios, encrypted/corrupt archives and duplicate/case-conflicting paths are rejected. Upload the contents of your build folder, not a ZIP with an extra parent folder.
Allowed assets: `html htm css js mjs json txt md png jpg jpeg gif webp ico avif woff woff2 ttf otf mp3 wav ogg m4a flac mp4 webm`. Names use ASCII letters, digits, underscores, hyphens, dots and internal spaces. Dotfiles, absolute/traversal paths, links, server configuration, server-side code, SVG, executables, dependencies under `node_modules`, and other unsupported files are discarded without being extracted. `removed_files` lists discarded names; inspect it before declaring success. Files such as `.env` are never published.
HTML and JavaScript can still contain harmful behavior; extension checks cannot determine intent. Apps are served only on `apps.promptbox.cn` as static content with an opaque-origin CSP sandbox. Scripts, forms, downloads, HTTPS assets and CORS-enabled API calls work. Cookies, localStorage, IndexedDB, service workers, iframes, popup windows and `` are unavailable. Use relative URLs such as `./assets/app.js`, not `/assets/app.js`. Module scripts and fonts are served with public CORS headers. Published apps cannot read the main site's storage, but may use intentionally public APIs. Never put private data into an untrusted app.
### Update using the token
```bash
curl https://promptbox.cn/api/publish.php \
-F 'mode=app' -F 'token=YOUR_SAVED_UUID' -F 'file=@app.zip'
```
`Authorization: Bearer YOUR_SAVED_UUID` is an alternative to the form/JSON token. Send `mode=app` when using the header. `directory` is optional on updates; if supplied, it must match the existing directory. Updates return HTTP **200**, the same URL and token, `updated:true`, and a new expiry time. Uploaded files overwrite matching paths; other existing files remain. An HTML upload overwrites `index.html`; an asset-only ZIP is allowed if the resulting app has a root `index.html`. Invalid updates leave existing files intact. Publishing uses a private staging directory and a rollback copy during replacement.
Lost tokens cannot be recovered, and expired tokens cannot update. There is no per-file deletion API. Without a token, a new request always creates a new directory. A creation retry after a lost response can create a duplicate.
## Publish documents and media
```bash
curl https://promptbox.cn/api/publish.php \
-F 'mode=file' -F 'name=project-report' -F 'file=@report.pdf'
```
One actual multipart `file` field is required for binary files; do not send a filename, URL or base64 string. Let `curl -F` or FormData set Content-Type and its boundary. `name` is optional; it is a basename without extension. Duplicate filenames get `_02`, `_03`, etc. Documents are never overwritten and have no update token.
| Category | Formats | Limit |
|---|---|---|
| Documents | PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP | 10 MiB |
| Images | JPG, JPEG, PNG, GIF, WEBP | 10 MiB |
| Audio/video | MP3, WAV, OGG, M4A, FLAC, MP4, WEBM | 10 MiB |
| UTF-8 text | TXT, MD, JSON, CSV, TSV | 1 MiB |
Modern Office/OpenDocument packages are checked for structure, macros, embedded objects and active content. Ordinary web/mail hyperlinks are allowed; external data/resource relationships are rejected. Legacy binary Office files (`doc`, `xls`, `ppt`), macro-enabled formats, SVG and archives are not accepted as documents. Convert them to the supported formats first. PDF checks reject obvious active content and validate its basic signature; this is not a complete PDF sanitizer or malware scan. Documents are served as downloads with `nosniff` and a restrictive browser sandbox, not as executable pages. These checks cannot guarantee safety in desktop document viewers.
Success returns HTTP **201**:
```json
{"ok":true,"mode":"file","filename":"project-report.pdf","url":"https://www.promptbox.cn/publish/project-report.pdf","bytes":12345,"expires_at":"","deleted_expired":0}
```
Existing text requests continue to work:
```bash
curl https://promptbox.cn/api/publish.php \
-H 'Content-Type: application/json' \
--data '{"name":"hello","extension":"txt","text":"Hello world"}'
```
Aliases `title`, `content` and `ext` remain accepted for `name`, `text` and `extension`. Conflicting aliases are rejected. HTML always uses the new app flow—even a legacy `extension=html` request uses `name` as the directory and returns an app URL/token. Existing HTML files in `/publish/` are served as plain-text downloads.
## Expiry, errors and verification
Each app expires 30 days after its last successful change; each single file expires 30 days after creation. Lazy cleanup runs on POST requests and removes expired app directories and their token records together. GET capabilities and OPTIONS have no cleanup side effects. Keep your source files and token locally; there is no durability guarantee after expiry.
Global limits remain 60 successful publications/hour, 300/day and 100 MiB public storage. There is a 10,000-document limit. Invalid input does not consume publishing quota; a storage failure after quota reservation can consume one use. The request-body ceiling is 26 MiB, with the lower per-mode limits enforced on content.
Errors return `{"ok":false,"error":"...","help":{"capabilities":"...","docs":"...","guide":"..."}}`. HTTP 400/401/403/405/409/413/415/422 require a corrected request or token; do not retry unchanged. HTTP 429 supplies `Retry-After`; 507 means shared storage is full. Investigate 500/503/network failures before retrying a creation with an uncertain result. Updates can be retried with their saved token and the same content.
After success, GET the returned URL, inspect `removed_files`, and test page interactions and assets. Return the public URL and expiry to the user while keeping the token private.
## Add Promptbox superpowers
Use the [API reference](https://promptbox.cn/api/docs.html) to add LLM answers, attachment understanding, web/page research, images, transcription, speech, music, YouTube and social search, financial data, notes/memory/knowledge graphs, documents, PDF creation, media processing, email and QR codes. Read the relevant section for its exact `.php` endpoint, method, fields, output and quota. Use absolute HTTPS helper URLs and omit browser credentials; sandboxed app requests have `Origin: null`. APIs that require same-origin authentication or do not allow CORS will need a different integration. Do not put credentials in public code.