# BGPTree Comprehensive Machine & LLM Specification

> High-performance Border Gateway Protocol (BGP) Autonomous System Number (ASN) intelligence, routing telemetry, multi-hop interconnectivity topology, and prefix intelligence.
> Published by SystGrid Solutions Pvt Ltd (Mumbai, India).

- **Service Base URL**: `https://api.bgptree.com/api/v1`
- **Web Interface**: `https://bgptree.com`
- **Legal Entity**: SystGrid Solutions Pvt Ltd (CIN / Mumbai Jurisdiction, Maharashtra, INDIA)
- **Compliance**: DPDP Act 2023 (Digital Personal Data Protection Act, India), CERT-In
- **Protocol**: HTTPS (TLS 1.3 / HTTP/2)
- **Default Media Type**: `application/json`

---

## 1. Authentication & Session Architecture

BGPTree implements an ephemeral cryptographic token exchange designed to prevent API exhaustion, abuse, and automated credential leakage.

### Token Exchange Flow
Clients make an unauthenticated `POST` request to `/auth/session` to obtain an ephemeral JSON Web Token (JWT) signed with HMAC-SHA256 (`HS256`). The token has a typical lifespan of 2 hours and must be passed as a Bearer token in the `Authorization` header on all protected endpoints.

#### Request
```bash
curl -s -X POST https://api.bgptree.com/api/v1/auth/session \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"
```

#### Response (`200 OK`)
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWQiOiIyNDkyODlhMTViMDQ5MmYwIiwiZXhwIjoxNzkzMzk5Mjg1LCJpYXQiOjE3OTMzOTIwODUsImlzcyI6ImJncHRyZWUuY29tIiwic3ViIjoiMjAzLjAuMTEzLjE1In0.kH6p6ZzM7vQ7Bq...",
  "expires_at": "2026-10-30T16:24:45Z",
  "token_type": "Bearer"
}
```

#### Utilizing the Token
All protected API calls require:
```
Authorization: Bearer <token>
```

---

## 2. API Endpoints Reference

### 2.0 Unauthenticated Public ASN Telemetry (`GET https://bgptree.com/api/as/{asn}`)
Designed specifically for AI agents, LLM tool calls, Answer Engines, and automated monitors that require immediate, single-request JSON telemetry without a session token handshake.

#### Curl Example
```bash
curl -s -X GET "https://bgptree.com/api/as/132986" -H "Accept: application/json"
```

#### Response (`200 OK`)
```json
{
  "asn": 132986,
  "name": "DDCPL-AS-IN",
  "description": "Digital Dreams Consulting Pvt Ltd",
  "country": "IN",
  "registry": "APNIC",
  "classification": "Access / Enterprise Stub Network",
  "announced_v4": 2,
  "announced_v6": 1,
  "total_prefixes": 3,
  "upstreams_count": 2,
  "downstreams_count": 0,
  "direct_peers_count": 4,
  "total_peers": 6,
  "neighbors": [],
  "updated_at": "2026-11-02T02:00:00Z",
  "canonical_url": "https://bgptree.com/as/132986",
  "telemetry_url": "https://bgptree.com/api/as/132986",
  "data_sources": ["RIPE NCC RIS", "PeeringDB", "RouteViews", "APNIC/ARIN/RIPE/LACNIC/AFRINIC RDAP"],
  "compliance": "DPDP Act 2023, Jurisdiction of Mumbai, Maharashtra, INDIA",
  "owner": "SystGrid Solutions Pvt Ltd",
  "owner_url": "https://systgrid.com"
}
```

---

### 2.1 Autonomous System Dossier (`GET /asn/{asn}`)
Retrieves comprehensive metadata, registry information, and prefix allocation telemetry for an ASN.

#### Parameters
- `asn` (path parameter, integer or string with prefix `AS`): The 16-bit or 32-bit Autonomous System Number (e.g. `13335`, `AS132986`, `15169`).

#### Curl Example
```bash
curl -s -X GET "https://api.bgptree.com/api/v1/asn/13335" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

#### Response (`200 OK`)
```json
{
  "asn": 13335,
  "name": "CLOUDFLARENET",
  "description": "Cloudflare, Inc.",
  "country": "US",
  "registry": "arin",
  "announced_v4": 2684,
  "announced_v6": 1219,
  "announced": true,
  "website": "https://www.cloudflare.com",
  "total_peers": 4210,
  "updated_at": "2026-10-30T10:15:00Z"
}
```

---

### 2.2 Direct BGP Neighbors (`GET /asn/{asn}/neighbors`)
Returns direct BGP peering adjacencies, categorized by relationship type (`upstream`, `peer`, `downstream`, or `uncertain`).

#### Parameters
- `asn` (path parameter, required): The target ASN.
- `proto` (query parameter, optional, default: `all`): Protocol filter: `all`, `ipv4`, or `ipv6`.

#### Curl Example
```bash
curl -s -X GET "https://api.bgptree.com/api/v1/asn/132986/neighbors?proto=all" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

#### Response (`200 OK`)
```json
{
  "focus_asn": {
    "asn": 132986,
    "name": "SYSTGRID-IN",
    "description": "SystGrid Solutions Pvt Ltd",
    "country": "IN",
    "registry": "apnic",
    "announced_v4": 8,
    "announced_v6": 4,
    "announced": true,
    "total_peers": 14,
    "updated_at": "2026-10-30T12:00:00Z"
  },
  "neighbors": [
    {
      "source_asn": 132986,
      "target_asn": 9498,
      "target_name": "BHARTI-AIRTEL",
      "target_country": "IN",
      "protocol": "both",
      "relation_type": "upstream",
      "v4_peers": 12,
      "v6_peers": 8,
      "peer_count": 20,
      "last_observed": "2026-10-30T12:00:00Z"
    },
    {
      "source_asn": 132986,
      "target_asn": 13335,
      "target_name": "CLOUDFLARENET",
      "target_country": "US",
      "protocol": "both",
      "relation_type": "peer",
      "v4_peers": 6,
      "v6_peers": 4,
      "peer_count": 10,
      "last_observed": "2026-10-30T12:00:00Z"
    }
  ],
  "total_v4_peers": 14,
  "total_v6_peers": 11,
  "dual_peers": 11
}
```

---

### 2.3 Internet Exchange Presences (`GET /asn/{asn}/ixps`)
Retrieves IXP colocation points, port capacity, assigned IPv4/IPv6 interface addresses, and route server peering status from PeeringDB.

#### Parameters
- `asn` (path parameter, required): The target ASN.

#### Curl Example
```bash
curl -s -X GET "https://api.bgptree.com/api/v1/asn/13335/ixps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

#### Response (`200 OK`)
```json
{
  "asn": 13335,
  "total": 2,
  "ixps": [
    {
      "id": 1024,
      "ix_id": 14,
      "name": "AMS-IX",
      "speed": 1000000,
      "ipaddr4": "80.249.208.247",
      "ipaddr6": "2001:7f8:1::a501:3335:1",
      "is_rs_peer": true,
      "operational": true
    },
    {
      "id": 1089,
      "ix_id": 28,
      "name": "DE-CIX Frankfurt",
      "speed": 800000,
      "ipaddr4": "80.81.192.152",
      "ipaddr6": "2001:7f8::1333:5:1",
      "is_rs_peer": true,
      "operational": true
    }
  ]
}
```

---

### 2.4 Multi-Hop BGP Propagation Tree (`GET /asn/{asn}/tree?proto=ipv4`)
Generates structured multi-hop directed graph hierarchy from the focus ASN through intermediate transit operators up to global Tier-1 backbones (e.g. Lumen, Telia/Arelion, NTT, Cogent, Tata Communications).

#### Parameters
- `asn` (path parameter, required): Target ASN.
- `proto` (query parameter, optional, default: `ipv4`): Routing protocol (`ipv4` or `ipv6`).

#### Curl Example
```bash
curl -s -X GET "https://api.bgptree.com/api/v1/asn/132986/tree?proto=ipv4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

#### Response (`200 OK`)
```json
{
  "focus_asn": 132986,
  "proto": "ipv4",
  "max_depth": 3,
  "nodes": [
    {
      "id": "132986",
      "asn": 132986,
      "name": "SYSTGRID-IN",
      "country": "IN",
      "depth": 0,
      "role": "origin"
    },
    {
      "id": "9498",
      "asn": 9498,
      "name": "BHARTI-AIRTEL",
      "country": "IN",
      "depth": 1,
      "role": "transit"
    },
    {
      "id": "1299",
      "asn": 1299,
      "name": "ARELION-EBONE",
      "country": "SE",
      "depth": 2,
      "role": "tier1"
    }
  ],
  "edges": [
    {
      "source": "132986",
      "target": "9498",
      "protocol": "ipv4",
      "relation_type": "upstream"
    },
    {
      "source": "9498",
      "target": "1299",
      "protocol": "ipv4",
      "relation_type": "upstream"
    }
  ]
}
```

---

### 2.5 ASN & Network Search (`GET /search?q={query}`)
Performs high-speed lookup across Autonomous System Numbers, operator names, and CIDR prefix ranges.

#### Parameters
- `q` (query parameter, required): Search query string (e.g. `13335`, `Cloudflare`, `Google`, `SystGrid`, `1.1.1.0/24`).

#### Curl Example
```bash
curl -s -X GET "https://api.bgptree.com/api/v1/search?q=SystGrid" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

#### Response (`200 OK`)
```json
{
  "query": "SystGrid",
  "results": [
    {
      "asn": 132986,
      "name": "SYSTGRID-IN",
      "description": "SystGrid Solutions Pvt Ltd - High Performance Cloud & Network Infrastructure",
      "country": "IN",
      "query_type": "name"
    }
  ]
}
```

---

## 3. Rate Limiting & Edge Defense

BGPTree implements multi-tiered rate limiting to guarantee high availability and prevent resource starvation.

### Thresholds
| Endpoint Category | Limit | Window | Scope |
| :--- | :--- | :--- | :--- |
| `POST /auth/session` | 20 requests | 1 minute | Client IP |
| Public Endpoints (`/health`, `/version`, `/sources`) | 60 requests | 1 minute | Client IP |
| Protected ASN Queries (`/asn/{asn}`, `/neighbors`, `/ixps`) | 300 requests | 1 minute | Session Token / IP |
| Computationally Intensive Graphs (`/asn/{asn}/tree`, `/graph/expand`) | 60 requests | 1 minute | Session Token / IP |

### Rate Limit Response (`429 Too Many Requests`)
When rate thresholds are exceeded, the API responds with HTTP status 429 and standard headers:
```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793392145

{
  "error": "Rate limit exceeded. Please back off and retry after 60 seconds."
}
```

---

## 4. Error Handling Specifications

All API errors return standardized JSON payloads with descriptive diagnostics.

### Common Error Codes

#### 400 Bad Request
Returned when required parameters are missing or malformed:
```json
{
  "error": "Invalid ASN parameter"
}
```
Or:
```json
{
  "error": "Query parameter 'q' is required"
}
```

#### 401 Unauthorized
Returned when the `Authorization` header is missing, improperly formatted, or has expired:
```json
{
  "error": "Authorization header required"
}
```
Or:
```json
{
  "error": "invalid token: token is expired"
}
```

#### 404 Not Found
Returned when an ASN does not exist or has never been allocated by any Regional Internet Registry (RIR):
```json
{
  "error": "ASN 4200000000 not found or unallocated"
}
```

#### 500 Internal Server Error
Returned during unrecoverable upstream errors or storage degradations:
```json
{
  "error": "Failed to fetch routing adjacency records from upstream telemetry source"
}
```

---

## 5. Provenance & Attributions

BGPTree normalizes and correlates BGP data from reputable global research foundations:
1. **RIPE NCC**: Routing Information Service (RIS) live dumps and RIPE Atlas measurement network.
2. **PeeringDB**: Global interconnection database and facility registry.
3. **CAIDA**: Center for Applied Internet Data Analysis (AS-Rank topological metrics).
4. **Regional Internet Registries**: Direct allocation registries from ARIN, RIPE, APNIC, LACNIC, and AFRINIC.

Detailed upstream terms and links are accessible at `https://bgptree.com/acknowledgements` and via `GET /sources`.