API Documentation

Integrate PAKKT into your tools and panels. API key authentication, JSON responses.

Quick reference

Base URL: https://api.pakkt.io/api/v1
Authentication: X-API-Key header
Rate limit: 60 req/min per key

1. Authentication

All requests must include your API key in the X-API-Key header.

curl https://api.pakkt.io/api/v1/agents \
  -H "X-API-Key: pakkt_pub_YOUR_KEY"

API keys can be generated from the panel (API Keys).
Rate limit: 60 requests / minute per key.
The key is only displayed once at creation. Store it securely.

2. Agents

List and view agents connected to your account.

`GET` /agents

List all your agents.

Response

[
  {
    "id": "01J5...",
    "name": "VPS Paris",
    "hostname": "debian",
    "iface": "ens3",
    "version": "a1b2c3d",
    "status": "online",
    "last_seen_at": "2026-03-16T12:00:00Z",
    "created_at": "2026-03-01T10:00:00Z"
  }
]

`GET` /agents/:id

Agent details.

Response

{
  "id": "01J5...",
  "name": "VPS Paris",
  "hostname": "debian",
  "iface": "ens3",
  "version": "a1b2c3d",
  "status": "online",
  "last_seen_at": "2026-03-16T12:00:00Z",
  "created_at": "2026-03-01T10:00:00Z"
}

3. XDP Rules (PAKKT Engine)

Create and manage XDP protection rules via the PAKKT Engine. Each rule is a slot in the XDP engine (max 256 per interface), with no network reload required.

`GET` /agents/:id/programs

List all XDP rules for an agent.

Response

[
  {
    "id": "01J6...",
    "name": "Anti-Flood FiveM",
    "filename": "pakkt_engine.bpf.o",
    "iface": "ens3",
    "port_range_start": 30120,
    "port_range_end": 30120,
    "protocol": 17,
    "rule_type": 1,
    "max_pps": 5000,
    "status": "loaded",
    "loaded_at": "2026-03-15T08:00:00Z"
  }
]

`POST` /agents/:id/engine-rules

Create a PAKKT Engine rule on an agent.

Body

{
  "name": "Rate Limit SSH",
  "port_range_start": 22,
  "port_range_end": 22,
  "protocol": 6,
  "rule_type": 1,
  "max_pps": 500,
  "max_port_pps": 0,
  "min_pkt_size": 0,
  "max_pkt_size": 0
}

Response

{
  "id": "01J7...",
  "name": "Rate Limit SSH",
  "status": "pending_load",
  "created_at": "2026-03-16T12:30:00Z"
}

protocol: 0 (any), 6 (TCP), 17 (UDP), 1 (ICMP)
rule_type: 0 (block), 1 (rate_limit), 2 (allow_only)
max_pps: packets/second per source IP (0 = disabled)
max_port_pps: global packets/second on the port (0 = disabled)
Interface is auto-detected from the agent, no need to specify it
Dedup: returns 409 if an active rule already exists on the same port range

`DELETE` /agents/:id/programs/:prog_id

Unload an XDP rule.

Response

204 No Content

4. IP Whitelist / Blacklist

Manage IP whitelists and blacklists per agent. Entries are synced via heartbeat and applied at the XDP (kernel) level.

`GET` /agents/:id/ip-list

List IP entries for an agent.

Query parameters

type: blacklist or whitelist (optional, returns all if omitted) — example: blacklist

Response

[
  {
    "id": "01K2...",
    "list_type": "blacklist",
    "ip_address": "203.0.113.42",
    "reason": "UDP flood detected",
    "status": "active",
    "expires_at": "2026-03-17T12:00:00Z",
    "created_at": "2026-03-16T12:00:00Z"
  }
]

`POST` /agents/:id/ip-list

Add an IP to the whitelist or blacklist.

Body

{
  "list_type": "blacklist",
  "ip_address": "203.0.113.42",
  "reason": "UDP flood detected",
  "expires_at": "2026-03-17T12:00:00Z"
}

Response

{
  "id": "01K2...",
  "status": "pending_add",
  "created_at": "2026-03-16T12:00:00Z"
}

list_type: blacklist or whitelist
expires_at: ISO 8601 (optional, blacklist only, null = permanent)
Initial status: pending_add -> active after agent confirmation

`DELETE` /agents/:id/ip-list/:entry_id

Remove an IP entry.

Response

204 No Content

Transitions to pending_remove then deleted after agent confirmation

5. Metrics

Access traffic metrics for your agents: real-time summary or historical data.

`GET` /metrics/:agent_id/summary

Metrics summary over a time window.

Query parameters

window: 10m, 1h, or 24h (default: 1h) — example: 24h

Response

{
  "total_passed": "142857",
  "total_dropped": "4821",
  "total_bytes_passed": "89421300",
  "total_bytes_dropped": "2890400",
  "top_ports": [
    {
      "port": 30120,
      "packets_passed": "85420",
      "packets_dropped": "3200",
      "bytes_passed": "54128000",
      "bytes_dropped": "1920000"
    }
  ]
}

`GET` /metrics/:agent_id

Historical metrics with time buckets.

Query parameters

from: ISO start date (default: 24h) — example: 2026-03-15T00:00:00Z
to: ISO end date (default: now) — example: 2026-03-16T00:00:00Z
interval: 1m, 5m, or 1h (default: 1m) — example: 5m
port: Filter by port (optional) — example: 30120

Response

[
  {
    "bucket": "2026-03-16T12:00:00Z",
    "port": 30120,
    "packets_passed": "8542",
    "packets_dropped": "124",
    "bytes_passed": "5412800",
    "bytes_dropped": "67200"
  }
]

6. Marketplace

Retrieve PAKKT-validated protection templates, filterable by category.

`GET` /marketplace/templates

List marketplace templates.

Query parameters

category: Filter by category (optional) — example: Gaming

Response

[
  {
    "id": "tpl_fivem_shield",
    "title": "FiveM Shield",
    "description": "UDP anti-flood protection for FiveM",
    "type": "xdp",
    "category": "Gaming",
    "filename": "pakkt_engine.bpf.o",
    "protocol": 17,
    "rule_type": 1,
    "port_range_start": 30120,
    "port_range_end": 30130,
    "max_pps": 5000,
    "risk": "low"
  }
]

nftables templates include an nft field with chain, protocol, action, etc.
Categories: Gaming, Web, Infrastructure, Database

7. nftables Firewall

Manage nftables rules (stateful firewall) for your agents.

`GET` /agents/:id/firewall

List nftables rules for an agent.

Response

[
  {
    "id": "01K8...",
    "name": "Anti brute-force SSH",
    "chain": "input",
    "protocol": "tcp",
    "port_start": 22,
    "port_end": 22,
    "action": "limit",
    "limit_rate": 5,
    "limit_unit": "minute",
    "conntrack": "new",
    "status": "active",
    "is_system": false,
    "packets_total": 4821,
    "bytes_total": 289260
  }
]

`POST` /agents/:id/firewall

Create an nftables rule.

Body

{
  "name": "Block Redis",
  "chain": "input",
  "protocol": "tcp",
  "port_start": 6379,
  "port_end": 6379,
  "action": "drop"
}

Response

{
  "id": "01K9...",
  "name": "Block Redis",
  "status": "pending_add",
  "created_at": "2026-03-16T15:00:00Z"
}

chain: input (default), forward, or output
action: drop, accept, reject, or limit
limit requires limit_rate and limit_unit (second or minute)
conntrack: new, established, related (or CSV combination)
System rules (is_system: true) cannot be deleted

`DELETE` /agents/:id/firewall/:rule_id

Delete an nftables rule.

Response

204 No Content

8. Errors

The API returns standard HTTP codes with a JSON body.

Code	Description
`400`	Invalid request (missing or incorrect parameters)
`401`	Missing or invalid API key
`402`	Account suspended (overdue payment)
`404`	Resource not found
`409`	Conflict (e.g., active rule already exists on this port range)
`422`	Validation failed (e.g., agent not yet connected, invalid ports)
`429`	Rate limit reached (60 req/min per key)
`500`	Internal error

APIDocumentation

Quick reference

1. Authentication

2. Agents

GET /agents

Response

GET /agents/:id

Response

3. XDP Rules (PAKKT Engine)

GET /agents/:id/programs

Response

POST /agents/:id/engine-rules

Body

Response

DELETE /agents/:id/programs/:prog_id

Response

4. IP Whitelist / Blacklist

GET /agents/:id/ip-list

Query parameters

Response

POST /agents/:id/ip-list

Body

Response

DELETE /agents/:id/ip-list/:entry_id

Response

5. Metrics

GET /metrics/:agent_id/summary

Query parameters

Response

GET /metrics/:agent_id

Query parameters

Response

6. Marketplace

GET /marketplace/templates

Query parameters

Response

7. nftables Firewall

GET /agents/:id/firewall

Response

POST /agents/:id/firewall

Body

Response

DELETE /agents/:id/firewall/:rule_id

Response

8. Errors

API
Documentation

`GET` /agents

`GET` /agents/:id

`GET` /agents/:id/programs

`POST` /agents/:id/engine-rules

`DELETE` /agents/:id/programs/:prog_id

`GET` /agents/:id/ip-list

`POST` /agents/:id/ip-list

`DELETE` /agents/:id/ip-list/:entry_id

`GET` /metrics/:agent_id/summary

`GET` /metrics/:agent_id

`GET` /marketplace/templates

`GET` /agents/:id/firewall

`POST` /agents/:id/firewall

`DELETE` /agents/:id/firewall/:rule_id