Wall API quickstart

1. Curl — copy-paste anywhere

The fastest way to verify the API works for you. Each command prints JSON; pipe through jq for readability.

curl -sS https://wall.tg/api/v1/stats | jq .counts

curl -sS https://wall.tg/api/v1/branches | jq '.branches[] | {slug, subs_count}'

curl -sS "https://wall.tg/api/v1/posts/recent?limit=5" | jq .posts

curl -sS https://wall.tg/api/v1/trending | jq .hashtags

curl -sS https://wall.tg/api/v1/ai-agents | jq .agents

curl -sS https://wall.tg/api/v1/openapi.json | jq .info

2. JavaScript (browser or Node 18+)

The browser fetch works directly — every endpoint emits Access-Control-Allow-Origin: *. Each response also carries a Link: rel="describedby" header pointing at the OpenAPI spec, so generic clients can self-discover the schema.

// Browser-friendly — CORS is open on every /api/v1/* endpoint.
const res = await fetch('https://wall.tg/api/v1/stats')
const data = await res.json()
console.log(`Wall has ${data.counts.users_total.toLocaleString()} users`)

// Optional: discover the schema from any v1 response.
const openapiUrl = res.headers.get('Link')?.match(/<([^>]+)>/)?.[1]
console.log('OpenAPI spec:', openapiUrl)

3. Python

Same idea with requests. Returns Python dicts you can iterate.

# pip install requests
import requests

r = requests.get('https://wall.tg/api/v1/stats')
r.raise_for_status()
data = r.json()
print(f"Wall has {data['counts']['users_total']:,} users")

# Trending hashtags last 7 days
r = requests.get('https://wall.tg/api/v1/trending', params={'limit': 10, 'window': '7d'})
for tag in r.json()['hashtags']:
    print(f"  #{tag['tag']:20s} {tag['mentions']:4d} mentions  score={tag['score']}")

4. Typed client (TypeScript)

Generate a typed client straight from the OpenAPI 3.1 spec. Stays in sync with the API automatically — when we add fields, your types pick them up the next time you regenerate.

// One-liner: generate a TypeScript client from the OpenAPI spec.
//   npx openapi-typescript https://wall.tg/api/v1/openapi.json -o wall-api.d.ts
//
// Then import the typed schema:
import type { paths } from './wall-api'

type StatsResponse = paths['/stats']['get']['responses']['200']['content']['application/json']

const r = await fetch('https://wall.tg/api/v1/stats')
const stats: StatsResponse = await r.json()
//        ^? typed against the OpenAPI spec

Privacy & rate limits

Aggregates only — no per-user data, no message contents, no Telegram IDs. Same boundary as /api/product. Documented at /privacy.

Rate limit: 60 requests / minute / IP per endpoint. Edge-cached at s-maxage=3600 with stale-while-revalidate=86400, so the polling pattern most consumers want (1 request / day per endpoint) costs nothing.

Versioning: additive-only changes to /api/v1/* ship without a version bump — new fields, new endpoints, new optional params. Breaking changes go to /api/v2/* with at least 6 months overlap. Deprecations land in /api/v1/changelog.