> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Callout settings

> GET and POST /v1/callouts/settings: who may make callouts on your platform, whether they must hold the token, and the cooldown between two callouts of a user.

> [!NOTE]
>
> Callouts are switched on per instance on request. Contact us ([contact@cabalspy.xyz](mailto:contact@cabalspy.xyz)) to enable them. Without them every endpoint answers 403 [feature\_not\_enabled](https://docs.cabalspy.xyz/cabalspy-id/errors.md#feature_not_enabled).

Your instance's rules for [callouts](https://docs.cabalspy.xyz/cabalspy-id/callouts.md). They apply to every new callout from the moment you save them; existing callouts are not affected. You can also change them on the instance's [Callouts](https://docs.cabalspy.xyz/cabalspy-id/dashboard.md#callouts) tab in the dashboard.

| Setting | Values | Default | Effect |
| - | - | - | - |
| `who` | `all` or `kol_only` | `all` | `kol_only`: only users with the KOL badge can call, others get `kol_only`. |
| `require_holding` | `true` or `false` | `true` | The user must hold the token in one of their wallets that count on its chain, otherwise `not_a_holder`. |
| `cooldown_minutes` | 0 to 10,080 | 360 | Minutes between two callouts of the same user, on any token. 0 switches it off. Too early gets `callout_cooldown` with `Retry-After`. |

The rule that a user can call the same token only once per 24 hours always applies, whatever the settings.

## Read the settings

`GET /v1/callouts/settings`

Returns the current settings, or the defaults if you never changed them.

```bash cURL theme={null}
curl "https://api-id.cabalspy.xyz/v1/callouts/settings" \
  -H "Authorization: Bearer YOUR_KEY"
```

```python Python theme={null}
import requests

r = requests.get("https://api-id.cabalspy.xyz/v1/callouts/settings",
                 headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/callouts/settings", {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
console.log((await res.json()).data);
```

```json Response theme={null}
{
  "success": true,
  "data": { "who": "all", "require_holding": true, "cooldown_minutes": 360 },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-11-01T18:00:00Z" }
}
```

## Change the settings

`POST /v1/callouts/settings`

Send only the settings you want to change. The response contains all three settings as they are now.

### Body

**who** `string`

`all` or `kol_only`.

**require\_holding** `boolean`

`true` or `false`.

**cooldown\_minutes** `integer`

A whole number from 0 to 10,080 (7 days).

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

### Usage Example

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/callouts/settings" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"who": "kol_only", "cooldown_minutes": 60}'
```

```python Python theme={null}
import requests

r = requests.post("https://api-id.cabalspy.xyz/v1/callouts/settings",
                  json={"require_holding": False},
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/callouts/settings", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ cooldown_minutes: 0 }),
});
console.log((await res.json()).data);
```

```json Response theme={null}
{
  "success": true,
  "data": { "who": "kol_only", "require_holding": true, "cooldown_minutes": 60 },
  "meta": { "request_id": "req_5162c7cf7f87", "cached": false, "cache_age_seconds": 0, "version": "v1", "timestamp": "2026-11-01T18:00:00Z" }
}
```

### Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | invalid\_parameter | An unknown setting (`allowed` lists the known ones), or a value of the wrong type or out of range. `parameter` names it. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | [feature\_not\_enabled](https://docs.cabalspy.xyz/cabalspy-id/errors.md#feature_not_enabled) | Callouts are not switched on for your instance. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.