Getting started with the API

What the API does, who can use it, its address, how to get a key, and a first call in curl, Python and Node.js.

In the appOrganisationAPI

The Cerberius API gives your own systems three checks:

Check	What it tells you
IP lookup `POST /ip-lookup`	Where an IP address is, who runs its network, and whether it's a VPN, proxy or Tor exit, or on a block list.
Email check `POST /email-lookup`	Whether an email address can receive mail, and whether it's a throwaway, free or shared address.
Prompt check `POST /prompt-guard`	Whether text meant for an AI model looks like an attempt to make it misbehave.

Your developers send addresses or a prompt, and get plain JSON back. The API is free with every paid Cerberius Agents plan.

Who can use it#

Every paid plan includes the API. There's nothing to buy or switch on.
On the Free plan, keys can't be made and calls are refused.
If the account is locked because a bill wasn't paid, calls are refused until it's paid. Keys are kept.
Only owners and admins can make and remove keys, under Organisation › API.

The API page in the app explains that page: keys, signed calls and usage.

The address#

Every call goes to this address, followed by the call's path:

https://service.cerberius.com/api

For example, an IP lookup goes to https://service.cerberius.com/api/ip-lookup.

Method and path	What it does
`POST /ip-lookup`	IP lookup: up to 100 IP addresses per call. Needs a key.
`POST /email-lookup`	Email check: up to 100 email addresses per call. Needs a key.
`POST /prompt-guard`	Prompt check: one prompt per call. Needs a key.
`GET /schema`	The API's OpenAPI description, as JSON, for code generators and tools such as Postman. No key needed.
`GET /healthcheck`	Answers `health ok` (plain text) when the API is up. It doesn't test the checks themselves. No key needed.

Each check is a POST with a JSON body. Send the header Content-Type: application/json, or the call is refused.

Get a key#

1
In Cerberius Agents, open Organisation › API and click Make a key.
2
Type a Name that says which system will use it, such as "Sign-up form".
3
Leave Sign every call off, unless you want signed calls.
4
Click Make key. Copy the key: it starts with cbk_ and is shown only once.

Keep the key on your server, like a password. The examples below read it from an environment variable called CERBERIUS_API_KEY.

Keep the key on your server

Call the API from your server. Don't put the key in a web page or in an app people download. Anyone could read it there, and use the API as your organisation.

Make one key for each system that calls the API. Then you can remove one key without stopping the others.

Your first call#

Each example looks up one IP address and prints its country. On an error, it stops with the status and our message.

curl#

curl https://service.cerberius.com/api/ip-lookup \
  -H "X-API-Key: $CERBERIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": ["8.8.8.8"]}'

Python#

Needs the requests package (pip install requests).

import os

import requests

response = requests.post(
    "https://service.cerberius.com/api/ip-lookup",
    headers={"X-API-Key": os.environ["CERBERIUS_API_KEY"]},
    json={"data": ["8.8.8.8"]},
    timeout=100,
)
answer = response.json()
if response.status_code != 200:
    raise RuntimeError(f"{response.status_code}: {answer['error']['message']}")
print(answer["data"][0]["country"])

Node.js#

Needs Node.js 18 or later, which has fetch built in. Save it as a .mjs file, so await works outside a function.

const response = await fetch("https://service.cerberius.com/api/ip-lookup", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.CERBERIUS_API_KEY,
  },
  body: JSON.stringify({ data: ["8.8.8.8"] }),
  signal: AbortSignal.timeout(100_000),
});
const answer = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${answer.error.message}`);
console.log(answer.data[0].country);

The answer#

Every check answers in the same shape. Here it is for the call above, shortened to a few fields:

{
  "excess_charges_apply": false,
  "data": [
    {
      "ip_address": "8.8.8.8",
      "lookup_status": "Success",
      "country": "United States",
      "country_code": "US",
      "fraud_score": "low"
    }
  ]
}

data holds the results: a list with one result per address, or, for a prompt check, one result.
excess_charges_apply is always false. There are no extra charges. The field is kept so code written for the first version of the API keeps working.

Each check's article lists every field: IP lookup, Email check and Prompt check.

Good to know#

Results can come back in a different order from the addresses you sent. Match each result on ip_address or email_address.
Email checks can be slow. We ask each address's mail server, which can take several seconds. Let a call run for up to 100 seconds before you give up.
Limits: up to 100 addresses or one prompt per call, and about 10 calls a second per key. See Errors and limits.
New fields may be added to answers over time. Ignore any you don't know.
Coming from the old Cerberius APIs? The address, headers, signature and field names are the same. Make a new key under Organisation › API and use it in place of the old one.

Next: Authentication and signed calls.