Getting started in five minutes

1. Create a key

Dashboard, Account > API keys, Create key.

1. Name it after whatever will use it: backup-cron, status-board. 64 characters at most, no < or >.
2. Tick the permissions. For this run: account:read, services:read, services.metrics:read.
3. Leave the rest at their defaults: all services, any address, no expiry.
4. Confirm it is you: two-factor code, password, or a code sent by email, depending on what your account carries.

The secret is shown once: fpk_ followed by 43 characters. Copy it. Nobody can read it back; if you lose it, rotate the key.

2. Make a first call

export FRESHPERF_KEY="fpk_9al41uPRzeglnYvHa3YfvsK86OfQwx6BmC2EKmI0Vhw"

curl -H "Authorization: Bearer $FRESHPERF_KEY" \
     https://api.freshperf.fr/v1/me

{
  "data": {
    "account": {
      "id": 1234,
      "email": "[email protected]",
      "firstName": "Alex",
      "lastName": "Martin",
      "company": false,
      "companyName": null,
      "country": "FR",
      "createdAt": 1785104280762,
      "emailVerified": true,
      "twoFactorEnabled": true
    },
    "key": {
      "id": 2,
      "label": "status-board",
      "keyPrefix": "fpk_9al41uPR",
      "scopes": ["account:read", "services:read", "services.metrics:read"],
      "allServices": true,
      "serviceCodes": [],
      "ipAllowlist": [],
      "expiresAt": null,
      "spendingCapCents": null,
      "spendingRemainingCents": null
    }
  }
}

GET /me says who the key acts for and what it carries. It is the first call to make when a script misbehaves. The full field contract is in Tickets, SSH keys and account.

3. List your services

curl -H "Authorization: Bearer $FRESHPERF_KEY" \
     "https://api.freshperf.fr/v1/services?limit=5"

{
  "data": [
    {
      "code": "SRV-TJUAQ1-1951",
      "name": "Minecraft 1",
      "customName": null,
      "productShortname": "minecraft-1",
      "productTitle": "Minecraft 1",
      "category": "minecraft",
      "status": "ACTIVE",
      "providerType": "pterodactyl",
      "autoRenew": true,
      "nextBillingAt": 1789437385056,
      "recurrence": "monthly",
      "createdAt": 1786845385066,
      "activatedAt": 1786845385056
    }
  ],
  "pagination": { "nextCursor": null, "limit": 5 }
}

The code is the identifier every service route takes.

curl -H "Authorization: Bearer $FRESHPERF_KEY" \
     https://api.freshperf.fr/v1/services/SRV-TJUAQ1-1951/status

{
  "data": {
    "status": "running",
    "uptimeSeconds": 1450617,
    "cpu": 0.01823,
    "memoryBytes": 906903552,
    "memoryMaxBytes": 2147483648,
    "ipv4": "203.0.113.32:20018"
  }
}

4. Act on it

Acting needs a write permission. Edit the key, add services.power:write, save, then:

curl -X POST \
     -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -d '{"action": "restart"}' \
     https://api.freshperf.fr/v1/services/SRV-TJUAQ1-1951/power

{ "data": { "status": "SUCCESS", "message": "Power signal accepted" } }

PENDING instead of SUCCESS means the infrastructure is still working on it: read /status again a few seconds later.

5. Check the log

Reopen the key under Account > API keys. Every call you just made is there with its route, status, address, duration and X-Request-Id. Refusals too.

Next