FiniAC Documentation

Appearance

API Version 3 ​

INFO

This is the documentation for the FiniAC Public API version 3. This version is the latest and is recommended for all new integrations.

Introduction ​

The FiniAC Public API is a RESTful API that allows you to interact with the Fini Anti-Cheat system. This API is designed to be simple and easy to use, with a focus on speed and reliability. The API is versioned to allow for changes and improvements over time, while maintaining backwards compatibility.

Getting Started ​

To get started with the FiniAC Public API, you will need to register for an API key. Once you have your API key, you can start making requests to the API.

Registering for an API Key ​

Currently to register for an API Key for the FiniAC Public API, you will need to contact us directly. We are working on a self-service registration system, but for now, please contact us to get started.

API Key Permissions ​

API keys are granted permissions based on the needs of the application using the API. When a permission for a specific endpoint is required, it will be listed in the endpoint's documentation. Calling the endpoint without the required permission will result in a 403 response and the name of the missing permission in the response message field.

Authentication ​

To authenticate with the API, you will need to include an access key and a secret key. The secret key will only be displayed once when the API token is refreshed.

API authentication examples:

http
GET /api/v3/keys/verify
Host: fini.dev
X-Fini-AccessKey: YOUR_ACCESS_KEY
X-Fini-SecretKey: YOUR_SECRET_KEY
bash
curl \
-X GET "https://fini.dev/api/v3/keys/verify" \
-H "X-Fini-AccessKey: YOUR_ACCESS_KEY" \
-H "X-Fini-SecretKey: YOUR_SECRET_KEY"
js
fetch("https://fini.dev/api/v3/keys/verify", {
  method: "GET",
  headers: {
    "X-Fini-AccessKey": "YOUR_ACCESS_KEY",
    "X-Fini-SecretKey": "YOUR_SECRET_KEY"
  }
})
js
axios.get("https://fini.dev/api/v3/keys/verify", {
  headers: {
    "X-Fini-AccessKey": "YOUR_ACCESS_KEY",
    "X-Fini-SecretKey": "YOUR_SECRET_KEY"
  }
})

Endpoints ​

API Keys ​

GET /api/v3/keys/verify ​

Purpose: The API key verification endpoint is used to verify that the API key is valid and has not been revoked.

Authentication: Requires a valid API Key.

Permissions

List of permissions that can be granted to an API key can be found here

ts
{
  success: boolean;
  info: {
    id: number;
    comment: string; // Optional comment [From FiniAC Staff]
    permissions: string; // Comma-separated list of permissions
    created_time: number; // Unix timestamp
    last_used: number; // Unix timestamp
    user: number; // User ID
    server_name: number; // Server name
    server_id: number; // Server ID
  }
}

Apollo ​

POST /api/v3/apollo/exec ​

Purpose: Executes a provided script within a defined server environment. Returns either the script's execution output or a token for retrieving the output later.

Authentication: Requires an API Key with the APOLLO.EXEC permission.

Input Parameters (Body)

json
{
  "script": "<string max 32kb>", // The script to execute
  "ip_addr": "<string formatted x.x.x.x>" // The IP address of the server to execute the script in
}

Responses

json
{
  "success": true,
  "message": "<string>", // Optional message
  "token": "<string>" // Used to retrieve the output later
}
json
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

GET /api/v3/apollo/return ​

Purpose: Retrieves the results of a previously executed script (where a token was provided).

Authentication: Requires an API Key with the APOLLO.EXEC permission.

Query Parameters

Responses

json
{
  "success": true,
  "value": "<string>" // The output of the script
}
json
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

Users ​

Purpose: Searches for users based on provided parameters like username, IP address, or Discord ID.

Authentication: Requires a valid API key with the USERS.SEARCH permission

Query Parameters

  • username (string, optional): The username to search for.
  • ipaddress (string, optional): The IP address to search for.
  • discord (string, optional): The Discord ID to search for.

Responses

json
{
  "success": true,
  "code": 200,
  "users": [
    {
      "id": 123,
      "username": "johndoe",
      "ip_addr": "127.0.0.1",
      "last_activity": 1679179153, // Example timestamp
      "created": 1676687521, // Example timestamp
      "discord_id": "123456789012345678",
      "servers": [
        {
          "id": 1,
          "name": "My Cool Server",
          "max_ips": 20,
          "last_connect": 1679175007, // Example timestamp
          "owner": 123 // User ID of owner
        }
        // ... other servers
      ]
    }
    // ... other matching users
  ]
}
json
// Emitted if no search parameters (username, ipaddress, or discord) are provided.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

Subscriptions ​

GET /api/v3/subscriptions/:subId/configs(?/:confId) ​

Purpose: This endpoint retrieves subscription configuration details.

Authentication: Requires a valid API key with the SUBSCRIPTIONS.CONFIGS permission.

URL Parameters

  • subId (number, required): Unique ID of the subscription.
  • confId (number, optional): Unique ID of a specific configuration to retrieve. If omitted, all configurations for the subscription are returned.

Responses

json
{
  "success": true,
  "code": 200,
  "configs": [
    {
      "id": "<number>",
      "subscription_id": "<number>",
      "value": "<array,string,number,object>",
      "name": "<string>",
      "name_friendly": "<string, readable>",
      "category": "<string>",
      "weight": "<number, float>",
      "type": "<string>",
      "default_value": "<array,string,number,object>",
      "required_feature_id": "<number>"
    }
    // More config objects if applicable...
  ]
}
json
// 400: Missing required parameters.
// 404: Subscription or specified configuration not found.
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

PUT /api/v3/subscriptions/:subId/configs/:confId ​

Purpose: This endpoint is designed to modify the value of an existing configuration within a specified subscription.

Authentication Requires a valid API key with the SUBSCRIPTIONS.CONFIGS permission.

Inputs

Request Body:

json
{
  "value": "<array,string,number,object>"
}

URL Parameters:

  • subId (string, required in URL): The unique identifier of the subscription that the configuration belongs to.
  • confId (string, required in URL): The unique identifier of the specific configuration you want to update.

Responses

json
{
  "success": true,
  "code": 200
}
json
// 400: Missing required parameters.
// 404: Subscription or specified configuration not found.
// 403: API key lacks necessary permissions.
{
  "success": false,
  "code": "<int>", // Error code
  "message": "<string>" // Optional message
}

Servers ​

Purpose: Searches for servers based on specified criteria (name or Discord user ID).

Authentication: Requires an API Key with the SERVERS.SEARCH permission.

Query Parameters

  • name (string, optional): The name of the server.
  • uid (number, optional): The Discord user ID associated with the server.

Responses

json
{
  "success": true,
  "code": 200,
  "servers": [
    {
      "id": 1,
      "name": "Test Server",
      "max_ips": 4,
      "owner": "John Doe",
      "users": [
        {
          /* User details */
        }
        /* (..more..) */
      ],
      "subscriptions": [
        {
          /* Subscription details */
        }
      ]
    }
    /* (..more..) */
  ]
}
json
// 400: Missing search parameters.
// 404: Servers not found with the provided criteria.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

Identities ​

POST /api/v3/identities/match ​

Purpose: This endpoint allows users to match multiple player identifiers to known player records within your system. This can be valuable for cross-referencing different player identification systems or for consolidating data.

Authentication:

This endpoint requires a valid API key with the permission BANS.MATCH.

Inputs

  • identifiers (array): A required array of player identifiers. Must be provided in the POST body. Each identifier should be an object with a type and a value property.

    Example identifiers array:

    json
    [
  { "type": "steam", "value": "76561199999999999" },
  { "type": "license", "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" },
  { "type": "ip", "value": "123.123.123.123" }
]

Limits: You may search for up to 5 identifiers in a single request.

Responses

json
{
  "success": true,
  "matches": [
    /* An array of player objects */
  ]
}
json
// 400: Missing required parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

Bans ​

GET /api/v3/bans/:uid ​

Purpose: Searches for bans associated with a license ID (uid).

Authentication: Requires a valid API key with the BANS.CHECK permission.

Optionally requires the BANS.CHECK.GLOBAL permission to view bans global bans (server_id = 0).

Optionally requires the BANS.DATE permission to view ban timestamps.

Optionally requires the BANS.REASON permission to view ban reasons.

Optionally requires the BANS.SEVERITY permission to view ban severity.

Parameters

URL Parameters:

  • uid (number, required): The license ID to check.

Responses

json
{
  "success": true,
  "code": 200,
  "bans": [
    {
      "id": "182475",
      "uid": "cf41abbb661b9f8c9fcbe3aa36f7178102e31c1d",
      "global": true,
      "created_by": "GLaDOS",
      "server_name": "Aperture Laboratories",
      "type": "fini",
      // Optional fields
      "time_unix": "1693351512", // Requires BANS.DATE permission
      "time_iso": "2023-08-29T23:25:12+00:00", // Requires BANS.DATE permission
      "reason": "Ban by detection logging, bad log: InvalidPedHealth\n\n{detection info as json}", // Requires BANS.REASON permission
      "severity": "high" // Requires BANS.SEVERITY permission
    }
    // ... other matching bans
  ]
}
json
// 400: Missing required parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

GET /api/v3/bans/check/discord ​

Purpose: Checks if a user is currently banned using their Discord ID. This endpoint returns truncated ban data, only containing uid and global. For more information about a ban, use the GET /api/v3/bans/:uid endpoint.

Authentication: Requires a valid API key with the BANS.CHECK permission.

Optionally requires the BANS.CHECK.GLOBAL permission to view bans global bans.

Optionally requires the BANS.DATE permission to view ban timestamps.

Optionally requires the BANS.REASON permission to view ban reasons.

Optionally requires the BANS.SEVERITY permission to view ban severity.

Input Parameters

  • discord (Required): The Discord ID to check.

Responses

json
{
  "success": true,
  "code": 200,
  "bans": [
    {
      "uid": "cf41abbb661b9f8c9fcbe3aa36f7178102e31c1d",
      "global": true
    }
    // Additional bans...
  ]
}
json
// 400: Missing required parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

POST /api/v3/bans/:uid ​

Purpose: Add a ban to the specified license ID (uid).

Authentication: Requires a valid API key with the BANS.ADD permission.

Additionally requires BANS.ADD.GLOBAL permission to add global bans.

Parameters

URL Parameters:

  • uid (number, required): The ban ID to update.

Body Parameters:

json
{
	"reason": "string", // The reason for the ban.
	"severity": "low" | "medium" | "high", // The severity of the ban.
	"server_id": "number" // (optioal) defaults to server_id from apikey, or 0 for global ban.
}

Responses

json
{
  "success": true,
  "code": 201,
  "message": "Ban created",
  "ban_id": "number" // The ID of the ban that was created.
}
json
// 400: Missing required parameters.
// 403: Forbidden (lacks necessary permissions).

{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

PUT /api/v3/bans/:banid ​

Purpose: Update a ban with the specified ID.

Authentication: Requires a valid API key with the BANS.EDIT permission.

Additionally requires BANS.EDIT.GLOBAL permission to alter global bans.

Parameters

URL Parameters:

  • banid (number, required): The ban ID to update.

WARNING

This endpoint uses the actual ban ID, not the license ID (uid). You must query the ban ID using the GET /api/v3/bans/:uid endpoint first.

Body Parameters:

json
{
	"reason": "string", // The reason for the ban.
	"severity": "low" | "medium" | "high", // The severity of the ban.
	"unbanned": true | false, // Unbans the ban if true.
	"server_id": "number" // Changing this to 0 will make the ban global.
}

:::

Responses

json
{
  "success": true,
  "code": 200,
  "message": "Ban updated"
}
json
// 400: Missing required parameters.
// 403: Forbidden (lacks necessary permissions).
// 404: Ban not found.

{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

GET /api/v3/bans/list ​

Purpose: Returns an abridged paginated list of all bans in the system for the authorised server. A maximum of 1000 bans can be returned at once. Use the GET /api/v3/bans/search endpoint for more advanced filtering.

Authentication: Requires a valid API key with the BANS.CHECK permission.

Input Parameters

  • page (Required): The page number to retrieve (starting from 1). [Default: 1].
  • count (Required): The number of bans to retrieve per page (maximum 1000) [Default: 100].
  • sort (Required): The sort order for the results by timestamp (either "ASC" or "DESC"). [Default: "ASC"].

Responses

json
{
  "success": true,
  "code": 200,
  "bans": [
    {
      "id": "424321",
      "uid": "cf41abbb661b9f8c9fcbe3aa36f7178102e31c1d",
      "server_id": "0", // 0 for global bans, otherwise the server ID
      "original_server_id": "1234",
      "time_unix": 1700000000, // Timestamp of when the ban was created
      "time_iso": "2023-11-14T12:00:00Z" // ISO 8601 format of the timestamp
    }
    // Additional bans... (up to 1000)
  ]
}
json
// 400: Missing required parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

Whitelist ​

GET /api/v3/whitelist/list ​

Purpose: Retrieve a paginated list of whitelist requests for your server.

Authentication: Requires a valid API key with the WHITELIST.READ permission.

Optionally requires the WHITELIST.READ.ALL permission to view whitelist requests from all servers.

Parameters

Query Parameters:

  • page (number, optional): Page number for pagination. Defaults to 1.
  • page_size (number, optional): Number of results per page. Defaults to 25, maximum 100.
  • status (string, optional): Filter by status. Valid values: new, accepted, rejected, removed.
  • search (string, optional): Search in player_uid, reason, or admittance fields.

Responses

json
{
  "success": true,
  "code": 200,
  "requests": [
    {
      "id": 123,
      "player_uid": "cf41abbb661b9f8c9fcbe3aa36f7178102e31c1d",
      "reason": "Player was falsely detected for InvalidPedHealth",
      "admittance": "Player was lagging and appeared to have invalid health values",
      "response": "Reviewed and approved", // May be empty
      "status": "accepted", // One of: new, accepted, rejected, removed
      "submitter_name": "AdminUser",
      "reviewer_name": "ReviewerUser", // May be null if not reviewed yet
      "server_name": "My FiveM Server",
      "server_id": 42,
      "time_created_unix": 1693351512,
      "time_created_iso": "2023-08-29T23:25:12+00:00",
      "time_updated_unix": 1693358712,
      "time_updated_iso": "2023-08-30T01:25:12+00:00"
    }
    // ... other whitelist requests
  ],
  "pages": {
    "current": 1,
    "total": 5
  }
}
json
// 400: Invalid parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

GET /api/v3/whitelist/:id ​

Purpose: Retrieve details of a specific whitelist request by its ID.

Authentication: Requires a valid API key with the WHITELIST.READ permission.

Optionally requires the WHITELIST.READ.ALL permission to view whitelist requests from other servers.

Parameters

URL Parameters:

  • id (number, required): The whitelist request ID.

Responses

json
{
  "success": true,
  "code": 200,
  "request": {
    "id": 123,
    "player_uid": "cf41abbb661b9f8c9fcbe3aa36f7178102e31c1d",
    "reason": "Player was falsely detected for InvalidPedHealth",
    "admittance": "Player was lagging and appeared to have invalid health values",
    "response": "Reviewed and approved", // May be empty
    "status": "accepted", // One of: new, accepted, rejected, removed
    "submitter_name": "AdminUser",
    "reviewer_name": "ReviewerUser", // May be null if not reviewed yet
    "server_name": "My FiveM Server",
    "server_id": 42,
    "time_created_unix": 1693351512,
    "time_created_iso": "2023-08-29T23:25:12+00:00",
    "time_updated_unix": 1693358712,
    "time_updated_iso": "2023-08-30T01:25:12+00:00"
  }
}
json
// 400: Invalid request URI.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions or request belongs to another server).
// 404: Whitelist request not found.
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message
}

POST /api/v3/whitelist/add ​

Purpose: Create a new whitelist request for a globally banned player.

Authentication: Requires a valid API key with the WHITELIST.WRITE permission.

Parameters

Body Parameters:

json
{
  "player_uid": "string", // Required. The 40-character hexadecimal license ID of the player.
  "reason": "string", // Required. The reason why the player was banned.
  "admittance": "string" // Required. Additional context or justification for the whitelist request.
}

Validation Rules:

  • player_uid must be a 40-character hexadecimal string (SHA-1 format)
  • Player must have exactly one active global ban (server_id = 0)
  • Players with multiple global bans (blacklisted) cannot be whitelisted
  • Player cannot already have an active (new or accepted) whitelist request for the same server

Responses

json
{
  "success": true,
  "code": 201,
  "message": "Whitelist request created",
  "request_id": 123 // The ID of the created whitelist request
}
json
// 400: Missing or invalid parameters, or player is not globally banned.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions).
// 409: Conflict - player already has an active whitelist request or is whitelisted.
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message (e.g., "Player is not globally banned", "Invalid player_uid format")
}

PUT /api/v3/whitelist/:id ​

Purpose: Update the status of a whitelist request. Regular users can only remove requests, while reviewers can accept or reject them.

Authentication: Requires a valid API key with the WHITELIST.WRITE permission.

Additionally requires the WHITELIST.REVIEW permission to set status to accepted or rejected.

Optionally requires the WHITELIST.WRITE.ALL permission to update whitelist requests from other servers.

Parameters

URL Parameters:

  • id (number, required): The whitelist request ID to update.

Body Parameters:

json
{
  "status": "accepted" | "rejected" | "removed", // Required. The new status for the request.
  "response": "string" // Optional. A message explaining the decision (typically used when accepting/rejecting).
}

Permission Requirements:

StatusRequired PermissionDescription
removedWHITELIST.WRITEAnyone with write access can remove a request
acceptedWHITELIST.REVIEWOnly reviewers can accept whitelist requests
rejectedWHITELIST.REVIEWOnly reviewers can reject whitelist requests

INFO

When a whitelist request is set to accepted, the system automatically pushes updated configs to the game server via Apollo.

Responses

json
{
  "success": true,
  "code": 200,
  "message": "Whitelist request updated"
}
json
// 400: Missing or invalid parameters.
// 401: Unauthorized (invalid API key).
// 403: Forbidden (lacks necessary permissions, e.g., trying to accept/reject without WHITELIST.REVIEW).
// 404: Whitelist request not found.
// 429: Rate limit exceeded.
{
  "success": false,
  "code": "<number>", // Error code
  "message": "<string>" // Error message (e.g., "You need the 'WHITELIST.REVIEW' permission to accept or reject whitelist requests")
}