> ## Documentation Index > Fetch the complete documentation index at: https://docs.ton.org/llms.txt > Use this file to discover all available pages before exploring further. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback: POST https://docs.ton.org/feedback ```json { "path": "/ecosystem/tma/analytics/api-endpoints", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # API Endpoints Here, you can view information about existing endpoints and how to make requests for them. ## API URL URL for POST requests: [`/events`](https://tganalytics.xyz/events) ## POST events This request is needed to record an event in the database. ### Body The request body may contain an array rather than a single event. The main thing is that all events in the array satisfy the scheme below. #### Required | Field | Type | Description | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user_id` | number | Unique identifier for the user. | | `event_name` | string | The name of the event from the supported events. | | `session_id` | string | Session identifier for tracking user sessions. **Must be** [UUID](https://github.com/Telegram-Mini-Apps/analytics/blob/master/src/utils/generateUUID.ts). | | `app_name` | string | The name of the application that you specified when creating the token | #### Optional | Field | Type | Description | | ------------------ | ------------------------------------- | --------------------------------------------------------------------------------------------- | | `is_premium` | boolean | If the user has a premium account, by default - false | | `is_success` | boolean | Indicates whether a wallet is connected or the transaction was successful, by default - false | | `error_message` | string | Error message if the wallet connection or transaction is unsuccessful | | `error_code` | number | Description: error code if the wallet connection or transaction is unsuccessful | | `wallet_address` | string | Wallet address involved in the event | | `wallet_type` | string | Type of the wallet | | `wallet_version` | string | Version of the wallet software | | `auth_type` | enum | Type of authorization used. `0` - `ton_addr`, `1` - `ton_proof`. | | `valid_until` | string | Timestamp until when a transaction offer is valid | | `from` | string | Wallet address initiating the transaction | | `messages` | `{ address: string; amount: string }` | List of transactions `{to, amount}` involved in the event | | `custom_data` | object | Object to store custom event details as needed | | `client_timestamp` | string | The time when the event occurred on the client | | `platform` | string | The platform from which the MiniApp was opened | | `locale` | string | User language code | | `start_param` | string | `tgWebAppStartParam` | | `url_referer` | string | The URL of the web application from which the request was sent | | `scope` | string | Event scope | ### Request body example: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} [ { "event_name": "app-init", "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d", "user_id": 111111111, "app_name": "docs", "is_premium": true, "platform": "tdesktop", "locale": "en", "client_timestamp": "1743503599534" } ] ``` ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} [ { "event_name": "connection-started", "custom_data": { "ton_connect_sdk_lib": "3.0.3", "ton_connect_ui_lib": "2.0.5" }, "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d", "user_id": 111111111, "app_name": "docs", "is_premium": true, "platform": "tdesktop", "locale": "en", "client_timestamp": "1743503647541" } ] ``` ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} [ { "event_name": "connection-error", "is_success": false, "error_message": "Connection was cancelled", "error_code": null, "custom_data": { "ton_connect_sdk_lib": "3.0.3", "ton_connect_ui_lib": "2.0.5" }, "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d", "user_id": 111111111, "app_name": "docs", "is_premium": true, "platform": "tdesktop", "locale": "en", "client_timestamp": "1743503683701" } ] ``` ### Headers Instead of `YOUR_TOKEN`, you need to specify the token received using the managing integration. (TO DO link) ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "TGA-Auth-Token": "YOUR_TOKEN", "Content-Type": "application/json" } ``` ### Responses #### HTTP201 * Description: The event has been successfully recorded * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "message": "Success record." } ``` #### HTTP400 * Description: The event was not recorded due to server issues * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "message": "Failed to record" } ``` #### HTTP400 * Description: The token was entered incorrectly or in the wrong format * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "message": "The token is not specified in the headers or is specified incorrectly." } ``` #### HTTP400 * Description: The entered token is invalid (was not created through a Data Chief bot) * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "message": "Token is invalid." } ``` #### HTTP400 * Description: The request body contains the application name that does not match the token * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "message": "Invalid app_name is specified." } ``` #### HTTP400 * Description: the body specified in the request was not validated (for example, the type of one of the fields does not match) * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "status": 400, "message": "VALIDATION_MISMATCH_REPORT" } ``` #### HTTP403 * Description: an attempt to use the API on a domain name that does not match the token * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "message": "The domain name does not match." } ``` #### HTTP429 * Description: too many requests from the client in a certain amount of time * Content: ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}} { "message": "Too many requests. Try again later." } ```