API Endpoints

SDK API

All SDK endpoints are served from your project’s API subdomain. The @tma.sh/sdk client handles these automatically — direct API calls are only needed for custom integrations.

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
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://{project}--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://{project}--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://{project}--api.tma.sh/sdk/v1/kv/user:preferences \
  -H "Authorization: Bearer {jwt}"

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

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

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

curl "https://{project}--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 Hono app from server/api/index.ts. These routes are deployed as a Cloudflare Worker and accessible at:

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

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.