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.

Base URLhttps://tack.nullstacks.workers.dev
Format
JSON in, JSON out (content-type: application/json). The page routes /p and /r return 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.
Examples in

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)

FieldTypeNotes
contentstringRequired. The page source, up to 1 MB of UTF-8. Whitespace only is rejected.
typestringhtml, md or txt. Anything else, or missing, is stored as txt.
namestringOptional 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/k3m9x2qpa7
const 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' }
});
StatusBodyWhen
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.

TypeWhat you get
htmlThe 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.
mdRendered on the server into a clean reading page. Works with no JavaScript.
txtShown 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/k3m9x2qpa7
const 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.

StatusBodyCause
400Expected a JSON body.The request body was not valid JSON.
400Nothing to deploy.content missing, not a string, or blank.
413code: "too_large"Content is over 1 MB.
429code: "rate_limited"More than 30 deploys in a minute from one IP. Wait for the retry-after header (60 seconds).
405Method not allowed.Wrong HTTP method for the route.
500Could 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