TgScan API Documentation

API Authentication

To be able to query API on behalf of your user account you need to use API key. Use HTTP header "Api-Key: XXX" where XXX is your API key.

You can generate API key on https://tgdev.io/tgscan/api page. Only one API key per user account is allowed. When you generate new API key the old API key is removed (if it exists). Please remember API key when you see it first time. It is allowed to see API key only once. If you forget API key you'll need to generate new key.

API Key Security

You need to store your API key in secure location. Do not share it with people you do not trust. If you expose your API key you may loose all credits on your balance if third party will use your key to send requests to TgScan API.

Result of Failed API Request

Non-successful API results look like:

{
  "status": "error",
  "result": {
    "message": <str>
  }
}

The field ".result.message" contains short error description.

Result of Successful API Request

Successful API results look like:

{
  "status": "ok",
  "result": <struct>
}

The field ".result"contains result data. Structure of result data depends on API method you have called.

Groups Search Method

URL: https://api.tgdev.io/tgscan/v1/search

Required arguments:

  • query - must be a username (without "@") or Telegram numeric ID

Curl example: curl -H "Api-Key: XXX" --data "query=some_username" https://api.tgdev.io/tgscan/v1/search

Successful result looks like:

{
  "status": "ok",
  "result": {
    "user": {
      "id": <int>,
      "username": <str|null>,
      "first_name": <str>,
      "last_name": <str|null>
    },
    "username_history": [
      {
         "username": <str>,
         "date": <str>
       },
    ],
    "id_history": [
      {
         "id": <str>,
         "date": <str>
       },

    ]
    "meta": {
      "search_query": <str>,
      "known_num_groups": <int>,
      "num_groups": <int>,
      "op_cost": <int>
    },
    "groups": [
      {
        "username": <str|null>,
        "title": <str>,
        "date_updated": <str>
      }
    ]
  }
}      

Account Balance Method

URL: https://api.tgdev.io/tgscan/v1/balance

This method does not accept any arguments.

Curl example: curl -XPOST -H "Api-Key: XXX" --data https://api.tgdev.io/tgscan/v1/balance

Successful result looks like:

{
  "status": "ok",
  "result": {
    "num_credits": <int>
  }
}

Test Group Search Method

URL: https://api.tgdev.io/tgscan/v1/test/search

Required arguments:

  • query - must be a username (without "@") or Telegram numeric ID

You can use only test API keys with this method. Result of this method contains random data, the structure of response is same as in response of live search method.

Though credits are not withdrawn from your account's balance when you use test search method, you still need to have real credits on your balance to be able to test this method.