# ipbase documentation

> ipbase resolves IP addresses to geolocation, network (ASN), security and hosted-domain data over a simple JSON REST API.

Authenticate every request with your API key via the `apikey` query parameter or request header. Base URL: https://api.ipbase.com

OpenAPI specification: https://ipbase.com/docs/openapi.yaml

---

Source: https://ipbase.com/docs

# ipbase API Documentation

Use the ipbase API to retrieve information about any IP address, ASN or domain and seamlessly integrate it into your product using one of our many SDKs or other pre-built integrations.

Building with an AI assistant? The full API is available as a machine-readable [OpenAPI 3.1 specification](https://ipbase.com/docs/openapi.yaml), and the documentation is published as [llms.txt](https://ipbase.com/docs/llms.txt) / [llms-full.txt](https://ipbase.com/docs/llms-full.txt). There is also a hosted [MCP server](https://ipbase.com/docs/mcp) at `https://api.ipbase.com/mcp` that AI agents can connect to directly.

## Getting started

To get started, you have to register an API key [here](https://app.ipbase.com/register). Then, follow our quickstart guide or continue reading our documentation and integrate ipbase, using our HTTP API, dedicated client SDKs or Postman Collection. Ultimately, [upgrade your plan](https://app.ipbase.com/subscription) to access all data & endpoints.

---

Source: https://ipbase.com/docs/asns

Available in plans >= medium

# ASN Endpoint

Retrieves the information about the provided ASN.

---

## ASN Information

This asn endpoint returns information any specified ASN.

### Required attributes

- **asn** (string):
The ASN you want to query

### Reponse Structure
Our `/asns` endpoint offers the following information:

```bash {{title: 'cURL'}}
curl -G https://api.ipbase.com/v2/asns?asn=AS13335 \
    -H "apikey: YOUR-API-KEY"
```

```js
import Ipbase from '@everapi/ipbase-js'

const ipBase = new Ipbase('YOUR-API-KEY')

await ipbase.asns({asn: 'AS13335'})
```

```python
import ipbase

client = ipbase.Client('YOUR-API-KEY')
result = client.asn('AS13335')
print(result)
```

```php
$client = new \Ipbase\Ipbase\IpbaseClient('YOUR-API-KEY');

$client->asns(['asn' => 'AS13335']);
```

```json {{title: 'Full Response'}}
{
    "data": {
        "asn": "AS13335",
        "organization": "Cloudflare, Inc.",
        "domain": "cloudflare.com",
        "country": "AU",
        "isp": "APNIC Research and Development",
        "ip_count": 512,
        "ranges_count": 2,
        "ranges": [
            {
                "subnet": "1.0.0.0/24",
                "company": "APNIC Research and Development",
                "ip_count": 256,
                "country": "AU"
            },
            {
                "subnet": "1.1.1.0/24",
                "company": "APNIC Research and Development",
                "ip_count": 256,
                "country": "AU"
            }
        ]
    }
}
```

---

### `data`   Response Properties

Available in all plans

- **asn** (integer):
The requested ASN

- **organization** (string):
️️The organization which owns the ASN

- **domain** (string):
The domain of the organization

- **country** (string):
The ISO 3166-1 alpha-2 country code of the owner of the ASN

- **isp** (string):
️ The ISP which the ASN belongs to

- **ip_count** (integer):
️The total count of IPs owned by this ASN

- **ranges_count** (integer):
️The total count of subnet ranges owned by this ASN

- **ranges** (array):
An array of the ranges owned by this ASN (see below)

```json lines
{
    "data": {
        "ip": "1.1.1.1",
        "hostname": "one.one.one.one",
        "type": "v4",
        ...
    }
}
```

---

### `ranges`   Response Properties

Available in all plans

- **subnet** (string):
The subnet in CIDR notation

- **company** (string):
The company name owning this subnet

- **ip_count** (string):
Count of the IPs contained in this subnet

- **country** (string):
The ISO 3166-1 alpha-2 country code for the location of the subnet

```json lines
{
    ...
    "ranges": [
        {
            "subnet": "1.0.0.0/24",
            "company": "APNIC Research and Development",
            "ip_count": 256,
            "country": "AU"
        },
        {
            "subnet": "1.1.1.0/24",
            "company": "APNIC Research and Development",
            "ip_count": 256,
            "country": "AU"
        }
    ],
    ...
}
```

---

Source: https://ipbase.com/docs/attachments

'On this page, we’ll dive into the different attachment endpoints you can use to manage attachments programmatically.'

# Attachments

Attachments are how you share things in Protocol — they allow you to send all sorts of files to your contacts and groups. On this page, we'll dive into the different attachment endpoints you can use to manage attachments programmatically. We'll look at how to query, upload, update, and delete attachments.

## The attachment model

The attachment model contains all the information about the files you send to your contacts and groups, including the name, type, and size.

### Properties

- **id** (string):
Unique identifier for the attachment.

- **message_id** (string):
Unique identifier for the message associated with the attachment.

- **filename** (string):
The filename for the attachment.

- **file_url** (string):
The URL for the attached file.

- **file_type** (string):
The MIME type of the attached file.

- **file_size** (integer):
The file size of the attachment in bytes.

- **created_at** (timestamp):
Timestamp of when the attachment was created.

---

## List all attachments

This endpoint allows you to retrieve a paginated list of all your attachments (in a conversation if a conversation id is provided). By default, a maximum of ten attachments are shown per page.

### Optional attributes

- **conversation_id** (string):
Limit to attachments from a given conversation.

- **limit** (integer):
Limit the number of attachments returned.

```bash {{ title: 'cURL' }}
curl -G https://api.protocol.chat/v1/attachments \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.attachments.list()
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.attachments.list()
```

```php
$client = new \Protocol\ApiClient($token);

$client->attachments->list();
```

```json {{ title: 'Response' }}
{
  "has_more": false,
  "data": [
    {
      "id": "Nc6yKKMpcxiiFxp6",
      "message_id": "LoPsJaMcPBuFNjg1",
      "filename": "Invoice_room_service__Plaza_Hotel.pdf",
      "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
      "file_type": "application/pdf",
      "file_size": 21352,
      "created_at": 692233200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}
```

---

## Create an attachment

This endpoint allows you to upload a new attachment to a conversation. See the code examples for how to send the file to the Protocol API.

### Required attributes

- **file** (string):
The file you want to add as an attachment.

```bash {{ title: 'cURL' }}
curl https://api.protocol.chat/v1/attachments \
  -H "Authorization: Bearer {token}" \
  -F file="../Invoice_room_service__Plaza_Hotel.pdf"
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.attachments.create({ file })
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.attachments.create(file=file)
```

```php
$client = new \Protocol\ApiClient($token);

$client->attachments->create([
  'file' => $file,
]);
```

```json {{ title: 'Response' }}
{
  "id": "Nc6yKKMpcxiiFxp6",
  "message_id": "LoPsJaMcPBuFNjg1",
  "filename": "Invoice_room_service__Plaza_Hotel.pdf",
  "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
  "file_type": "application/pdf",
  "file_size": 21352,
  "created_at": 692233200
}
```

---

## Retrieve an attachment

This endpoint allows you to retrieve an attachment by providing the attachment id. Refer to [the list](#the-attachment-model) at the top of this page to see which properties are included with attachment objects.

```bash {{ title: 'cURL' }}
curl https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
  -H "Authorization: Bearer {token}"
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.attachments.get('Nc6yKKMpcxiiFxp6')
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.attachments.get("Nc6yKKMpcxiiFxp6")
```

```php
$client = new \Protocol\ApiClient($token);

$client->attachments->get('Nc6yKKMpcxiiFxp6');
```

```json {{ title: 'Response' }}
{
  "id": "Nc6yKKMpcxiiFxp6",
  "message_id": "LoPsJaMcPBuFNjg1",
  "filename": "Invoice_room_service__Plaza_Hotel.pdf",
  "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf",
  "file_type": "application/pdf",
  "file_size": 21352,
  "created_at": 692233200
}
```

---

## Update an attachment

This endpoint allows you to perform an update on an attachment. Currently, the only supported type of update is changing the filename.

### Optional attributes

- **filename** (string):
The new filename for the attachment.

```bash {{ title: 'cURL' }}
curl -X PUT https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
  -H "Authorization: Bearer {token}" \
  -d filename="Invoice_room_service__Plaza_Hotel_updated.pdf"
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.attachments.update('Nc6yKKMpcxiiFxp6', {
  filename: 'Invoice_room_service__Plaza_Hotel_updated.pdf',
})
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.attachments.update("Nc6yKKMpcxiiFxp6", filename="Invoice_room_service__Plaza_Hotel_updated.pdf")
```

```php
$client = new \Protocol\ApiClient($token);

$client->attachments->update('Nc6yKKMpcxiiFxp6', [
  'filename' => 'Invoice_room_service__Plaza_Hotel_updated.pdf',
]);
```

```json {{ title: 'Response' }}
{
  "id": "Nc6yKKMpcxiiFxp6",
  "message_id": "LoPsJaMcPBuFNjg1",
  "filename": "Invoice_room_service__Plaza_Hotel.pdf",
  "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel_updated.pdf",
  "file_type": "application/pdf",
  "file_size": 21352,
  "created_at": 692233200
}
```

---

## Delete an attachment

This endpoint allows you to delete attachments. Note: This will permanently delete the file.

```bash {{ title: 'cURL' }}
curl -X DELETE https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \
  -H "Authorization: Bearer {token}"
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.attachments.delete('Nc6yKKMpcxiiFxp6')
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.attachments.delete("Nc6yKKMpcxiiFxp6")
```

```php
$client = new \Protocol\ApiClient($token);

$client->attachments->delete('Nc6yKKMpcxiiFxp6');
```

---

Source: https://ipbase.com/docs/authentication

# Authentication

You'll need to authenticate your requests to access any of the endpoints in the ipbase API. In this guide, we'll look at how authentication works. ipbase offers two ways to authenticate your API requests: API key as GET parameter, or via request header.

## GET query parameter

You can pass your API key along with every request by adding it as a query parameter `apikey`

```bash {{ title: 'Example request with authentication via get request' }}
curl "https://api.ipbase.com/v2/info?ip=1.1.1.1&apikey=YOUR-APIKEY"
```

Please don't commit your ipbase password to GitHub!

## HTTP Header

The recommended way to authenticate with the ipbase API through a HTTP request header:

```bash {{ title: 'Example request with authentication via header' }}
curl "https://api.ipbase.com/v2/info?ip=1.1.1.1" \
  -H "apikey: YOUR-API-KEY"
```

Always keep your token safe and reset it if you suspect it has been compromised.

## Using an SDK

If you use one of our official SDKs, you won't have to worry about any of the above — fetch your access token from the [ipbase dashboard](https://app.ipbase.com/dashboard) and the client library will take care of the rest. All the client libraries use OAuth2 behind the scenes.

---

Source: https://ipbase.com/docs/block-users-by-country

# How to block users based on their country

Blocking users based on their country is a very common use case. In this tutorial, we are going to look at an example,
where we restrict certain content from a list of countries.

## Introduction
In this example, we are specifically blocking users from accessing a website. It is worth mentioning that this example
specifically aims to block users that have no association to us or our servers (e.g. a user account).
Typically, we are talking about website visitors.

## Writing the code
We are sending a `GET` request to the ipbase IP info endpoint, which provides us with the associated country information.
In fact, the `info`endpoint ([Read more](/info)) provides an entire data object that is dedicated towards providing country-specific
information (including currency, timezones, etc.). For our use case, the `alpha2` code,
which represents the ISO 3166 ALPHA-2 standard, is most sufficient.

That being said, we are checking the user client's IP address for it's alpha2-country code against a list of countries.
If the user's country is part of the list, he is being blocked from the content. If not, he is allowed to see the content.
Instead of actually blocking the users, we are working with "you are blocked" or "you can see this messages" messages as examples.

```js
import Ipbase from '@everapi/ipbase-js'

const blockedCountries = ['DE', 'AT', 'ES', 'CH']
const ipBase = new Ipbase('Gvq8SwM11WP0qfgJEczrlFZknvmMfY2jzIacnAe5')
var userCountry = await ipBase.info().then(response => {
    return response.data.location.country.alpha2
});

if(blockedCountries.includes(userCountry)) {
    console.log('You are blocked');
} else {
    console.log('You can see this');
}
```

```python
import ipbase

blockedCountries = ['DE', 'AT', 'ES', 'CH']
client = ipbase.Client('YOUR-API-KEY')

userCountry = client.info()['data']['location']['country']['alpha2']

if userCountry in blockedCountries:
    print('You are blocked')
else:
    print('You can see this')

```

```php
<?php

$blockedCountries = ['AT', 'DE', 'ES', 'CH', 'HR'];
$ipBase = new \Ipbase\Ipbase\IpbaseClient('YOUR-API-KEY');

$userCountry = $ipBase->info()['data']['location']['country']['alpha2'];

if(in_array($userCountry, $blockedCountries)) {
    echo "You are blocked";
} else {
    echo "You can see this";
}
```

There are plenty of use cases where you can exclude users because of their country of origin. For example, some companies want to
exclude users that are from the European Union due to GDPR issues.

Register your API key to get started, here and enter the API key in the example above.

---

Source: https://ipbase.com/docs/conversations

'On this page, we’ll dive into the different conversation endpoints you can use to manage conversations programmatically.'

# Conversations

Conversations are an essential part of Protocol — they are the containers for the messages between you, your contacts, and groups. On this page, we’ll dive into the different conversation endpoints you can use to manage conversations programmatically. We'll look at how to query, create, update, and delete conversations.

## The conversation model

The conversation model contains all the information about the conversations between you and your contacts. In addition, conversations can also be group-based with more than one contact, they can have a pinned message, and they can be muted.

### Properties

- **id** (string):
Unique identifier for the conversation.

- **contact_id** (string):
Unique identifier for the other contact in the conversation.

- **group_id** (string):
Unique identifier for the group that the conversation belongs to.

- **pinned_message_id** (string):
Unique identifier for the pinned message.

- **is_pinned** (boolean):
Whether or not the conversation has been pinned.

- **is_muted** (boolean):
Whether or not the conversation has been muted.

- **last_active_at** (timestamp):
Timestamp of when the conversation was last active.

- **last_opened_at** (timestamp):
Timestamp of when the conversation was last opened by the authenticated
user.

- **created_at** (timestamp):
Timestamp of when the conversation was created.

- **archived_at** (timestamp):
Timestamp of when the conversation was archived.

---

## List all conversations

This endpoint allows you to retrieve a paginated list of all your conversations. By default, a maximum of ten conversations are shown per page.

### Optional attributes

- **limit** (integer):
Limit the number of conversations returned.

- **muted** (boolean):
Only show conversations that are muted when set to `true`.

- **archived** (boolean):
Only show conversations that are archived when set to `true`.

- **pinned** (boolean):
Only show conversations that are pinned when set to `true`.

- **group_id** (string):
Only show conversations for the specified group.

```bash {{ title: 'cURL' }}
curl -G https://api.protocol.chat/v1/conversations \
  -H "Authorization: Bearer {token}" \
  -d limit=10
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.conversations.list()
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.conversations.list()
```

```php
$client = new \Protocol\ApiClient($token);

$client->conversations->list();
```

```json {{ title: 'Response' }}
{
  "has_more": false,
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "contact_id": "WAz8eIbvDR60rouK",
      "group_id": null,
      "pinned_message_id": null,
      "is_pinned": false,
      "is_muted": false,
      "last_active_at": 705103200,
      "last_opened_at": 705103200,
      "created_at": 692233200,
      "archived_at": null
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}
```

---

## Create a conversation

This endpoint allows you to add a new conversation between you and a contact or group. A contact or group id is required to create a conversation.

### Required attributes

- **contact_id** (string):
Unique identifier for the other contact in the conversation.

- **group_id** (string):
Unique identifier for the group that the conversation belongs to.

```bash {{ title: 'cURL' }}
curl https://api.protocol.chat/v1/conversations \
  -H "Authorization: Bearer {token}" \
  -d 'contact_id'="WAz8eIbvDR60rouK"
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.conversations.create({
  contact_id: 'WAz8eIbvDR60rouK',
})
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.conversations.create(contact_id="WAz8eIbvDR60rouK")
```

```php
$client = new \Protocol\ApiClient($token);

$client->conversations->create([
  'contact_id' => 'WAz8eIbvDR60rouK',
]);
```

```json {{ title: 'Response' }}
{
  "id": "xgQQXg3hrtjh7AvZ",
  "contact_id": "WAz8eIbvDR60rouK",
  "group_id": null,
  "pinned_message_id": null,
  "is_pinned": false,
  "is_muted": false,
  "last_active_at": null,
  "last_opened_at": null,
  "created_at": 692233200,
  "archived_at": null
}
```

---

## Retrieve a conversation

This endpoint allows you to retrieve a conversation by providing the conversation id. Refer to [the list](#the-conversation-model) at the top of this page to see which properties are included with conversation objects.

```bash {{ title: 'cURL' }}
curl https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.conversations.get('xgQQXg3hrtjh7AvZ')
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.conversations.get("xgQQXg3hrtjh7AvZ")
```

```php
$client = new \Protocol\ApiClient($token);

$client->conversations->get('xgQQXg3hrtjh7AvZ');
```

```json {{ title: 'Response' }}
{
  "id": "xgQQXg3hrtjh7AvZ",
  "contact_id": "WAz8eIbvDR60rouK",
  "group_id": null,
  "pinned_message_id": null,
  "is_pinned": false,
  "is_muted": false,
  "last_active_at": 705103200,
  "last_opened_at": 705103200,
  "created_at": 692233200,
  "archived_at": null
}
```

---

## Update a conversation

This endpoint allows you to perform an update on a conversation. Examples of updates are pinning a message, muting or archiving the conversation, or pinning the conversation itself.

### Optional attributes

- **pinned_message_id** (string):
Unique identifier for the pinned message.

- **is_pinned** (boolean):
Whether or not the conversation has been pinned.

- **is_muted** (boolean):
Whether or not the conversation has been muted.

- **archived_at** (timestamp):
Timestamp of when the conversation was archived.

```bash {{ title: 'cURL' }}
curl -X PUT https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'is_muted'=true
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.conversations.update('xgQQXg3hrtjh7AvZ', {
    is_muted: true,
})
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.conversations.update("xgQQXg3hrtjh7AvZ", is_muted=True)
```

```php
$client = new \Protocol\ApiClient($token);

$client->conversations->update('xgQQXg3hrtjh7AvZ', [
  'is_muted' => true,
]);
```

```json {{ title: 'Response' }}
{
  "id": "xgQQXg3hrtjh7AvZ",
  "contact_id": "WAz8eIbvDR60rouK",
  "group_id": null,
  "pinned_message_id": null,
  "is_pinned": false,
  "is_muted": true,
  "last_active_at": 705103200,
  "last_opened_at": 705103200,
  "created_at": 692233200,
  "archived_at": null
}
```

---

## Delete a conversation

This endpoint allows you to delete your conversations in Protocol. Note: This will permanently delete the conversation and all its messages — archive it instead if you want to be able to restore it later.

```bash {{ title: 'cURL' }}
curl -X DELETE https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"
```

```js
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.conversations.delete('xgQQXg3hrtjh7AvZ')
```

```python
from protocol_api import ApiClient

client = ApiClient(token)

client.conversations.delete("xgQQXg3hrtjh7AvZ")
```

```php
$client = new \Protocol\ApiClient($token);

$client->conversations->delete('xgQQXg3hrtjh7AvZ');
```

---

Source: https://ipbase.com/docs/domains

Available in plans >= medium

# Domain Endpoint

Retrieves all domains hosted on a single IP address.

---

## Domain Information

This domain endpoint returns information about hosted domains via a specified IP address.

### Required attributes

- **ip** (string):
The IP you want to query the domains for

### Optional attributes

- **cursor** (integer):
The cursor for iterating through all domains

- **per_page** (integer):
The amount of domains you want to see on each page

### Response Properties

- **data** (array):
The hosted domains on this IP address as an array of strings

- **total_count** (integer):
️️The total count of domains hosted on this IP address

- **next_cursor** (string):
️The cursor to the next page of the domains

- **next_page_url** (string):
️A link to the next page of the domains

- **per_page** (integer):
️The amount of domains listed in one request

- **prev_cursor** (string):
️The cursor to the previous page of the domains

- **prev_page_url** (string):
A link to the previous page of the domains

```bash {{title: 'cURL'}}
curl -G https://api.ipbase.com/v2/domains?ip=1.1.1.1 \
    -H "apikey: YOUR-API-KEY"
```

```js
import Ipbase from '@everapi/ipbase-js'

const ipBase = new Ipbase('YOUR-API-KEY')

await ipbase.domains({ip: '1.1.1.1'})
```

```python
import ipbase

client = ipbase.Client('YOUR-API-KEY')
result = client.domains('1.1.1.1')
print(result)
```

```php
$client = new \Ipbase\Ipbase\IpbaseClient('YOUR-API-KEY');

$client->domains(['ip' => '1.1.1.1']);
```

```json {{title: 'Full Response'}}
{
    "data": [
        "eliwise.academy",
        "accountingprose.academy",
        "pistola.academy",
        "1and1-test-ntlds-fr.accountant",
        "omnergy.africa",
        "sulphur.africa",
        "saadeh.agency",
        "mi6-gov.agency",
        "zhonghuidigi.agency",
        "alecta.app",
        "carso.app",
        "desaparecidos.app",
        "hx.app",
        "ibx.app",
        "lawso.app",
        "akey.app",
        "yabo168.app",
        "yabo188.app",
        "bob223.app",
        "yabo104.app",
        "yabo110.app",
        "yabo113.app",
        "yabo118.app",
        "yabo125.app",
        "yabo127.app",
        "yabo130.app",
        "yabo131.app",
        "yabo132.app",
        "yabo134.app",
        "yabo135.app"
    ],
    "total_count": 11046,
    "per_page": 30,
    "next_cursor": "eyJpZCI6MzI1MDQsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "next_page_url": "https://api.ipbase.com/v2/domains?apikey=[[REDACTED]]&ip=1.1.1.16&cursor=eyJpZCI6MzI1MDQsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": "eyJpZCI6MjM4ODksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
    "prev_page_url": "https://api.ipbase.com/v2/domains?apikey=[[REDACTED]]&ip=1.1.1.1&cursor=eyJpZCI6MjM4ODksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9"
}
```

---

Source: https://ipbase.com/docs/info

# Info Endpoint

Checks the provided IP address (both `v4` & `v6` formats) and returns all available information.

---

## IP Information

This IP information endpoint returns information your client's or a specific IP address.

### Optional attributes

- **ip** (string):
The IP address you want to query

- **language** (string):
An ISO Alpha 2 Language Code for localizing the IP data

- **hostname** (boolean):
If the hostname parameter is set to 1, the API response will contain the hostname of the ip

### Response Structure
Our `/info` endpoint offers the following information: data (general information), `range_type`, `connection`, `location`, `tlds`, `timezone`, `security` and `domains`.

```bash {{title: 'cURL'}}
curl -G https://api.ipbase.com/v2/info?ip=1.1.1.1 \
    -H "apikey: YOUR-API-KEY"
```

```js
import Ipbase from '@everapi/ipbase-js'

const ipBase = new Ipbase('YOUR-API-KEY')

await ipbase.info({ip: '1.1.1.1'})
```

```python
import ipbase

client = ipbase.Client('YOUR-API-KEY')
result = client.info('1.1.1.1')
print(result)
```

```php
$client = new \Ipbase\Ipbase\IpbaseClient('YOUR-API-KEY');

$client->info(['ip' => '1.1.1.1']);
```

```json {{title: 'Full Response'}}
{
    "data": {
        "ip": "1.1.1.1",
        "hostname": "one.one.one.one",
        "type": "v4",
        "range_type": {
            "type": "PUBLIC",
            "description": "Public address"
        },
        "connection": {
            "asn": 13335,
            "organization": "Cloudflare, Inc.",
            "isp": "APNIC Research and Development",
            "range": "1.1.1.1/32"
        },
        "location": {
            "geonames_id": 5368753,
            "latitude": 34.053611755371094,
            "longitude": -118.24549865722656,
            "zip": "90012",
            "continent": {
                "code": "NA",
                "name": "North America",
                "name_translated": "North America",
                "geonames_id": 6255149,
                "wikidata_id": "Q49"
            },
            "country": {
                "alpha2": "US",
                "alpha3": "USA",
                "calling_codes": [
                    "+1"
                ],
                "currencies": [
                    {
                        "symbol": "$",
                        "name": "US Dollar",
                        "symbol_native": "$",
                        "decimal_digits": 2,
                        "rounding": 0,
                        "code": "USD",
                        "name_plural": "US dollars"
                    }
                ],
                "emoji": "🇺🇸",
                "ioc": "USA",
                "languages": [
                    {
                        "name": "English",
                        "name_native": "English"
                    }
                ],
                "name": "United States",
                "name_translated": "United States",
                "timezones": [
                    "America/New_York",
                    "America/Detroit",
                    "America/Kentucky/Louisville",
                    "America/Kentucky/Monticello",
                    "America/Indiana/Indianapolis",
                    "America/Indiana/Vincennes",
                    "America/Indiana/Winamac",
                    "America/Indiana/Marengo",
                    "America/Indiana/Petersburg",
                    "America/Indiana/Vevay",
                    "America/Chicago",
                    "America/Indiana/Tell_City",
                    "America/Indiana/Knox",
                    "America/Menominee",
                    "America/North_Dakota/Center",
                    "America/North_Dakota/New_Salem",
                    "America/North_Dakota/Beulah",
                    "America/Denver",
                    "America/Boise",
                    "America/Phoenix",
                    "America/Los_Angeles",
                    "America/Anchorage",
                    "America/Juneau",
                    "America/Sitka",
                    "America/Metlakatla",
                    "America/Yakutat",
                    "America/Nome",
                    "America/Adak",
                    "Pacific/Honolulu"
                ],
                "is_in_european_union": false,
                "fips": "US",
                "geonames_id": 6252001,
                "hasc_id": "US",
                "wikidata_id": "Q30"
            },
            "city": {
                "fips": "0644000",
                "alpha2": null,
                "geonames_id": 5368753,
                "hasc_id": null,
                "wikidata_id": "Q65",
                "name": "Los Angeles",
                "name_translated": "Los Angeles"
            },
            "region": {
                "fips": "US06",
                "alpha2": "US-CA",
                "geonames_id": 5332921,
                "hasc_id": "US.CA",
                "wikidata_id": "Q99",
                "name": "California",
                "name_translated": "California"
            }
        },
        "tlds": [
            ".us"
        ],
        "timezone": {
            "id": "America/Los_Angeles",
            "current_time": "2023-06-28T07:46:37-07:00",
            "code": "PDT",
            "is_daylight_saving": true,
            "gmt_offset": -25200
        },
        "security": {
            "is_anonymous": false,
            "is_datacenter": false,
            "is_vpn": false,
            "is_bot": false,
            "is_abuser": false,
            "is_known_attacker": false,
            "is_proxy": false,
            "is_spam": false,
            "is_tor": false,
            "is_icloud_relay": false,
            "threat_score": 100
        },
        "domains": {
            "count": 12337,
            "domains": [
                "eliwise.academy",
                "accountingprose.academy",
                "1and1-test-ntlds-fr.accountant",
                "sulphur.africa",
                "saadeh.agency"
            ]
        }
    }
}
```

---

### `data`   Response Properties

Available in all plans

- **ip** (string):
The requested IP address

- **hostname** (string):
️The IPs hostname - if requested via `?hostname=1`

- **type** (string):
IP type `v4` or `v6`

Hostname Lookup
The ipbase API does not by default return details about the hostname that the specified IP address resolves to. Add the hostname parameter of the API and set it to 1 to include the hostname object in your API return.

Important:
The ipbase API does not by default return details about the hostname that the specified IP address resolves to. Add the hostname parameter of the API and set it to 1 to include the hostname object in your API return.

```json lines
{
    "data": {
        "ip": "1.1.1.1",
        "hostname": "one.one.one.one",
        "type": "v4",
        ...
    }
}
```

---

### `range_type`   Response Properties

Available in all plans

- **type** (string):
See below

- **description** (string):
️Range type

The range `type` field can have the following values:

Unspecified/unknown address

️Reserved/internal use only

️Refer to source hosts on this network

️Internet host loopback address

️Relay anycast address

️Limited broadcast destination address

️Multicast address assignments - Indentify a group of interfaces

️Link local address, allocated for communication between hosts on a single link

️Link local unicast / Linked-scoped unicast

️Discard only

️Discard

️For use in private networks

️Public address

️Carrier-grade NAT

️Reserved/internal use only

```json lines
{
    "range_type": {
        "type": "PUBLIC",
        "description": "Public address"
    }
}
```

---

### `connection`   Response Properties

Available in all plans

- **asn** (integer):
The ASN number

- **organization** (string):
️️The ASN organization

- **isp** (string):
️️The name of the ISP

- **range** (string):
The IP range

Tip:
You can request more information about the ASN via the [asn endpoint](/asns). The ASN endpoint is available in the medium plan and above.

```json lines
{
    "connection": {
        "asn": 13335,
        "organization": "Cloudflare, Inc.",
        "isp": "APNIC Research and Development",
        "range": "1.1.1.1/32"
    }
}
```

---

### `location`   Response Properties

Available in all plans

- **geonames_id** (integer):
Geonames identifier for the [Geonames Registry](https://geonames.org)

- **latitude** (float):
️️Latitude associated with the IP address

- **longitude** (float):
Longitude associated with the IP address

- **zip** (string):
ZIP code associated with the IP address

### Third-party data IDs

Our location information features IDs of the following data sources that can be mapped for further data ingestion:

- **geonames_id** (source: Geonames):
Example: [https://www.geonames.org/5332870/](https://www.geonames.org/5332870/) for California

- **hasc_id** (source: Wikidata):
Example: [https://www.wikidata.org/wiki/Property:P8119](https://www.wikidata.org/wiki/Property:P8119) represents country subdivions within

- **wikidata_id** (source: Wikidata):
Example: [https://www.wikidata.org/wiki/Q30](https://www.wikidata.org/wiki/Q30) for California

- **fips** (source: FIPS):
[https://www.census.gov/library/reference/code-lists/ansi.html](https://www.census.gov/library/reference/code-lists/ansi.html)

More detailed location data is available within three objects: `country`, `city`, and `region`.

---

### `country`
Type: object

- **alpha2** (string):
The alpha2 representation of the country code

- **alpha3** (string):
️   The alpha3 representation of the country code

- **calling_codes** (array):
All available calling codes for this country

- **emoji** (string):
The country's flag as an emoji

- **ioc** (string):
The IOCs three-letter representation of the country code ([reference](https://en.wikipedia.org/wiki/List_of_IOC_country_codes))

- **name** (string):
The country name data

- **name_translated** (string):
The local country name data

- **timezones** (array):
All of the available timezones within the country data

- **is_in_european_union** (boolean):
true if the country is in the European Union (helpful for GDPR redirects), otherwise `false

- **fips** (string):
The FIPS two letter representation of the country code ([reference](https://en.wikipedia.org/wiki/List_of_FIPS_country_codes))

- **geonames_id** (integer):
[reference](https://ipbase.com/docs/info#location)

- **hasc_id** (string):
[reference](https://ipbase.com/docs/info#location)

- **wikidata_id** (string):
[reference](https://ipbase.com/docs/info#location)

---

### `country > currencies`
Type: object

- **symbol** (string):
The currency symbol

- **name** (string):
️   ️The currency name

- **symbol_native** (string):
The native currency symbol

- **decimal_digits** (integer):
How many decimal digits does the currency use

- **rounding** (integer):
The IOCs three-letter representation of the country code ([reference](https://en.wikipedia.org/wiki/List_of_IOC_country_codes))

- **code** (string):
️The three letter currency code

- **name_plural** (string):
The plural version of the currency

---

### `country > languages`
Type: array&#60;object>

- **name** (string):
The language name

- **name_native** (string):
The native currency name

---

### `city`
Type: object

- **fips** (string):
The FIPS two letter representation of the city code ([reference](https://www.census.gov/library/reference/code-lists/ansi.html))

- **alpha2** (string):
️   The two-letter representation of the city

- **geonames_id** (integer):
[reference](https://ipbase.com/docs/info#location)

- **hasc_id** (string):
[reference](https://ipbase.com/docs/info#location)

- **wikidata_id** (string):
[reference](https://ipbase.com/docs/info#location)

- **name** (string):
The region name

- **name_translated** (string):
The local region name

```json lines
{
    "location": {
        "geonames_id": 5368753,
        "latitude": 34.053611755371094,
        "longitude": -118.24549865722656,
        "zip": "90012",
        "continent": {
            "code": "NA",
            "name": "North America",
            "name_translated": "North America",
            "geonames_id": 6255149,
            "wikidata_id": "Q49"
        },
        "country": {
            "alpha2": "US",
            "alpha3": "USA",
            "calling_codes": [
                "+1"
            ],
            "currencies": [
                {
                    "symbol": "$",
                    "name": "US Dollar",
                    "symbol_native": "$",
                    "decimal_digits": 2,
                    "rounding": 0,
                    "code": "USD",
                    "name_plural": "US dollars"
                }
            ],
            "emoji": "🇺🇸",
            "ioc": "USA",
            "languages": [
                {
                    "name": "English",
                    "name_native": "English"
                }
            ],
            "name": "United States",
            "name_translated": "United States",
            "timezones": [
                "America/New_York",
                "America/Detroit",
                "America/Kentucky/Louisville",
                "..."
            ],
            "is_in_european_union": false,
            "fips": "US",
            "geonames_id": 6252001,
            "hasc_id": "US",
            "wikidata_id": "Q30"
        },
        "city": {
            "fips": "0644000",
            "alpha2": null,
            "geonames_id": 5368753,
            "hasc_id": null,
            "wikidata_id": "Q65",
            "name": "Los Angeles",
            "name_translated": "Los Angeles"
        },
        "region": {
            "fips": "US06",
            "alpha2": "US-CA",
            "geonames_id": 5332921,
            "hasc_id": "US.CA",
            "wikidata_id": "Q99",
            "name": "California",
            "name_translated": "California"
        }
    }
}
```

---

### `timezone`   Response Properties

Available in all plans

- **id** (string):
The timezone

- **current_time** (string):
️The current time as a datetime string

- **code** (string):
️   The three-letter code for the timezone

- **is_daylight_saving** (boolean):
️   If it is currency in daylight saving

- **gmt_offset** (string):
️   The offset to GMT in seconds

```json lines
{
    "connection": {
        "asn": 13335,
        "organization": "Cloudflare, Inc.",
        "isp": "APNIC Research and Development",
        "range": "1.1.1.1/32"
    }
}
```

---

### `timezone`   Response Properties

>= Medium plan

- **id** (string):
The timezone

- **current_time** (string):
️The current time as a datetime string

- **code** (string):
️   The three-letter code for the timezone

- **is_daylight_saving** (boolean):
️   If it is currency in daylight saving

- **gmt_offset** (string):
️   The offset to GMT in seconds

```json lines
{
    "connection": {
        "asn": 13335,
        "organization": "Cloudflare, Inc.",
        "isp": "APNIC Research and Development",
        "range": "1.1.1.1/32"
    }
}
```

---

### `security`   Response Properties

>= Medium plan

- **is_anonymous** (boolean):
If the IP is anonymous

- **is_datacenter** (boolean):
️       If the IP is an address used in a datacenter

- **is_vpn** (boolean):
️       If the IP is a known VPN

- **is_bot** (boolean):
️       If the IP is a known bot

- **is_abuser** (boolean):
️       If the IP is a known bot

- **is_known_attacker** (boolean):
If the IP is a known attacker

- **is_proxy** (boolean):
If the IP is a known proxy

- **is_spam** (boolean):
If the IP is a known spammer

- **is_tor** (boolean):
If the IP is a known Tor endpoint

- **proxy_type** (string):
The type of proxy, it can be `vpn or an empty string

- **is_icloud_relay** (boolean):
If the IP is a known iCloud relay IP

- **threat_score** (boolean):
A threat score on a scale from 0 to 100, with 0 representing no threat and 100 the highest threat level

```json lines
{
    "security": {
        "is_anonymous": false,
        "is_datacenter": false,
        "is_vpn": false,
        "is_bot": false,
        "is_abuser": false,
        "is_known_attacker": false,
        "is_proxy": false,
        "is_spam": false,
        "is_tor": false,
        "proxy_type": "",
        "is_icloud_relay": false,
        "threat_score": 0
    }
}
```

---

### `domains`   Response Properties

>= Medium plan

- **count** (integer):
How many domains are hosted on this [domain](/domains)

- **domains** (array):
️️A list of domains hosted on this IP. Up to 5 domains are listed here; more are available with our Hosted Domain API (soon).

You can request all domains via the domains endpoint.

```json lines
{
    "domains": {
        "count": 12360,
        "domains": [
            "eliwise.academy",
            "accountingprose.academy",
            "pistola.academy",
            "1and1-test-ntlds-fr.accountant",
            "omnergy.africa"
        ]
    }
}
```

---

Source: https://ipbase.com/docs/mcp

'Connect AI agents to the ipbase API through our hosted MCP (Model Context Protocol) server.'

# MCP Server

ipbase ships a hosted [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, so AI agents and assistants can call the API as native tools — no SDK or glue code required.

```
https://api.ipbase.com/mcp
```

The endpoint speaks the streamable HTTP transport. Listing the available tools works without authentication; executing a tool requires your API key, sent as the `apikey` header. You can [get a free API key here](https://app.ipbase.com/register).

## Connect

Using Claude Code:

```bash
claude mcp add --transport http ipbase https://api.ipbase.com/mcp --header "apikey: YOUR_API_KEY"
```

Or add the server to any MCP-capable client (Claude Desktop, Cursor, VS Code, ...):

```json
{
  "mcpServers": {
    "ipbase": {
      "url": "https://api.ipbase.com/mcp",
      "headers": { "apikey": "YOUR_API_KEY" }
    }
  }
}
```

## Available tools

The tools are generated from the same [OpenAPI specification](https://ipbase.com/docs/openapi.yaml) that describes the REST API, so they always match the documented endpoints, parameters and responses.

| Tool | Endpoint | Description |
|---|---|---|
| `getInfo` | `GET /v2/info` | Look up an IP address |
| `getAsn` | `GET /v2/asns` | Look up an ASN |
| `getDomains` | `GET /v2/domains` | Domains hosted on an IP |
| `getStatus` | `GET /v2/status` | Account quota status |

## Quotas and errors

Tool calls are metered exactly like REST requests: they consume your plan quota and return the same status codes and error responses (`401`, `422`, `429`, ...). If a call fails, the tool result contains the API's error message including hints on how to proceed.

---

Source: https://ipbase.com/docs/quickstart

# Quickstart

This guide will get you all set up and ready to use the ipbase API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Before you can make requests to the ipbase API, you will need to grab your
API key from your dashboard. You find it under [App » Dashboard](https://app.ipbase.com/dashboard).

## Choose your client

Before making your first API request, you need to pick which API client you will use. In addition to cURL HTTP requests, ipbase offers [clients](/sdks) for JavaScript, Python, PHP and many more programming langauges. In the following example, you can see how to install each client.

```bash {{ title: 'cURL' }}
# cURL is most likely already installed on your machine
curl --version
```

```bash {{ language: 'js' }}
# Install the ipbase JavaScript SDK
npm install @everapi/ipbase-js --save
```

```bash {{ language: 'python' }}
# Install the ipbase Python SDK
pip install ipbase
```

```bash {{ language: 'php' }}
# Install the ipbase PHP SDK
composer require everapi/ipbase-php
```

## Making your first API request

After picking your preferred client, you are ready to make your first call to the ipbase API. Below, you can see how to send a
`GET` request to the `/info` endpoint to get information about your client's IP address.

```bash {{ title: 'cURL' }}
curl -G https://api.ipbase.com/v2/info \
    -H "apikey: YOUR-API-KEY"
```

```js
import Ipbase from '@everapi/ipbase-js'

const ipBase = new Ipbase('YOUR-API-KEY')
ipBase.info().then(response => {
    console.log(response)
});
```

```python
import ipbase

client = ipbase.Client('YOUR-API-KEY')
result = client.info()
print(result)
```

```php
$ipBase = new \Ipbase\Ipbase\IpbaseClient('YOUR-API-KEY');
echo $ipBase->info();
```

Alternatively, you can retrieve information about any specific IP address:

```bash {{ title: 'cURL' }}
curl -G https://api.ipbase.com/v2/info?ip=1.1.1.1 \
    -H "apikey: YOUR-API-KEY"
```

```js
import Ipbase from '@everapi/ipbase-js'

const ipBase = new Ipbase('YOUR-API-KEY')
ipBase.info({
    ip: '1.1.1.1'
}).then(response => {
    console.log(response)
});
```

```python
import ipbase

client = ipbase.Client('YOUR-API-KEY')
result = client.info('1.1.1.1')
print(result)
```

```php
$ipBase = new \Ipbase\Ipbase\IpbaseClient('YOUR-API-KEY');
echo $ipBase->info([
    'ip' => '1.1.1.1'
]);
```

## What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the ipbase API:

- [Grab your API key from the ipbase dashboard](#)
- [Check out the Conversations endpoint](/conversations)
- [Learn about the different error messages in ipbase](/errors)

---

Source: https://ipbase.com/docs/rate-limit

# Rate Limit & Quotas

You can use a certain number of requests per month, defined by your plan.

Once you go over this quota, the API returns a `429` HTTP status code, and you either need to upgrade your plan or wait until the end of the month. We enforce a minute rate limit for specific plans. If you exceed this, the API returns a 429 HTTP status code. You then have to wait until the end of the minute to make more requests. Not every request counts towards your monthly request volume.

Not every request counts
Only successful calls count against your quota. Any error on our side or validation errors (e.g., wrong parameter) will NOT count against your quota or rate limit.

```bash {{ title: 'Example request with basic auth' }}
curl "https://api.ipbase.com/v2/info?ip=1.1.1.1&apikey=YOUR-APIKEY"
```

## Response Headers

We attach specific headers to tell you your current monthly/minute quota and how much you have remaining in the period.

```json lines
X-RateLimit-Limit-Quota-Minute: 10
X-RateLimit-Limit-Quota-Month: 300

X-RateLimit-Remaining-Quota-Minute: 5
X-RateLimit-Remaining-Quota-Month: 199
```

---

Source: https://ipbase.com/docs/sdks

# SDKs

The recommended way to interact with the ipbase API is by using one of our official SDKs. Today, ipbase offers fine-tuned JavaScript, Ruby, PHP, Python, and Go libraries to make your life easier and give you the best experience when consuming the API.

---

Source: https://ipbase.com/docs/status

# Status Endpoint

The status endpoint returns information about your current quota.

Requests to this endpoint do not count against your quota or rate limit.

---

## Check API Status

This status endpoint returns information about your current quota.
### Required attributes

- **apikey** (string):
Your API Key - you can retrieve your API key from your ipbase dashboard.

---

### Response Properties

- **quotas** (object):
Contains information about your request quota.

```bash {{title: 'cURL'}}
curl -G https://api.ipbase.com/v2/status \
    -H "apikey: YOUR-API-KEY"
```

```js
import Ipbase from '@everapi/ipbase-js'

const ipBase = new Ipbase('YOUR-API-KEY')

await ipbase.status()
```

```python
import ipbase

client = ipbase.Client('YOUR-API-KEY')
result = client.status()
print(result)
```

```php
$client = new \Ipbase\Ipbase\IpbaseClient('YOUR-API-KEY');

$client->status();
```

```json {{title: 'Response'}}
{
    "account_id": 313373133731337,
    "quotas": {
        "month": {
            "total": 300,
            "used": 72,
            "remaining": 229
        },
        "grace": {
            "total": 0,
            "used": 0,
            "remaining": 0
        }
    }
}
```

---

Source: https://ipbase.com/docs/status-codes

# Request Status Codes

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code `200`.

Before reaching out to support with an error, please be aware that 99% of all
reported errors are, in fact, user errors. Therefore, please carefully check
your code before contacting Protocol support.

---

## Status codes

Here is a list of the different categories of status codes returned by the Protocol API. Use these to understand if a request was successful.

A 200 status code indicates a successful response.

A 403 status code indicates that you are not allowed to use this endpoint, [please upgrade your plan](https://app.ipbase.com/subscription).

A 404 status code indicates that a requested endpoint does not exist.

A 422 status code indicates that a requested endpoint does not exist.

A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests [please upgrade your plan](https://app.ipbase.com/subscription).

A 500 status code indicates a internal server error - let us know: support@ipbase.com

---

## Validation errors

Here is a list of the different categories of status codes returned by the Protocol API. Use these to understand if a request was successful.

The `ip` must be a valid IP address.

The `ip` parameter is required.

The selected `language` is invalid and should be an ISO Alpha 2 Language Code for localising the ip data.

---

---

Source: https://ipbase.com/docs/testing

# Testing

Available in plans >= medium

This page includes all needed information to make sure your test environment works before deploying to production.

### Sandbox API Keys
An API request sent with a sandbox api key is automatically identified as a request in sandbox mode. All request with sandbox keys will respond with dummy data.

Requests done with sandbox keys do not count against your quota.

Please note that the requests are still shown in the graph on the dashboard. You can select only your live key if you want to filter them out.

### Response
All API endpoints will respond with the data for the IP `1.1.1.1` and the ASN `AS13335`