# SEO tools

The SEO tools suite: every tool, your subscription, and prices with the bundle and yearly discounts.

## List the SEO tools

`GET /seo/tools` · scope `seo:read`

Every SEO tool, whether it needs hosting, whether your account has it, its plans and pack (prices per month before VAT, from the live price rows), and the current bundle and yearly discounts.

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/seo/tools" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/seo/tools", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/seo/tools", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "tools": [
      {
        "key": "rank",
        "name": "Rank tracking",
        "standalone": true,
        "active": true,
        "url": "https://app.pbn.ltd/rank/",
        "plans": [
          {
            "key": "starter",
            "name": "Starter",
            "price_usd": "5.00",
            "summary": "..."
          }
        ],
        "pack": null
      }
    ],
    "discounts": {
      "bundle_min_tools": 3,
      "bundle_percent": "20",
      "annual_months": 12,
      "annual_percent": "16.67"
    }
  }
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## Your SEO tools subscription

`GET /seo/subscription` · scope `seo:read`

What your SEO tools order covers today (tools, plans, period, discounts) and the next period if it is already paid. Tools bought on their own (not through the SEO checkout) are listed by seo.tools.

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/seo/subscription" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/seo/subscription", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/seo/subscription", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "active": true,
    "paid_until": "2027-09-22",
    "order": {
      "ref": "seo1:...",
      "months": 12,
      "start": "2026-09-22",
      "end": "2027-09-22",
      "bundle_percent": "20",
      "annual_percent": "16.67",
      "tools": [
        {
          "tool": "rank",
          "plan": "Pro",
          "packs": 0
        }
      ]
    },
    "next_order": null
  }
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## Price a selection of SEO tools

`POST /seo/quote` · scope `seo:read`

The exact price the checkout would charge for a NEW order of these tools (before any existing subscription is taken into account), VAT for your account included. Nothing is stored.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `tools` | body | array | yes | [{"tool": "rank", "plan": "pro", "packs": 0}, ...] - keys from seo.tools. |
| `months` | body | integer | no | 1, 3, 6 or 12. Default: `1`. |

### Example

```bash
curl -s -X POST "https://app.pbn.ltd/api/v1/seo/quote" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.post("https://app.pbn.ltd/api/v1/seo/quote", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/seo/quote", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "tools": 3,
    "months": 12,
    "monthly_list": "45.00",
    "list": "540.00",
    "bundle_percent": "20",
    "bundle": "108.00",
    "annual_percent": "16.67",
    "annual": "72.01",
    "net": "359.99",
    "vat_percent": "0.00",
    "vat": "0.00",
    "charge": "359.99",
    "hint": ""
  }
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`, `validation_failed`