Plugins API — Counter-Strike Boost Developers

Overview #

Three endpoints, and a panel integration only really needs two of them: list what is available, then download what the user picked.

GET	`/v1/plugins`	Paginated, searchable, filterable directory
GET	`/v1/plugins/{slug}`	One plugin: versions, files, download URLs
GET	`/v1/plugins/{slug}/download/{version}`	The file itself

Nothing is pre-built

We store plugin source only — not a single .amxx binary exists on our disks. Every kind=amxx request runs the AMX Mod X compiler on the spot. That is why those requests carry their own hourly budget, why a bad plugin can return 422 compile_failed with real compiler output, and why you should cache what you download.

List plugins #

GET /v1/plugins plugins:read auth optional

The directory. Paginated, sorted by all-time downloads descending, and filterable by category or free-text search. Only published plugins appear.

Parameters

q string optional

Free-text search over plugin name and tags (substring match, case-insensitive). Not a description search. Truncated to 100 characters.

category string optional

Exact category slug. Valid values come from /v1/meta → plugin_categories. An unknown category is not an error — it simply matches nothing.

page_n integer default 1

1-based page number, clamped to 1–100000.

per_page integer default 24

Items per page, clamped to 1–100.

Response fields

Field	Type	Notes
`slug`	string	Stable identifier. Use it everywhere.
`author`	string	The original author, credited as upstream published it. May be empty.
`license`	string	SPDX-ish identifier. Plugins are GPL with source included — show this to your users.
`latest_version`	string	Newest published version string, or `""` if the plugin has no published version yet. Feed this straight into the download path.
`rating`	object	`{ avg, count }`. `avg` is `0` when `count` is `0` — do not render it as a real zero-star score.
`downloads`	integer	All-time downloads across every version and kind.
`detail_url / page_url`	string	Absolute API detail URL, and the human-facing page on the website. Link the latter from your panel.

total_pages is derived from the filtered total, so it changes with q and category. Paging past the end returns an empty plugins array with 200, not a 404.

Request

cURL

curl "https://api.counter-strike-boost.com/v1/plugins?category=admin&per_page=2"

JavaScript

const res  = await fetch(
  "https://api.counter-strike-boost.com/v1/plugins?category=admin&per_page=2"
);
const data = await res.json();

if (!data.status) {
  throw new Error(data.error);   // stable machine-readable code
}

PHP

<?php
$body = file_get_contents(
    "https://api.counter-strike-boost.com/v1/plugins?category=admin&per_page=2"
);
$data = json_decode($body, true);

if (empty($data['status'])) {
    throw new RuntimeException($data['error'] ?? 'request_failed');
}

Python

import requests

r = requests.get(
    "https://api.counter-strike-boost.com/v1/plugins?category=admin&per_page=2",
    timeout=30,
)
r.raise_for_status()
data = r.json()

Response 200 OK

200 OK

{
  "page": 1,
  "per_page": 2,
  "plugins": [
    {
      "author": "counter-strike-boost.com",
      "category": "hud-info",
      "detail_url": "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts",
      "downloads": 174,
      "latest_version": "1.0.0",
      "license": "GPL-3.0",
      "name": "CSB Server Adverts",
      "page_url": "https://counter-strike-boost.com/plugins/csb-server-adverts",
      "rating": { "avg": 0, "count": 0 },
      "slug": "csb-server-adverts",
      "updated_at": "2026-07-31 14:20:24"
    },
    {
      "author": "Nomexous (High Ping Kicker)",
      "category": "admin",
      "detail_url": "https://api.counter-strike-boost.com/v1/plugins/csb-high-ping-kicker",
      "downloads": 138,
      "latest_version": "1.0.0",
      "license": "GPL-3.0",
      "name": "CSB High Ping Kicker",
      "page_url": "https://counter-strike-boost.com/plugins/csb-high-ping-kicker",
      "rating": { "avg": 0, "count": 0 },
      "slug": "csb-high-ping-kicker",
      "updated_at": "2026-07-31 16:25:09"
    }
  ],
  "status": true,
  "total": 236,
  "total_pages": 118
}

Get a plugin #

GET /v1/plugins/{slug} plugins:read auth optional

Full detail for one plugin: tags, upstream credit, and every published version with its complete file manifest and ready-made download URLs. This is the call that populates a plugin page or an install dialog.

Parameters

slug string path required

Plugin slug, e.g. csb-server-adverts.

Response fields

Field	Type	Notes
`tags`	string[]	Already split and trimmed for you. Empty array if the plugin has none.
`original_url`	string	Upstream source (forum thread, repo) where the plugin came from. `""` for plugins written by us.
`versions`	object[]	Newest first. Each entry is self-contained: version string, creation date, file manifest and download URLs.
`versions[].files[].install_dir`	string	Where the file belongs, relative to `cstrike/`. This is what makes a one-click install possible — drop each file into its own `install_dir`, do not dump everything in one folder.
`versions[].files[].is_primary`	bool	The main `.sma`. It is the compile entry point, and what `kind=sma` returns.
`versions[].files[].sha1`	string	Checksum of the stored source file. Use it to skip re-downloading unchanged files.
`versions[].downloads`	object	URL per kind. Always contains `amxx` and `zip`, plus one entry per distinct file kind in that version.

Only three kinds are downloadable

The downloads map is built from the version's file kinds, so it can contain keys such as ini or cfg. The download endpoint accepts only amxx, sma and zip — any other kind returns 400 invalid_kind. Use downloads.zip when you need the config files too; it contains the whole version.

Request

cURL

curl "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts"

JavaScript

const res  = await fetch(
  "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts"
);
const data = await res.json();

if (!data.status) {
  throw new Error(data.error);   // stable machine-readable code
}

PHP

<?php
$body = file_get_contents(
    "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts"
);
$data = json_decode($body, true);

if (empty($data['status'])) {
    throw new RuntimeException($data['error'] ?? 'request_failed');
}

Python

import requests

r = requests.get(
    "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts",
    timeout=30,
)
r.raise_for_status()
data = r.json()

Response

200 OK

{
  "plugin": {
    "author": "counter-strike-boost.com",
    "category": "hud-info",
    "downloads": 174,
    "license": "GPL-3.0",
    "name": "CSB Server Adverts",
    "original_url": "",
    "page_url": "https://counter-strike-boost.com/plugins/csb-server-adverts",
    "rating": { "avg": 0, "count": 0 },
    "slug": "csb-server-adverts",
    "tags": ["adverts", "announcements", "chat", "amxmodx", "hud"],
    "updated_at": "2026-07-31 14:20:24",
    "versions": [
      {
        "created_at": "2025-05-20 19:19:16",
        "downloads": {
          "amxx": "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=amxx",
          "ini":  "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=ini",
          "sma":  "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=sma",
          "zip":  "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=zip"
        },
        "files": [
          {
            "filename": "adverts.sma",
            "install_dir": "addons/amxmodx/scripting",
            "is_primary": true,
            "kind": "sma",
            "sha1": "83f9598ceb9c8fcbe75f96251fdcbce5124d56c2",
            "size_bytes": 2910
          },
          {
            "filename": "csb_adverts.ini",
            "install_dir": "addons/amxmodx/configs",
            "is_primary": false,
            "kind": "ini",
            "sha1": "8fe22baf3971b0ce5e48b6612322aa4ab620789d",
            "size_bytes": 384
          }
        ],
        "version": "1.0.0"
      }
    ]
  },
  "status": true
}

404 Not Found

{
  "error": "not_found",
  "status": false
}

Download a plugin #

GET /v1/plugins/{slug}/download/{version} plugins:read auth optional

Returns the file itself, not JSON. This is the "Install" button: pick a kind, get bytes, write them to disk.

Parameters

slug string path required

Plugin slug.

version string path required

Exact published version string, e.g. 1.0.0. There is no latest alias — read latest_version from the list or detail call first.

kind enum default amxx

amxx — freshly compiled binary. sma — the primary source file. zip — the entire version as an archive (source, configs, compiled binary). Anything else is 400 invalid_kind.

amxx enum default plugin's own

Pin the AMX Mod X toolchain: 1.8.2, 1.9 or 1.10. Affects amxx and zip. An invalid value is silently ignored and the plugin default is used — it never fails the request.

Errors

Status	error	When
400	`invalid_kind`	`kind` was not one of `amxx`, `sma`, `zip`. Body lists `allowed`.
404	`not_found`	No such plugin/version, it is unpublished, or it has no files.
404	`no_source_file`	`kind=sma` on a version with no source file.
422	`no_compilable_source`	The version contains no `.sma` to compile. A data problem on our side — report it.
422	`compile_failed`	The compiler rejected the source. Body carries `toolchain` and up to 4000 characters of `output`. Retrying will not help; try a different `amxx` toolchain, or show the output to the user.
429	`rate_limited`	Compile budget exhausted (per-IP hourly, or the site-wide flood brake). Honour `Retry-After`.
502	`compiler_unavailable`	The compiler service is momentarily down. Transient — retry shortly.
502	`zip_failed`	The archive could not be assembled. Transient — retry shortly.

Distinguish the two 502-ish failures from the 422. compile_failed is deterministic — the source is broken and every retry produces the same error, so surface it and stop. compiler_unavailable and zip_failed are infrastructure; back off and retry.

Every download is counted and logged (slug, version, kind, toolchain, caller IP, result and compile duration). Cache aggressively on your side: repeatedly recompiling the same plugin costs you your hourly budget and costs us CPU.

Request

cURL

# -OJ writes the file under the name the server sends
curl -OJ "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=amxx&amxx=1.10"

JavaScript

const res = await fetch(
  "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=amxx&amxx=1.10"
);

if (!res.ok) {
  const err = await res.json();   // { status: false, error: "..." }
  throw new Error(err.error);
}

await writeFile("plugin.amxx", Buffer.from(await res.arrayBuffer()));

PHP

<?php
$ch = curl_init("https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=amxx&amxx=1.10");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code !== 200) {
    $err = json_decode($body, true);
    throw new RuntimeException($err['error'] ?? 'request_failed');
}

file_put_contents("plugin.amxx", $body);

Python

import requests

r = requests.get(
    "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=amxx&amxx=1.10",
    timeout=600,          # a cold server build can take minutes
)
r.raise_for_status()

with open("plugin.amxx", "wb") as f:
    f.write(r.content)

Response

The response body is the file. Headers on a successful kind=amxx download:

`content-type`	`application/octet-stream`
`content-disposition`	`attachment; filename="csb-server-adverts-1.0.0.amxx"`
`cache-control`	`no-store`
`x-content-type-options`	`nosniff`

kind	Content-Type	Filename
`amxx`	`application/octet-stream`	`{slug}-{version}.amxx`
`sma`	`text/plain; charset=UTF-8`	`the source filename, e.g. adverts.sma`
`zip`	`application/zip`	`{slug}-{version}.zip`

422 compile_failed

{
  "error": "compile_failed",
  "output": "adverts.sma(41) : error 017: undefined symbol \"get_user_nam\"\n\n1 Error.\nCompilation aborted.",
  "status": false,
  "toolchain": "1.10"
}

400 invalid_kind

{
  "allowed": ["amxx", "sma", "zip"],
  "error": "invalid_kind",
  "status": false
}

Recipe: one-click install #

The full flow a game panel implements — browse, resolve the version, install every file into its right directory.

1. Show the directory

BASH

curl "https://api.counter-strike-boost.com/v1/plugins?per_page=20"

2. User picks one — read its versions and file manifest

BASH

curl "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts"

3. Install: compiled binary into scripting's sibling, configs into configs

BASH

# the compiled plugin -> cstrike/addons/amxmodx/plugins/
curl -OJ "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=amxx"

# or grab everything at once, already laid out by install_dir
curl -OJ "https://api.counter-strike-boost.com/v1/plugins/csb-server-adverts/download/1.0.0?kind=zip"

4. Register it

BASH

# append the plugin filename to cstrike/addons/amxmodx/configs/plugins.ini
echo "csb-server-adverts-1.0.0.amxx" >> cstrike/addons/amxmodx/configs/plugins.ini

Prefer kind=zip when a plugin ships config files: the archive already respects each file's install_dir, so you can unpack it over cstrike/ and be done.