API Reference

By default, every request increments the counter. The endpoint format is:

GET /hits/:id/:resource[.format]

Path Parameters

Segment	Description
:id	Namespace
:resource	Counter name
.format	Optional. Use .json or .svg. JSON is default

Each counter is a single row in the hits table of a Cloudflare D1 database, keyed by the :id and :resource segments:

Column	Type	Description
id	TEXT	The :id segment of the route
resource	TEXT	The :resource segment of the route
visit	INTEGER	Total number of hits for this counter

id and resource form the primary key, so <id>/<resource> is the counter's unique identity. A request increments the counter with a single atomic upsert, which means concurrent requests never lose a hit. The row is created by the first request that increments the counter.

If you only want to read the current value without incrementing it, append ?mode=read. This is useful when the same page fetches the counter more than once. Read-only requests never create a row, and an unknown counter reads as 0.

JSON Response

If you want to render the number yourself, request JSON:

GET /hits/github/tally-api
GET /hits/github/tally-api.json

Example response structure:

type Response = {
  visit: number;
};

Field	Description
visit	Total number of hits since the counter was created

Header	Value
Content-Type	application/json
Cache-Control	max-age=0, no-cache, no-store, must-revalidate
Access-Control-Allow-Origin	*

SVG Counter

If you want a badge-style counter for a README or webpage, request SVG:

GET /hits/github/tally-api.svg
GET /hits/github/tally-api.svg?theme=gelbooru

The response is a pixel-style counter image that can be embedded directly in Markdown or HTML.

Header	Value
Content-Type	image/svg+xml
Cache-Control	max-age=0, no-cache, no-store, must-revalidate
Access-Control-Allow-Origin	*

Query Parameters

Parameter	Default	Description
mode	-	Set to read to return the current value only
theme	moebooru	Counter theme. Supports the full Moe Counter set

Themes

Tally API includes the full Moe Counter theme set. Common choices include moebooru, gelbooru, miku, and minecraft.

If theme is invalid, the service falls back to moebooru automatically.

Error Responses

Status	Response body	Description
400	{ "error": "Missing id or resource" }	Missing required route params
400	{ "error": "Invalid resource" }	Resource parsing failed

Credits

The SVG themes and rendering approach are inspired by journey-ad/Moe-Counter. Tally API keeps the familiar image-counter workflow and adds a JSON endpoint for scripts and custom UI.