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.

Everything on this page is also served as a machine-readable description at openapi.json: OpenAPI 3.1, every route with its authentication, its request and response shapes, its rate limits and its errors. It is built from one source in the repository, and a test walks the Worker's route table against it, so a route with no entry there fails the build. If you are an assistant rather than a person, start at The farm for AI assistants.

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 these 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, and so does checking for a new release. 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 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. The farm sends at most three codes per hour per address, ten per hour per client, and one hundred per hour across the service. 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

Art in the farm's hand

The farm draws a wide header and a square icon in its house style from one sentence describing the scene. Both are filed as your images under media/<you>/<id>/ and answered as URLs you can put straight into media. See Art in the farm's hand for what to write.

The scene is 3 to 200 characters on one line; anything else answers 400 without spending a try. You need a verified Tiiny profile, and the app ID has to be yours or unclaimed, or the answer is 403. Three drawings per app per day, twelve per maker, and thirty across the farm. Only one drawing runs at a time per app, so a second request while one is running answers 409. A drawing takes a minute or two, so give the call a generous timeout. A refusal from the drawing service answers 422 and a failure answers 502. Neither reduces the three tries shown for that app, but every accepted request counts toward the maker and farm safety caps.

curl --fail-with-body \
  -H "Authorization: Bearer $FARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scene": "a corkboard of pinned cards joined by threads of light"}' \
  https://tiinyapp.farm/api/seeds/my-app/art

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, seeds, thumbs (the same number under the name the first release used), 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.

Seeds and comments

A seed is the farm's thumbs up: one per person per app, given again to take it back.

/api/social/counts is one read for a whole catalog page, so a grid of apps does not ask once per tile. It needs no credential and is cached for 60 seconds. A maker's total is the seeds their apps have been given, added up, credited through the verified profile on each manifest. A maker who hid their page is not listed.

Reading needs nothing. Giving a seed needs a signed-in account or a farm_ token. 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.

thumbs carries the same number as seeds so an older reader keeps working. Read seeds.

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

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