API reference

Every route the farm serves, how requests are authenticated, what the limits are, and what an error looks like.

The farm runs as a Cloudflare Worker in front of a static site. Everything under /api/, plus the account, maker and app file routes, is handled by the Worker; everything else is a static file.

The base is https://tiinyapp.farm. Responses are JSON with Cache-Control: no-store unless stated otherwise.

Authentication

There are two credentials and they are not interchangeable.

A session cookie. Signing in with an email code or with GitHub sets __Host-farm, which is HttpOnly, Secure, SameSite=Lax and lasts 30 days. The site uses it. Signing in again replaces the previous session rather than adding one.

A bearer token. Create one on Your apps, copy it once, and send it as Authorization: Bearer farm_.... A token is farm_ followed by 40 hexadecimal characters. Only four routes accept one:

Everywhere else a token is ignored and the cookie decides. Creating and revoking tokens needs the cookie, so a token cannot mint another token. Tokens are stored as SHA-256 hashes, never in the clear, and each use records the time it was last used.

The origin rule. Any POST, PUT, PATCH or DELETE that does not carry a bearer token on one of those four routes must send Origin: https://tiinyapp.farm, or it is refused with 403 and Please submit this form from tiinyapp.farm. This is what stops another site posting with a visitor's cookie.

Sign in

A code lasts ten minutes and dies after five wrong attempts. Three codes per hour per address. If you are already signed in when you start either flow, finishing it links that method to your existing account rather than making a second one; finishing it from a different account is refused with 403.

Email sign-in answers 503 when the mail credential is not configured, and GitHub sign-in answers 503 when its client id and secret are not.

Prove you own a Tiiny

The code lasts 24 hours. Verify fetches your public profile, looks for the exact code as a whole word, and reads your display name from the page heading. A profile already claimed by another account answers 409, an unreadable or private profile answers 422, and a missing code answers 422 with an instruction to add it and try again.

/api/owners is the public lookup the pull request checks use to confirm a manifest's owner. It needs no credential and is the one route that skips the Worker's request queue, so it stays responsive during an upload.

Your account

The full token is in the creation response and nowhere else afterwards; only its prefix is kept for display. Five live tokens per account. Creating one needs a verified Tiiny profile.

A bio is at most 600 characters. Maker links are github, website and youtube only, and each must be an HTTPS URL. An avatar key must be an image you uploaded to your own account. Turning your profile off leaves your maker page reachable only to signed-in visitors.

Images

Up to 2 MiB. The type is read from the file's own first bytes, not its name, and only PNG, JPEG and WebP are accepted; anything else answers 415. Uploading needs a verified Tiiny profile. You can only delete your own images. Served images are immutable and cached for a year.

curl --fail-with-body \
  -H "Authorization: Bearer $FARM_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @art/icon.png \
  https://tiinyapp.farm/api/media

Apps

These are the routes farm publish and farm status <id> use. The form fields are:

Send a release URL or an upload, never both. A release URL is fetched with a ten second deadline and may redirect up to three times; the URL must be HTTPS on port 443, with no credentials, no fragment, and a real public hostname. The first two bytes of whatever arrives must be gzip. The farm measures the SHA-256 and the exact size itself; numbers you supply are not used.

An update must carry a strictly newer version when it changes the release, and may keep the current version for a text-only change.

curl --fail-with-body \
  -H "Authorization: Bearer $FARM_TOKEN" \
  -F 'id=my-app' \
  -F 'name=My App' \
  -F 'pitch=One useful line' \
  -F 'description=What the app does and what users should know.' \
  -F 'version=0.1.0' \
  -F 'license=MIT' \
  -F 'tags=developer-tools' \
  -F 'entry={"command":"python -m my_app"}' \
  -F 'permissions=network,device' \
  -F 'repo=https://github.com/example/my-app' \
  -F 'archive=@my-app-0.1.0.tar.gz;type=application/gzip' \
  https://tiinyapp.farm/api/seeds

Each entry in GET /api/seeds/mine carries id, name, version, icon, state, prUrl, a checks array of {name, status}, a reviews array, thumbs, comments, and canUpdate. When GitHub cannot be reached the entry carries unavailable: true and its stored state instead. States you will see are preparing, label pending, awaiting review, draft, closed, merged, published, submission failed and submission uncertain.

Three answers are 202 rather than an error, and each says what to do: an interrupted review request that may still have succeeded, a submission that reached review but whose label did not, and the same form sent again to retry that label.

Comments and thumbs up

Reading needs nothing. A thumb needs a signed-in account. A comment needs a verified Tiiny profile, is 1 to 1,000 characters, and is limited to five per hour; deleting your comments does not give the limit back. A comment can be deleted by its author or by a farm admin. Only apps in the deployed catalog have a conversation, so an unknown id answers 404, and the wrong method for a route answers 405.

Each comment comes back as {id, author: {handle, name, avatar}, text, at, canDelete}. The author name falls back to "A maker" when a profile is not readable, and an email address is never part of it.

Check for a new release

Arrives with the release path. This route is on the open pull request #5.

Only the app's own verified maker may call it, and only once a minute per app; a second call inside that minute answers 429 with the number of seconds left. status is one of found, listed, none, manual or untracked, and message is the sentence shown to the maker. A found answer also carries the pull request URL. Without the farm's GitHub App credentials the two answers that need no credential still work and anything further answers 503.

Files and pages the Worker serves

Three old paths answer 301: /plant to /install/, /seeds to /submit/, and /farm to /account/.

Rate limits and sizes

Errors

Every failure is JSON with one error field holding a sentence meant for a person:

{"error": "Verify you own a Tiiny before submitting an app."}

An unexpected error answers 502 with The request could not be completed. Please try again. rather than the underlying text, because those can contain credentials.

All documentation Install an app Submit an app