What are Attempts?

Attempts are used to detect if a user is trying to connect while already banned. It will record every instance of their attempts and keep track of their IP address so you can see if they're attempting to avoid the ban or not.

GET /bans/attempts

This will return a collection of the latest attempts paginated by 25 results.

Request Payload: GET http://freya.test/api/v1/bans/attempts

Response: 200 OK

{
  "data": [
    {
      "id": 12,
      "ban_id": 2,
      "steam_id": "76561198013448859",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:42:04.000000Z",
      "updated_at": "2020-08-09T03:42:04.000000Z"
    },
    {
      "id": 10,
      "ban_id": 2,
      "steam_id": "76561198013448859",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:42:03.000000Z",
      "updated_at": "2020-08-09T03:42:03.000000Z"
    },
    {
      "id": 11,
      "ban_id": 2,
      "steam_id": "76561198013448859",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:42:03.000000Z",
      "updated_at": "2020-08-09T03:42:03.000000Z"
    },
    {
      "id": 9,
      "ban_id": 2,
      "steam_id": "76561198013448859",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:42:02.000000Z",
      "updated_at": "2020-08-09T03:42:02.000000Z"
    },
    {
      "id": 8,
      "ban_id": 2,
      "steam_id": "76561198013448859",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:42:01.000000Z",
      "updated_at": "2020-08-09T03:42:01.000000Z"
    },
    {
      "id": 7,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:57.000000Z",
      "updated_at": "2020-08-09T03:41:57.000000Z"
    },
    {
      "id": 5,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:56.000000Z",
      "updated_at": "2020-08-09T03:41:56.000000Z"
    },
    {
      "id": 6,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:56.000000Z",
      "updated_at": "2020-08-09T03:41:56.000000Z"
    },
    {
      "id": 4,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:55.000000Z",
      "updated_at": "2020-08-09T03:41:55.000000Z"
    },
    {
      "id": 2,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:54.000000Z",
      "updated_at": "2020-08-09T03:41:54.000000Z"
    },
    {
      "id": 3,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:54.000000Z",
      "updated_at": "2020-08-09T03:41:54.000000Z"
    },
    {
      "id": 1,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:52.000000Z",
      "updated_at": "2020-08-09T03:41:52.000000Z"
    }
  ],
  "links": {
    "first": "http:\/\/freya.test\/api\/v1\/bans\/attempts?page=1",
    "last": "http:\/\/freya.test\/api\/v1\/bans\/attempts?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/freya.test\/api\/v1\/bans\/attempts",
    "per_page": 25,
    "to": 12,
    "total": 12
  }
}

Attempts can be omitted from bans by using the following value in the attributes of a ban: block_attempts this is more-so a way to stop people from spamming attempts, it will not hinder the alt tracker by disabling the recording of attempts We do recommend you create your own sort of rate limit for creating attempts however, blocking is a short-term solution.


GET /bans/attempt/{id}

This will return a single attempt by its ID. Pretty simple.

Request Payload: GET http://freya.test/api/v1/bans/attempt/1

Response: 200 OK

{
  "data": {
    "id": 1,
    "ban_id": 1,
    "steam_id": "76561198056377032",
    "ip": "69.240.201.21",
    "created_at": "2020-08-09T03:41:52.000000Z",
    "updated_at": "2020-08-09T03:41:52.000000Z"
  }
}

GET /bans/attempts/find

This will allow you to search through multiple attempts to get a specific one by the following inputs below. The response will be a collection of results paginated by 25.

Name Type Required Description
steam_id string SteamID of the attempt you're looking for.
ip string IP connected to the attempt you're looking for.

Request Payload: GET https://freya.test/api/v1/bans/attempts/find?steam_id=76561198056377032

Response: 200 OK

{
  "data": [
    {
      "id": 7,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:57.000000Z",
      "updated_at": "2020-08-09T03:41:57.000000Z"
    },
    {
      "id": 5,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:56.000000Z",
      "updated_at": "2020-08-09T03:41:56.000000Z"
    },
    {
      "id": 6,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:56.000000Z",
      "updated_at": "2020-08-09T03:41:56.000000Z"
    },
    {
      "id": 4,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:55.000000Z",
      "updated_at": "2020-08-09T03:41:55.000000Z"
    },
    {
      "id": 2,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:54.000000Z",
      "updated_at": "2020-08-09T03:41:54.000000Z"
    },
    {
      "id": 3,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:54.000000Z",
      "updated_at": "2020-08-09T03:41:54.000000Z"
    },
    {
      "id": 1,
      "ban_id": 1,
      "steam_id": "76561198056377032",
      "ip": "69.240.201.21",
      "created_at": "2020-08-09T03:41:52.000000Z",
      "updated_at": "2020-08-09T03:41:52.000000Z"
    }
  ],
  "links": {
    "first": "http:\/\/freya.test\/api\/v1\/bans\/attempts\/find?page=1",
    "last": "http:\/\/freya.test\/api\/v1\/bans\/attempts\/find?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "http:\/\/freya.test\/api\/v1\/bans\/attempts\/find",
    "per_page": 25,
    "to": 7,
    "total": 7
  }
}

POST /bans/attempts/create

You can use this API route to create an attempt for a user who is attempting to connect while banned.

If there is a steam_id present but no ban_id present it will look for the latest active ban to attach the attempt to. If it cannot find an active ban it'll return with a 400 Bad Method.

Name Type Required Description
ban_id int The ID of the ban the attempt is connected to.
steam_id string The SteamID of the user who is attempting to connect.
ip string The IP address of the user who is attempting to connect.

Request Payload: POST https://freya.test/api/v1/bans/attempts/create

{
    "steam_id": "76561198013448859",
    "ip": "69.240.201.21"
}

Response: 201 Created

{
  "data": {
    "ban_id": 2,
    "steam_id": "76561198013448859",
    "ip": "69.240.201.21",
    "updated_at": "2020-08-09T03:42:04.000000Z",
    "created_at": "2020-08-09T03:42:04.000000Z",
    "id": 12
  }
}

Note & Statuses before creating

If you do not specify a ban_id the attempt will go to the latest active ban, if it cannot find one it will fail with an error 400 Bad Request. A ban with block_attempts in the attributes will return a 423 Locked response indicating you cannot create the attempt due to the block_attempts flag on the ban.

The steam_id must also be on an actual ban, if the steam_id isn't present on any ban in the database it won't create.


PUT /bans/attempts/{id}/update

Updates a specific attempt by its ID. You can leave the fields you don't want to update out of the payload to keep them the same as they already are.

Name Type Required Description
ban_id int The ID of the ban the attempt is connected to.
steam_id string The SteamID of the user who is attempting to connect.
ip string The IP address of the user who is attempting to connect.

Request Payload: PUT https://freya.test/api/v1/bans/attempts/9/update

{
    "ip": "72.402.52.34"
}

Response: 200 OK

{
  "data": {
    "id": 1,
    "ban_id": 1,
    "steam_id": "76561198056377032",
    "ip": "72.402.52.34",
    "created_at": "2020-08-09T03:41:52.000000Z",
    "updated_at": "2020-08-09T03:54:33.000000Z"
  }
}

DELETE /bans/attempts/{id}/delete

This route will completely delete an attempt, it does not archive it, it just completely deletes it, forever gone unless you're a disk wizard and can recover deleted items.

Request Payload: DELETE https://freya.test/api/v1/bans/attempts/1/delete

Response: 200 OK

[]