Overview
Tack stores one page per request and hands back two URLs: /p/<id> renders it and /r/<id> returns the source untouched. Everything here is plain HTTP and JSON.
https://tack.nullstacks.workers.dev- Format
- JSON in, JSON out (
content-type: application/json). The page routes/pand/rreturn HTML and plain text. - Auth
- None to deploy or read. Deleting needs the edit key from the deploy response.
- Ids
- 10 lowercase letters and digits. Pages are unlisted: you can only reach one if you know its id.
- Limits
- 1 MB per page, 30 deploys per minute per IP.
POST/api/deploy
Stores a page and returns its id, its two links and an edit key. The edit key is shown once; only its hash is stored, so keep it if you want to delete the page later.
Body (JSON)
| Field | Type | Notes |
|---|---|---|
| content | string | Required. The page source, up to 1 MB of UTF-8. Whitespace only is rejected. |
| type | string | html, md or txt. Anything else, or missing, is stored as txt. |
| name | string | Optional title. Trimmed and cut to 80 characters. Defaults to Untitled. |
Example
curl -X POST https://tack.nullstacks.workers.dev/api/deploy \
-H 'content-type: application/json' \
-d '{"type":"md","name":"Hello","content":"# Hello from Tack"}'const res = await fetch('https://tack.nullstacks.workers.dev/api/deploy', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ type: 'md', name: 'Hello', content: '# Hello from Tack' })
});
const { id, editKey, preview, raw } = await res.json();201Created
{
"id": "k3m9x2qpa7",
"name": "Hello",
"type": "md",
"size": 17,
"ts": 1795000000000,
"editKey": "n4q8w2e7r5t3y6u9i2o5",
"preview": "/p/k3m9x2qpa7",
"raw": "/r/k3m9x2qpa7"
}preview and raw are paths: put the base URL in front of them. size is in bytes and ts is milliseconds since the Unix epoch. Failures are listed under Errors & limits.
GET/api/doc/:id
Returns a page’s metadata and its content. The edit key hash is never included.
curl https://tack.nullstacks.workers.dev/api/doc/k3m9x2qpa7const doc = await (await fetch('https://tack.nullstacks.workers.dev/api/doc/k3m9x2qpa7')).json();200OK
{
"id": "k3m9x2qpa7",
"name": "Hello",
"type": "md",
"size": 17,
"ts": 1795000000000,
"content": "# Hello from Tack"
}Responses are sent with cache-control: no-store. An unknown id returns 404.
DELETE/api/doc/:id
Permanently deletes a page. Send the edit key from the deploy response in the x-edit-key header. A valid id alone is not enough.
curl -X DELETE https://tack.nullstacks.workers.dev/api/doc/k3m9x2qpa7 \
-H 'x-edit-key: n4q8w2e7r5t3y6u9i2o5'await fetch('https://tack.nullstacks.workers.dev/api/doc/k3m9x2qpa7', {
method: 'DELETE',
headers: { 'x-edit-key': 'n4q8w2e7r5t3y6u9i2o5' }
});| Status | Body | When |
|---|---|---|
| 200 | {"ok":true} | Deleted. |
| 403 | {"error":"Wrong edit key."} | Key missing or not matching. |
| 404 | {"error":"Not found."} | No page with that id. |
Copies of /p and /r are cacheable for up to 5 minutes, so a browser or cache that already has the page may keep showing it briefly.
GET/p/:id
The shareable page. HEAD works too.
| Type | What you get |
|---|---|
| html | The stored source, served as written. Scripts run, but inside a sandbox with an opaque origin, so the page cannot read cookies or storage from Tack or from other pages. |
| md | Rendered on the server into a clean reading page. Works with no JavaScript. |
| txt | Shown as preformatted text in the same reading page. |
Success responses carry cache-control: public, max-age=300, x-content-type-options: nosniff and referrer-policy: no-referrer. An unknown id returns a 404 HTML page.
GET/r/:id
The source, byte for byte, as text/plain; charset=utf-8. This is the link to hand to a script. HEAD works too.
curl https://tack.nullstacks.workers.dev/r/k3m9x2qpa7const source = await (await fetch('https://tack.nullstacks.workers.dev/r/k3m9x2qpa7')).text();Sent with content-length, x-content-type-options: nosniff, cache-control: public, max-age=300 and access-control-allow-origin: *, so browsers on any origin can fetch it. Raw source is never served as HTML.
GET/health
A liveness check for monitors.
{ "ok": true, "service": "tack", "ts": 1795000000000 }Errors & limits
Errors from /api/* are JSON with an error message for people and, for some, a code for programs.
| Status | Body | Cause |
|---|---|---|
| 400 | Expected a JSON body. | The request body was not valid JSON. |
| 400 | Nothing to deploy. | content missing, not a string, or blank. |
| 413 | code: "too_large" | Content is over 1 MB. |
| 429 | code: "rate_limited" | More than 30 deploys in a minute from one IP. Wait for the retry-after header (60 seconds). |
| 405 | Method not allowed. | Wrong HTTP method for the route. |
| 500 | Could not save that page. | Storage failed. Safe to retry. |
Browsers and CORS
OPTIONS requests to /api/* answer 204 and allow GET, POST, DELETE and the content-type and x-edit-key headers. GET /r/:id is open to every origin. Servers, scripts and curl are not affected by CORS at all.
Tack is open source under the MIT license. github.com/nullstacks/tack