API Endpoints

SDK API

SDK endpoints are served by the platform API at https://api.tma.sh. The @tma.sh/sdk client handles these calls automatically.

Method	Endpoint	Description
POST	/sdk/v1/auth/validate	Validate Telegram initData, returns JWT
GET	/.well-known/jwks.json	Global JWKS keys for JWT verification
PUT	/sdk/v1/kv/:key	Set a KV value
GET	/sdk/v1/kv/:key	Get a KV value
DELETE	/sdk/v1/kv/:key	Delete a KV value
GET	/sdk/v1/kv?prefix=	List KV keys by prefix
POST	/sdk/v1/analytics	Submit analytics events (/sdk/v1/analytics/event also accepted)
POST	/sdk/v1/payments/stars/invoice	Create a Stars invoice link

Authentication

POST /sdk/v1/auth/validate

Validates the Telegram initData string and returns a signed JWT. The request body requires both initData and projectId. An optional platform field can be included to specify the client platform. The JWT can be verified against the global JWKS endpoint.

curl -X POST https://api.tma.sh/sdk/v1/auth/validate \
  -H "Content-Type: application/json" \
  -d '{
    "initData": "query_id=AAH...",
    "projectId": "your-project-id",
    "platform": "tma"
  }'

The platform field is optional and defaults to "tma" if omitted.

GET /.well-known/jwks.json

Returns the global public JSON Web Key Set for verifying JWTs issued by the /sdk/v1/auth/validate endpoint. This endpoint is served globally at api.tma.sh and is not per-project. Use this with any standard JWKS-compatible JWT library for server-side token verification.

curl https://api.tma.sh/.well-known/jwks.json

KV Storage

All KV endpoints require a valid JWT in the Authorization header.

PUT /sdk/v1/kv/:key — Set a value.

curl -X PUT https://api.tma.sh/sdk/v1/kv/user:preferences \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{"theme": "dark"}'

GET /sdk/v1/kv/:key — Retrieve a value.

curl https://api.tma.sh/sdk/v1/kv/user:preferences \
  -H "Authorization: Bearer {jwt}"

DELETE /sdk/v1/kv/:key — Delete a value.

curl -X DELETE https://api.tma.sh/sdk/v1/kv/user:preferences \
  -H "Authorization: Bearer {jwt}"

GET /sdk/v1/kv?prefix= — List keys matching a prefix.

curl "https://api.tma.sh/sdk/v1/kv?prefix=user:" \
  -H "Authorization: Bearer {jwt}"

Payments

All payment endpoints require a valid JWT in the Authorization header.

POST /sdk/v1/payments/stars/invoice — Create a Telegram Stars invoice link.

The platform uses the project’s stored bot token to create the invoice via the Telegram Bot API. No bot token is needed client-side.

curl -X POST https://api.tma.sh/sdk/v1/payments/stars/invoice \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Subscription",
    "description": "Access premium features for 30 days",
    "payload": "{\"plan\": \"premium\"}",
    "prices": [{"label": "Premium (30 days)", "amount": 100}]
  }'

Returns { "success": true, "data": { "invoiceUrl": "https://..." } }. The invoiceUrl can be opened with window.Telegram.WebApp.openInvoice() or via the SDK’s tma.payments.stars.pay() method.

---

User API Routes

Developers can define custom API routes by exporting a standard fetch handler from server/api/index.ts. Any framework that produces a Workers-compatible module works (Hono, itty-router, or plain fetch). These routes are deployed as a Cloudflare Worker and accessible at:

https://{project}--api.tma.sh/*
https://pr{number}--{project}--api.tma.sh/*

Same-origin /api/* requests are also proxied on {project}.tma.sh and pr{number}--{project}.tma.sh.

User-defined routes have access to project environment variables and KV bindings. See the API Routes guide for setup details.

---

GitHub Webhooks

POST /api/webhooks/github

Receives push events from GitHub to trigger auto-deployments. The request body is verified using HMAC-SHA256 signature validation via the X-Hub-Signature-256 header.

This endpoint is configured automatically when connecting a GitHub repository to a project. Manual setup is not required.