# Veeam Data Cloud Service Availability API - Complete Documentation for AI Agents

> Comprehensive guide for LLMs and AI agents to understand and effectively use the Veeam Data Cloud Service Availability API

## Table of Contents

1. [API Overview](#api-overview)
2. [Complete Endpoint Reference](#complete-endpoint-reference)
3. [Data Models & Schemas](#data-models--schemas)
4. [Query Patterns & Workflows](#query-patterns--workflows)
5. [Error Handling & Recovery](#error-handling--recovery)
6. [Business Logic & Rules](#business-logic--rules)
7. [Integration Examples](#integration-examples)

---

## API Overview

### Purpose
This API provides programmatic access to comprehensive data about Veeam Data Cloud (VDC) service availability across Amazon Web Services (AWS) and Microsoft Azure cloud regions worldwide. It enables automated discovery of where specific VDC services are available, filtering by cloud provider, geographic location, and service tier/edition requirements.

### Base Information
- **Base URL:** `/api/v1`
- **Protocol:** HTTPS
- **Response Format:** JSON only
- **Authentication:** None (public API)
- **API Version:** 1.0.0
- **OpenAPI Version:** 3.1.0
- **Total Regions:** 63 (27 AWS + 36 Azure as of 2026-01-03)

### Key Characteristics
- RESTful design with predictable resource-oriented URLs
- Standard HTTP response codes
- Consistent error response format
- CORS enabled for all origins
- Cache-Control headers for performance optimization
- All timestamps in ISO 8601 format

---

## Complete Endpoint Reference

### 1. GET /api/v1/regions

**Purpose:** Retrieve a comprehensive list of all cloud regions with VDC service availability, with powerful filtering capabilities.

**When to use:**
- Planning a new VDC deployment and need to identify suitable regions
- Checking which regions support specific service combinations
- Finding regions that meet data residency requirements
- Comparing service availability across cloud providers
- Building a multi-region disaster recovery strategy

**URL:** `GET /api/v1/regions`

**Query Parameters:**

| Parameter | Type | Required | Values | Description |
|-----------|------|----------|--------|-------------|
| provider | string | No | AWS, Azure | Filter by cloud provider. Omit to see both. |
| country | string | No | Any string | Search by country or location name. Matches region names and aliases (e.g., "Japan" finds Tokyo). Case-insensitive partial matching. |
| service | string | No | vdc_vault, vdc_m365, vdc_entra_id, vdc_salesforce, vdc_azure_backup | Show only regions where this service is available. |
| tier | string | No | Core, Non-Core | Filter Veeam Data Cloud Vault by pricing tier. Only applies to vdc_vault service. |
| edition | string | No | Foundation, Advanced | Filter Veeam Data Cloud Vault by edition. Only applies to vdc_vault service. |

**Filtering Logic:**
- All parameters are optional and can be combined
- Multiple filters use AND logic (all must match)
- Country search is case-insensitive and supports partial matching
- Tier and edition filters only affect Veeam Data Cloud Vault results
- Empty/no filters return all 63 regions

**Response Schema:**
```json
{
  "data": [
    {
      "id": "aws-us-east-1",
      "name": "US East 1 (N. Virginia)",
      "provider": "AWS",
      "coords": [38.9, -77.4],
      "aliases": ["Virginia", "N. Virginia", "US East", "IAD"],
      "services": {
        "vdc_vault": [
          {"edition": "Foundation", "tier": "Core"},
          {"edition": "Advanced", "tier": "Core"}
        ],
        "vdc_m365": true,
        "vdc_entra_id": true
      }
    }
  ],
  "count": 1,
  "filters": {
    "provider": null,
    "country": null,
    "service": null,
    "tier": null,
    "edition": null
  }
}
```

**Example Queries:**

1. **All AWS regions:**
   ```
   GET /api/v1/regions?provider=AWS
   ```

2. **Regions with Microsoft 365 backup:**
   ```
   GET /api/v1/regions?service=vdc_m365
   ```

3. **AWS regions with Veeam Data Cloud Vault Advanced/Core:**
   ```
   GET /api/v1/regions?provider=AWS&service=vdc_vault&edition=Advanced&tier=Core
   ```

4. **Regions in Japan:**
   ```
   GET /api/v1/regions?country=Japan
   ```

5. **Azure regions with Salesforce backup:**
   ```
   GET /api/v1/regions?provider=Azure&service=vdc_salesforce
   ```

**Response Codes:**
- `200 OK` - Success, returns matching regions (may be empty array)
- `400 Bad Request` - Invalid parameter value

**Common Errors:**
- Invalid provider (must be "AWS" or "Azure")
- Invalid service ID
- Invalid tier (must be "Core" or "Non-Core")
- Invalid edition (must be "Foundation" or "Advanced")

---

### 2. GET /api/v1/regions/{id}

**Purpose:** Retrieve complete details about a specific cloud region by its unique identifier.

**When to use:**
- You know the exact region ID and need detailed information
- Verifying service availability in a specific region
- Getting geographic coordinates for mapping
- Looking up alternative names for a region

**URL:** `GET /api/v1/regions/{id}`

**Path Parameters:**

| Parameter | Type | Required | Format | Description |
|-----------|------|----------|--------|-------------|
| id | string | Yes | {provider}-{region-code} | Unique region identifier (e.g., "aws-us-east-1", "azure-us-east") |

**Region ID Patterns:**
- AWS: `aws-{region-code}` (e.g., "aws-us-east-1", "aws-eu-west-1", "aws-ap-southeast-1")
- Azure: `azure-{location-name}` (e.g., "azure-us-east", "azure-europe-west", "azure-asia-southeast")

**Response Schema:**
```json
{
  "id": "aws-us-east-1",
  "name": "US East 1 (N. Virginia)",
  "provider": "AWS",
  "coords": [38.9, -77.4],
  "aliases": ["Virginia", "N. Virginia", "US East", "IAD"],
  "services": {
    "vdc_vault": [
      {"edition": "Foundation", "tier": "Core"},
      {"edition": "Advanced", "tier": "Core"}
    ],
    "vdc_m365": true,
    "vdc_entra_id": true,
    "vdc_salesforce": true
  }
}
```

**Example Queries:**

1. **Get AWS US East region:**
   ```
   GET /api/v1/regions/aws-us-east-1
   ```

2. **Get Azure West Europe region:**
   ```
   GET /api/v1/regions/azure-europe-west
   ```

**Response Codes:**
- `200 OK` - Region found and returned
- `404 Not Found` - Region ID doesn't exist

**Understanding Service Data:**
- **Tiered service (vdc_vault):** Returns array of available edition/tier combinations
- **Boolean services:** `true` = available, `false` or absent = not available
- Services not offered in region are typically omitted from the object

---

### 3. GET /api/v1/regions/nearest - Find Nearest Regions

**Purpose:** Find the N closest Veeam Data Cloud regions to any geographic location

**When to use:**
- Infrastructure planning: Find closest regions for disaster recovery
- Latency optimization: Identify nearest backup endpoints
- Multi-region strategy: Discover geographically distributed options
- Service discovery: Find closest regions with specific services

**URL:** `GET /api/v1/regions/nearest`

**Query Parameters:**

| Parameter | Type | Required | Values | Description |
|-----------|------|----------|--------|-------------|
| `lat` | float | Yes | -90 to 90 | Latitude of source location in decimal degrees |
| `lng` | float | Yes | -180 to 180 | Longitude of source location in decimal degrees |
| `limit` | integer | No | 0-20 | Max results to return. Default: 5, Max: 20, 0=unlimited |
| `provider` | string | No | `AWS`, `Azure` | Filter to specific cloud provider |
| `service` | string | No | `vdc_vault`, `vdc_m365`, `vdc_entra_id`, `vdc_salesforce`, `vdc_azure_backup` | Filter to regions offering this service |
| `tier` | string | No | `Core`, `Non-Core` | Filter vdc_vault by tier (requires `service=vdc_vault`) |
| `edition` | string | No | `Foundation`, `Advanced` | Filter vdc_vault by edition (requires `service=vdc_vault`) |

**Important Validation Rules:**
- `tier` and `edition` are ONLY valid when `service=vdc_vault`
- Passing `tier` or `edition` without `service=vdc_vault` returns 400 error
- Provider is case-sensitive: must be exactly `AWS` or `Azure`

**Response Schema:**

```json
{
  "query": {
    "lat": 35.6762,
    "lng": 139.6503,
    "limit": 5,
    "service": "vdc_vault",
    "provider": "AWS",
    "tier": "Core",
    "edition": null
  },
  "results": [
    {
      "region": {
        "id": "aws-ap-northeast-1",
        "name": "Asia Pacific (Tokyo)",
        "provider": "AWS",
        "coords": [35.6762, 139.2],
        "aliases": ["Tokyo", "Japan"],
        "services": {
          "vdc_vault": [
            { "edition": "Foundation", "tier": "Core" },
            { "edition": "Advanced", "tier": "Core" }
          ],
          "vdc_m365": true
        }
      },
      "distance": {
        "km": 42.15,
        "miles": 26.19
      }
    }
  ],
  "count": 1
}
```

**Distance Calculation:**
- Uses Haversine formula for great-circle distance
- Accurate for Earth's spherical approximation
- Returns distances rounded to 2 decimal places

**Sorting & Tie-Breaking:**
- Results sorted by distance ascending (closest first)
- Equal distances tie-break by region.id alphabetically
- Guarantees deterministic ordering

**Example Queries:**

1. Find 3 closest regions to Tokyo:
   ```
   GET /api/v1/regions/nearest?lat=35.6762&lng=139.6503&limit=3
   ```

2. Find closest AWS regions with vdc_vault:
   ```
   GET /api/v1/regions/nearest?lat=40.7128&lng=-74.0060&provider=AWS&service=vdc_vault
   ```

3. Find all Azure regions sorted by distance (unlimited):
   ```
   GET /api/v1/regions/nearest?lat=51.5074&lng=-0.1278&provider=Azure&limit=0
   ```

4. Find closest Core tier vdc_vault regions:
   ```
   GET /api/v1/regions/nearest?lat=37.7749&lng=-122.4194&service=vdc_vault&tier=Core&limit=10
   ```

5. Find closest Advanced edition Core tier regions:
   ```
   GET /api/v1/regions/nearest?lat=0&lng=0&service=vdc_vault&tier=Core&edition=Advanced
   ```

**Response Codes:**

- `200 OK` - Successfully found nearest regions (may return 0 results if filters exclude all)
- `400 Bad Request` - Invalid coordinates, limit out of range, or invalid filter combination

**Common Error Scenarios:**

```json
{
  "error": "Invalid parameter combination",
  "code": "INVALID_PARAMETER",
  "message": "tier and edition parameters are only valid with service=vdc_vault",
  "parameter": "tier",
  "value": "Core"
}
```

**Use Cases:**

1. **Disaster Recovery Planning:** Find 3-5 geographically distributed regions
2. **Latency Optimization:** Identify single closest region for primary backup
3. **Multi-Cloud Strategy:** Compare AWS vs Azure closest regions
4. **Service Availability:** Check which nearby regions offer specific services
5. **Cost Optimization:** Filter by Core tier to find most cost-effective nearby regions

---

### 4. GET /api/v1/regions/compare - Compare Multiple Regions

**Purpose:** Compare service availability across 2-5 cloud regions to identify differences and commonalities, helping users make informed decisions when planning multi-region or hybrid cloud deployments.

**When to use:**
- Planning multi-region disaster recovery deployments
- Comparing regions across cloud providers (AWS vs Azure)
- Selecting a primary region based on service requirements
- Identifying service gaps before deployment
- Analyzing hybrid cloud deployment options
- Building region selection tools or dashboards
- Automating deployment validation checks

**URL:** `GET /api/v1/regions/compare`

**Query Parameters:**

| Parameter | Type | Required | Values | Description |
|-----------|------|----------|--------|-------------|
| `ids` | string | Yes | Comma-separated region IDs | List of 2-5 region IDs to compare (e.g., "aws-us-east-1,azure-us-east") |

**Validation Rules:**
- Minimum 2 region IDs required
- Maximum 5 region IDs allowed (prevents overly large responses)
- All region IDs must exist (returns 404 if any are invalid)
- Duplicate IDs are automatically deduplicated
- Whitespace around IDs is trimmed
- Region IDs are case-sensitive

**Response Schema:**

```json
{
  "regions": [
    {
      "id": "aws-us-east-1",
      "name": "US East 1 (N. Virginia)",
      "provider": "AWS",
      "coords": [38.9, -77.4],
      "services": { "vdc_vault": [...], "vdc_m365": true }
    },
    {
      "id": "azure-us-east",
      "name": "East US (Virginia)",
      "provider": "Azure",
      "coords": [37.3719, -79.8164],
      "services": { "vdc_vault": [...], "vdc_azure_backup": true }
    }
  ],
  "comparison": {
    "vdc_vault": {
      "availableIn": ["aws-us-east-1", "azure-us-east"],
      "missingFrom": [],
      "isCommon": true,
      "details": {
        "aws-us-east-1": [
          { "edition": "Foundation", "tier": "Core" },
          { "edition": "Advanced", "tier": "Core" }
        ],
        "azure-us-east": [
          { "edition": "Foundation", "tier": "Non-Core" },
          { "edition": "Advanced", "tier": "Core" }
        ]
      }
    },
    "vdc_m365": {
      "availableIn": ["azure-us-east"],
      "missingFrom": ["aws-us-east-1"],
      "isCommon": false,
      "details": {
        "azure-us-east": true
      }
    },
    "vdc_entra_id": {
      "availableIn": [],
      "missingFrom": ["aws-us-east-1", "azure-us-east"],
      "isCommon": false,
      "details": {}
    }
  },
  "summary": {
    "totalServices": 5,
    "commonServices": 2,
    "partialServices": 2,
    "unavailableServices": 1,
    "commonServiceIds": ["vdc_vault", "vdc_azure_backup"],
    "partialServiceIds": ["vdc_m365", "vdc_salesforce"],
    "unavailableServiceIds": ["vdc_entra_id"]
  }
}
```

**Response Field Explanations:**

1. **regions** - Full details of all compared regions (same structure as GET /api/v1/regions/{id})

2. **comparison** - Service-by-service breakdown:
   - **availableIn** - Array of region IDs where service is available
   - **missingFrom** - Array of region IDs where service is NOT available
   - **isCommon** - `true` if service is available in ALL compared regions
   - **details** - Service configuration per region:
     - For tiered services (vdc_vault): Array of edition/tier combinations
     - For boolean services: `true` if available
     - Missing from details = not available in that region

3. **summary** - High-level statistics:
   - **totalServices** - Total VDC services analyzed (always 5)
   - **commonServices** - Services available in ALL regions
   - **partialServices** - Services available in SOME but not all regions
   - **unavailableServices** - Services not available in ANY region
   - **commonServiceIds/partialServiceIds/unavailableServiceIds** - Lists of service IDs in each category

**Example Queries:**

1. **Compare US East regions across providers:**
   ```
   GET /api/v1/regions/compare?ids=aws-us-east-1,azure-us-east
   ```
   Use case: Hybrid cloud planning, comparing AWS vs Azure in same geographic area

2. **Multi-region disaster recovery planning:**
   ```
   GET /api/v1/regions/compare?ids=aws-us-east-1,aws-eu-west-2,aws-ap-northeast-1
   ```
   Use case: Identify common services across 3 continents for global DR strategy

3. **Hybrid Azure deployment:**
   ```
   GET /api/v1/regions/compare?ids=azure-us-east,azure-west-europe,azure-au-east
   ```
   Use case: Ensure required services available across Azure regions

4. **Maximum comparison (5 regions):**
   ```
   GET /api/v1/regions/compare?ids=aws-us-east-1,azure-us-east,aws-eu-west-2,aws-ap-northeast-1,azure-west-europe
   ```
   Use case: Comprehensive multi-region, multi-provider analysis

**Response Codes:**

- `200 OK` - Successful comparison
- `400 Bad Request` - Less than 2 or more than 5 region IDs provided
- `404 Not Found` - One or more region IDs don't exist

**Error Examples:**

```json
{
  "error": "Invalid parameter",
  "code": "INVALID_PARAMETER",
  "message": "At least 2 region IDs are required for comparison",
  "parameter": "ids",
  "value": "aws-us-east-1"
}
```

```json
{
  "error": "Region not found",
  "code": "REGION_NOT_FOUND",
  "message": "The following region IDs were not found: invalid-region, another-invalid",
  "parameter": "ids",
  "value": "aws-us-east-1,invalid-region,another-invalid",
  "allowedValues": ["invalid-region", "another-invalid"]
}
```

**Use Cases & Patterns:**

1. **Pre-deployment Validation:**
   - Compare target regions to ensure all required services are available
   - Identify service gaps that could block deployment

2. **Cost Analysis:**
   - Compare vdc_vault tier availability (Core vs Non-Core)
   - Identify regions with cost-optimized service options

3. **Feature Parity Checks:**
   - Ensure all regions in a deployment have same service capabilities
   - Flag regions with partial service availability

4. **Decision Support:**
   - Show users side-by-side comparison when selecting regions
   - Highlight differences to inform region selection

5. **Automated Deployment:**
   - Pre-flight check: verify services available before deployment
   - Fail fast if required services missing

**Integration Tips:**

- Cache comparison results for frequently compared region sets
- Use `summary.commonServiceIds` to quickly identify universally available services
- Check `comparison[serviceId].isCommon === true` to validate service requirements
- Use `details` to show specific tier/edition differences in UI
- Process `missingFrom` array to warn users about service gaps

---

### 5. GET /api/v1/services

**Purpose:** Retrieve metadata about all Veeam Data Cloud services with comprehensive regional availability statistics.

**When to use:**
- Discovering what VDC services exist
- Understanding service types (tiered vs boolean)
- Comparing service coverage across VDC offerings
- Finding which services have the widest availability
- Understanding distribution across cloud providers
- Building UI dropdowns or service selection menus
- Learning which services support editions and tiers

**URL:** `GET /api/v1/services`

**Parameters:** None

**Response Schema:**
```json
{
  "services": [
    {
      "id": "vdc_vault",
      "name": "Veeam Data Cloud Vault",
      "type": "tiered",
      "description": "Immutable backup storage with configurable pricing tiers",
      "editions": ["Foundation", "Advanced"],
      "tiers": ["Core", "Non-Core"],
      "regionCount": 80,
      "providerBreakdown": {
        "AWS": 45,
        "Azure": 35
      },
      "configurationBreakdown": {
        "Foundation-Core": 12,
        "Advanced-Core": 45,
        "Foundation-Non-Core": 8,
        "Advanced-Non-Core": 15
      }
    },
    {
      "id": "vdc_m365",
      "name": "Microsoft 365 Protection",
      "type": "boolean",
      "description": "Backup and recovery for Microsoft 365 data",
      "regionCount": 23,
      "providerBreakdown": {
        "AWS": 0,
        "Azure": 23
      }
    },
    {
      "id": "vdc_entra_id",
      "name": "Microsoft Entra ID Protection",
      "type": "boolean",
      "description": "Backup and recovery for Microsoft Entra ID (formerly Azure AD)",
      "regionCount": 23,
      "providerBreakdown": {
        "AWS": 0,
        "Azure": 23
      }
    },
    {
      "id": "vdc_salesforce",
      "name": "Salesforce Protection",
      "type": "boolean",
      "description": "Backup and recovery for Salesforce data",
      "regionCount": 12,
      "providerBreakdown": {
        "AWS": 5,
        "Azure": 7
      }
    },
    {
      "id": "vdc_azure_backup",
      "name": "Microsoft Azure Protection",
      "type": "boolean",
      "description": "Native Azure backup capabilities",
      "regionCount": 36,
      "providerBreakdown": {
        "AWS": 0,
        "Azure": 36
      }
    }
  ],
  "count": 5
}
```

**Response Fields Explained:**

- **regionCount**: Total number of regions where this service is available. Use to quickly compare service coverage.
- **providerBreakdown**: Count of AWS vs Azure regions offering the service. Helps understand cloud provider distribution.
- **configurationBreakdown**: (Tiered services only) Count of regions per edition-tier combination. Keys follow "Edition-Tier" format (e.g., "Foundation-Core", "Advanced-Non-Core"). Use to find how many regions support specific configurations.
- **count**: Total number of services returned (always 5 currently)

**Service Details:**

1. **Veeam Data Cloud Vault** (vdc_vault)
   - Type: Tiered
   - Purpose: Object storage backup repository
   - Editions: Foundation (entry-level), Advanced (full-featured)
   - Tiers: Core (premium performance), Non-Core (cost-optimized)

2. **Microsoft 365 Protection** (vdc_m365)
   - Type: Boolean
   - Purpose: Backup for Exchange Online, SharePoint Online, OneDrive, Teams

3. **Microsoft Entra ID Protection** (vdc_entra_id)
   - Type: Boolean
   - Purpose: Microsoft Entra ID (formerly Azure AD) backup

4. **Salesforce Protection** (vdc_salesforce)
   - Type: Boolean
   - Purpose: Salesforce CRM data protection

5. **Microsoft Azure Protection** (vdc_azure_backup)
   - Type: Boolean
   - Purpose: Azure VM and resource backup

**Response Codes:**
- `200 OK` - Always returns successfully with complete service list

**Use Cases:**

1. **Compare service availability**: Quickly see that Veeam Data Cloud Vault has 80 regions while Salesforce Protection has only 12
2. **Understand provider distribution**: See that M365/Entra ID are Azure-only while Veeam Data Cloud Vault spans both providers
3. **Configuration planning**: Check configurationBreakdown to see how many regions support Advanced-Core tier

---

### 6. GET /api/v1/services/{serviceId}

**Purpose:** Retrieve comprehensive details about a specific VDC service, including complete lists of all regions where the service is available and detailed breakdowns by cloud provider and configuration.

**When to use:**
- Get all regions supporting a specific service
- Find which regions support specific edition-tier combinations
- Understand geographic distribution of a service
- Build deployment plans for specific services
- Verify service availability details

**URL:** `GET /api/v1/services/{serviceId}`

**Path Parameters:**

| Parameter | Type | Required | Values | Description |
|-----------|------|----------|--------|-------------|
| serviceId | string | Yes | vdc_vault, vdc_m365, vdc_entra_id, vdc_salesforce, vdc_azure_backup | Unique identifier for the VDC service |

**Response Schema (Boolean Service - e.g., vdc_m365):**
```json
{
  "service": {
    "id": "vdc_m365",
    "name": "Microsoft 365 Protection",
    "type": "boolean",
    "description": "Backup and recovery for Microsoft 365 data",
    "regionCount": 23
  },
  "regions": [
    "azure-au-east",
    "azure-brazil-south",
    "azure-canada-central"
  ],
  "providerBreakdown": {
    "AWS": {
      "count": 0,
      "regions": []
    },
    "Azure": {
      "count": 23,
      "regions": [
        "azure-au-east",
        "azure-brazil-south",
        "azure-canada-central"
      ]
    }
  }
}
```

**Response Schema (Tiered Service - vdc_vault):**
```json
{
  "service": {
    "id": "vdc_vault",
    "name": "Veeam Data Cloud Vault",
    "type": "tiered",
    "description": "Immutable backup storage with configurable pricing tiers",
    "editions": ["Foundation", "Advanced"],
    "tiers": ["Core", "Non-Core"],
    "regionCount": 80
  },
  "regions": [
    "aws-af-south-1",
    "aws-ap-east-1",
    "aws-eu-north-1"
  ],
  "providerBreakdown": {
    "AWS": {
      "count": 45,
      "regions": [
        "aws-af-south-1",
        "aws-ap-east-1",
        "aws-eu-north-1"
      ]
    },
    "Azure": {
      "count": 35,
      "regions": [
        "azure-au-east",
        "azure-brazil-south"
      ]
    }
  },
  "configurationBreakdown": {
    "Foundation-Core": {
      "count": 12,
      "regions": [
        "aws-eu-north-1",
        "aws-eu-south-2"
      ]
    },
    "Advanced-Core": {
      "count": 45,
      "regions": [
        "aws-af-south-1",
        "aws-ap-east-1"
      ]
    },
    "Foundation-Non-Core": {
      "count": 8,
      "regions": [
        "aws-us-west-1"
      ]
    },
    "Advanced-Non-Core": {
      "count": 15,
      "regions": [
        "aws-us-east-1"
      ]
    }
  }
}
```

**Response Fields Explained:**

- **service**: Complete service metadata including type, description, and total region count
- **regions**: Array of all region IDs where this service is available. Use these IDs with `/api/v1/regions/{id}` for full region details.
- **providerBreakdown**: Detailed breakdown by cloud provider including both counts and complete region ID lists
- **configurationBreakdown**: (Tiered services only) Breakdown by edition-tier combination with counts and complete region ID lists. Keys follow "Edition-Tier" format.

**Example Queries:**

1. **Get all M365 regions:**
   ```
   GET /api/v1/services/vdc_m365
   ```

2. **Get Veeam Data Cloud Vault distribution:**
   ```
   GET /api/v1/services/vdc_vault
   ```

3. **Check Salesforce availability:**
   ```
   GET /api/v1/services/vdc_salesforce
   ```

**Response Codes:**
- `200 OK` - Service found and details returned
- `404 Not Found` - Invalid service ID

**Error Response (404):**
```json
{
  "error": "Service not found",
  "code": "SERVICE_NOT_FOUND",
  "message": "Service with ID 'invalid_service' does not exist",
  "parameter": "serviceId",
  "value": "invalid_service",
  "allowedValues": [
    "vdc_vault",
    "vdc_m365",
    "vdc_entra_id",
    "vdc_salesforce",
    "vdc_azure_backup"
  ]
}
```

**Use Cases:**

1. **List all regions for a service**: Use the `regions` array to get all region IDs
2. **Find provider-specific regions**: Check `providerBreakdown.AWS.regions` or `providerBreakdown.Azure.regions`
3. **Configuration-specific planning**: For Veeam Data Cloud Vault, use `configurationBreakdown["Advanced-Core"].regions` to find regions supporting specific configurations
4. **Build deployment matrices**: Combine with `/api/v1/regions/{id}` to get full geographic details for each region

---

### 7. GET /api/v1/health

**Purpose:** Comprehensive health check that validates API functionality and data availability.

**When to use:**
- Health monitoring in production systems
- Getting current region statistics
- Troubleshooting data loading issues
- Dashboard status displays

**URL:** `GET /api/v1/health`

**Parameters:** None

**Response Schema:**
```json
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-01-03T10:30:00Z",
  "stats": {
    "totalRegions": 63,
    "awsRegions": 27,
    "azureRegions": 36
  }
}
```

**Status Values:**
- `healthy` - API fully operational with all data loaded
- `degraded` - API responding but with reduced functionality
- `unhealthy` - Critical errors preventing normal operation

**Response Codes:**
- `200 OK` - Health check completed (check status field for details)
- `500 Internal Server Error` - Critical failure

---

### 8. GET /api/v1/ping

**Purpose:** Lightweight connectivity test with no data dependencies.

**When to use:**
- Quick connectivity tests
- Monitoring system health checks
- CI/CD pipeline validation
- Network troubleshooting

**URL:** `GET /api/v1/ping`

**Parameters:** None

**Response Schema:**
```json
{
  "status": "ok",
  "message": "Cloudflare Pages Functions are working!",
  "timestamp": "2026-01-03T10:30:00Z",
  "environment": "production"
}
```

**Response Fields:**
- `status`: Always "ok" if the endpoint is reachable
- `message`: Confirmation message about API functionality
- `timestamp`: Current server time in ISO 8601 format
- `environment`: Deployment environment. Possible values:
  - `"production"` - Production deployment
  - `"preview"` - Preview/staging deployment (Cloudflare Pages preview branches)
  - `"local"` - Local development environment

**Response Codes:**
- `200 OK` - API is reachable and responding

**Note:** This endpoint will respond even if the region database is unavailable, making it ideal for basic connectivity checks.

---

## Data Models & Schemas

### Region Object

```typescript
interface Region {
  id: string;              // Unique identifier (e.g., "aws-us-east-1")
  name: string;            // Human-readable name (e.g., "US East 1 (N. Virginia)")
  provider: "AWS" | "Azure";  // Cloud provider
  coords: [number, number];   // [latitude, longitude]
  aliases?: string[];      // Alternative names for searching
  services: Services;      // Available VDC services
}
```

**Field Details:**

- **id**: Format is `{provider}-{region-code}`. Stable identifier that never changes.
- **name**: Official region name from cloud provider. Display this to users.
- **provider**: Either "AWS" or "Azure". Use for grouping/filtering.
- **coords**: Geographic coordinates as [lat, lng]. Approximate data center location.
- **aliases**: Optional array of alternative names, country names, airport codes, etc.
- **services**: Object with VDC service availability (see below).

### Services Object

```typescript
interface Services {
  vdc_vault?: VaultService[];     // Tiered service
  vdc_m365?: boolean;             // Boolean service
  vdc_entra_id?: boolean;         // Boolean service
  vdc_salesforce?: boolean;       // Boolean service
  vdc_azure_backup?: boolean;     // Boolean service
}

interface VaultService {
  edition: "Foundation" | "Advanced";
  tier: "Core" | "Non-Core";
}
```

**Understanding Service Data:**

1. **Tiered Service (Veeam Data Cloud Vault)**:
   - Represented as array of edition/tier combinations
   - Region may offer multiple combinations
   - Example: `[{edition: "Foundation", tier: "Core"}, {edition: "Advanced", tier: "Core"}]`
   - Absent = service not available in region

2. **Boolean Services**:
   - `true` = service available
   - `false` or property absent = service not available
   - No variation in features or pricing

### Service Object

```typescript
interface Service {
  id: string;                    // Service identifier (e.g., "vdc_vault")
  name: string;                  // Display name
  type: "tiered" | "boolean";    // Availability type
  editions?: string[];           // Only for tiered services
  tiers?: string[];              // Only for tiered services
}
```

### Error Object

```typescript
interface Error {
  error: string;       // Short error title
  code: string;        // Machine-readable error code
  message: string;     // Detailed explanation
  parameter?: string;  // Parameter that caused error
  value?: string;      // Invalid value provided
}
```

**Common Error Codes:**
- `REGION_NOT_FOUND` - Region ID doesn't exist
- `SERVICE_NOT_FOUND` - Service ID doesn't exist
- `INVALID_PARAMETER` - General parameter validation failure
- `INVALID_PROVIDER` - Provider must be "AWS" or "Azure"
- `INVALID_SERVICE` - Service ID not recognized
- `INVALID_TIER` - Tier must be "Core" or "Non-Core"
- `INVALID_EDITION` - Edition must be "Foundation" or "Advanced"

---

## Query Patterns & Workflows

### Common Workflow Patterns

#### 1. Discover Available Services
```
Step 1: GET /api/v1/services
Step 2: Review service types, options, and regional statistics
Step 3: Compare regionCount and providerBreakdown across services
Step 4: Use service IDs in detailed queries or region filters
```

#### 2. Find Regions for Specific Service
```
Method A - Using service detail endpoint:
Step 1: GET /api/v1/services/vdc_m365
Step 2: Review regions array for complete list of region IDs
Step 3: Check providerBreakdown to see AWS vs Azure distribution
Step 4: Optionally fetch full region details: GET /api/v1/regions/{id}

Method B - Using regions endpoint with filter:
Step 1: GET /api/v1/regions?service=vdc_m365
Step 2: Filter results by provider if needed
Step 3: Select region based on geography/latency
```

#### 3. Check Service Availability in Known Region
```
Step 1: GET /api/v1/regions/aws-us-east-1
Step 2: Check services object for required service
Step 3: Verify edition/tier if using Veeam Data Cloud Vault
```

#### 4. Find Nearest Region with Required Service
```
Step 1: GET /api/v1/regions?service={required_service}
Step 2: Calculate distance using coords field
Step 3: Sort by distance to user location
Step 4: Select nearest region
```

#### 5. Multi-Region Deployment Planning
```
Method A - Using service detail endpoint:
Step 1: GET /api/v1/services/vdc_vault
Step 2: Review configurationBreakdown["Advanced-Core"].regions for all matching regions
Step 3: Group by provider using providerBreakdown
Step 4: Select regions across different geographies
Step 5: Fetch full details: GET /api/v1/regions/{id} for each selected region

Method B - Using regions filter:
Step 1: GET /api/v1/regions?service=vdc_vault&edition=Advanced&tier=Core
Step 2: Group by provider for cost comparison
Step 3: Select regions across different geographies
Step 4: Verify each region: GET /api/v1/regions/{id}
```

### Advanced Query Patterns

#### Find Regions by Data Residency Requirements
```
GET /api/v1/regions?country=Germany
GET /api/v1/regions?country=Europe
GET /api/v1/regions?country=Canada
```

#### Compare Cloud Provider Options
```
Step 1: GET /api/v1/regions?provider=AWS&service=vdc_vault&tier=Core
Step 2: GET /api/v1/regions?provider=Azure&service=vdc_vault&tier=Core
Step 3: Compare counts and geographic distribution
```

#### Find Cost-Optimized Regions
```
GET /api/v1/regions?service=vdc_vault&tier=Non-Core
```

#### Find Premium Performance Regions
```
GET /api/v1/regions?service=vdc_vault&tier=Core
```

---

## Error Handling & Recovery

### Error Response Format

All errors return appropriate HTTP status codes with structured JSON:

```json
{
  "error": "Invalid parameter",
  "code": "INVALID_PROVIDER",
  "message": "Provider must be either 'AWS' or 'Azure'. Received: 'GCP'",
  "parameter": "provider",
  "value": "GCP"
}
```

### Automatic Recovery Strategies

#### Strategy 1: Parameter Validation Errors (400)
```
1. Parse error.message field for guidance
2. Check error.parameter and error.value
3. Correct the parameter value
4. Retry request with corrected value
```

Example:
```
Error: "Provider must be either 'AWS' or 'Azure'. Received: 'GCP'"
Action: Replace 'GCP' with 'AWS' or 'Azure' and retry
```

#### Strategy 2: Region Not Found (404)
```
1. Check if region ID format is correct ({provider}-{code})
2. Try searching instead: GET /api/v1/regions?country={search_term}
3. Use returned region IDs for specific queries
```

#### Strategy 3: Service Not Found (404)
```
1. Check if service ID format is correct
2. Try getting all services: GET /api/v1/services
3. Use returned service IDs for specific queries
```

#### Strategy 4: Service Not Available in Region
```
1. GET /api/v1/regions/{id} returns region but missing service
2. Service not available - search for alternative regions
3. GET /api/v1/services/{service_id} to see all regions with service
4. Or GET /api/v1/regions?service={required_service}
```

### Validation Rules

**Provider Parameter:**
- Must be exactly "AWS" or "Azure"
- Case-sensitive
- No other values accepted

**Service Parameter:**
- Must be one of: vdc_vault, vdc_m365, vdc_entra_id, vdc_salesforce, vdc_azure_backup
- Case-sensitive
- Exact match required

**Tier Parameter:**
- Must be exactly "Core" or "Non-Core"
- Only valid with vdc_vault service
- Case-sensitive

**Edition Parameter:**
- Must be exactly "Foundation" or "Advanced"
- Only valid with vdc_vault service
- Case-sensitive

**Country Parameter:**
- Any string accepted
- Case-insensitive matching
- Supports partial matching
- Searches both names and aliases

**Region ID Path Parameter:**
- Format: `{provider}-{region-code}`
- Must match existing region exactly
- Case-sensitive

---

## Business Logic & Rules

### Service Availability Rules

1. **Veeam Data Cloud Vault (Tiered Service)**
   - Can have multiple edition/tier combinations per region
   - Not all combinations available in all regions
   - Typical pattern: both editions in Core tier, fewer in Non-Core
   - Filtering by edition/tier shows regions with ANY matching combination

2. **Boolean Services**
   - Simple presence/absence model
   - No variations in features or pricing
   - Either available (true) or not (absent/false)

3. **Regional Patterns**
   - Not all services available in all regions
   - Major/popular regions tend to have more services
   - New regions may have limited service availability
   - Some services are cloud-provider specific

### Filter Combination Logic

When multiple filters are applied:
```
AND logic: ALL conditions must be met
Example: provider=AWS&service=vdc_vault&tier=Core
Returns: AWS regions that have Veeam Data Cloud Vault with Core tier
```

Special cases:
- `tier` without `service` - filters only Veeam Data Cloud Vault
- `edition` without `service` - filters only Veeam Data Cloud Vault
- Empty result set is valid (no matching regions)

### Data Freshness

- Data is compiled at build time from YAML source files
- Updates require rebuilding and redeploying
- Check `/api/v1/health` for current region counts
- This is not real-time data - community-maintained

### Geographic Search Behavior

Country parameter uses fuzzy matching:
```
"Japan" matches:
- "Asia Pacific (Tokyo)"
- "Asia Pacific (Osaka)"

"virgin" matches:
- "US East 1 (N. Virginia)"

"europe" matches:
- "Europe (London)"
- "Europe (Paris)"
- "Europe West"
- etc.
```

---

## Integration Examples

### Example 1: Find Nearest Region for Service

```python
import requests
import math

def haversine_distance(lat1, lon1, lat2, lon2):
    """Calculate distance between two points in km"""
    R = 6371  # Earth radius in km

    lat1, lon1, lat2, lon2 = map(math.radians, [lat1, lon1, lat2, lon2])
    dlat = lat2 - lat1
    dlon = lon2 - lon1

    a = math.sin(dlat/2)**2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon/2)**2
    c = 2 * math.asin(math.sqrt(a))

    return R * c

def find_nearest_region(user_lat, user_lon, service):
    """Find nearest region offering specified service"""

    # Get all regions with the service
    response = requests.get(f"/api/v1/regions?service={service}")
    data = response.json()

    nearest = None
    min_distance = float('inf')

    for region in data['data']:
        lat, lon = region['coords']
        distance = haversine_distance(user_lat, user_lon, lat, lon)

        if distance < min_distance:
            min_distance = distance
            nearest = region

    return nearest, min_distance

# Usage
region, distance = find_nearest_region(51.5074, -0.1278, 'vdc_m365')
print(f"Nearest region: {region['name']} ({distance:.0f} km away)")
```

### Example 2: Multi-Cloud Comparison

```javascript
async function compareProviders(service) {
  // Get AWS regions
  const awsResponse = await fetch(`/api/v1/regions?provider=AWS&service=${service}`);
  const awsData = await awsResponse.json();

  // Get Azure regions
  const azureResponse = await fetch(`/api/v1/regions?provider=Azure&service=${service}`);
  const azureData = await azureResponse.json();

  return {
    aws: {
      count: awsData.count,
      regions: awsData.data.map(r => r.name)
    },
    azure: {
      count: azureData.count,
      regions: azureData.data.map(r => r.name)
    }
  };
}

// Usage
const comparison = await compareProviders('vdc_vault');
console.log(`AWS: ${comparison.aws.count} regions`);
console.log(`Azure: ${comparison.azure.count} regions`);
```

### Example 3: Data Residency Compliance

```javascript
async function findCompliantRegions(country, requiredServices) {
  // Find regions in the country
  const response = await fetch(`/api/v1/regions?country=${country}`);
  const data = await response.json();

  // Filter regions that have ALL required services
  const compliant = data.data.filter(region => {
    return requiredServices.every(service => {
      if (service === 'vdc_vault') {
        // Tiered service - check if array exists and has items
        return Array.isArray(region.services.vdc_vault) && region.services.vdc_vault.length > 0;
      } else {
        // Boolean service - check if true
        return region.services[service] === true;
      }
    });
  });

  return compliant;
}

// Usage
const regions = await findCompliantRegions('Germany', ['vdc_vault', 'vdc_m365']);
console.log(`Found ${regions.length} compliant regions in Germany`);
```

### Example 4: Automatic Error Recovery

```python
import requests
import time

def query_with_retry(url, max_retries=3):
    """Query API with automatic error recovery"""

    for attempt in range(max_retries):
        try:
            response = requests.get(url)

            if response.status_code == 200:
                return response.json()

            elif response.status_code == 400:
                error = response.json()

                # Automatic correction for common mistakes
                if error['code'] == 'INVALID_PROVIDER' and 'GCP' in error.get('value', ''):
                    # User likely meant cloud provider - try AWS first
                    corrected_url = url.replace('GCP', 'AWS')
                    print(f"Auto-correcting: {error['message']}")
                    response = requests.get(corrected_url)
                    if response.status_code == 200:
                        return response.json()

                # If can't auto-correct, raise the error
                raise ValueError(error['message'])

            elif response.status_code == 404:
                error = response.json()
                raise ValueError(f"Not found: {error['message']}")

            else:
                # Unexpected error, retry
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)  # Exponential backoff
                    continue
                else:
                    response.raise_for_status()

        except requests.RequestException as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise

    raise Exception("Max retries exceeded")

# Usage
try:
    data = query_with_retry('/api/v1/regions?provider=GCP')
except ValueError as e:
    print(f"Error: {e}")
```

### Example 5: Service Coverage Analysis

```javascript
async function analyzeServiceCoverage() {
  // Get all services with statistics
  const servicesResp = await fetch('/api/v1/services');
  const servicesData = await servicesResp.json();

  // Analyze and compare
  const analysis = servicesData.services.map(service => ({
    name: service.name,
    totalRegions: service.regionCount,
    awsRegions: service.providerBreakdown.AWS,
    azureRegions: service.providerBreakdown.Azure,
    coverage: (service.regionCount / 63 * 100).toFixed(1) + '%', // 63 total regions
    configurations: service.configurationBreakdown
      ? Object.keys(service.configurationBreakdown).length
      : null
  }));

  // Sort by coverage
  analysis.sort((a, b) => b.totalRegions - a.totalRegions);

  return analysis;
}

// Get detailed regions for a specific service
async function getServiceRegionDetails(serviceId) {
  // Get service detail with region lists
  const serviceResp = await fetch(`/api/v1/services/${serviceId}`);
  const serviceData = await serviceResp.json();

  // For Veeam Data Cloud Vault, find regions supporting Advanced-Core
  if (serviceId === 'vdc_vault' && serviceData.configurationBreakdown) {
    const advancedCoreRegions = serviceData.configurationBreakdown['Advanced-Core'].regions;

    console.log(`Found ${advancedCoreRegions.length} regions with Advanced-Core`);

    // Optionally fetch full details for each region
    const regionDetails = await Promise.all(
      advancedCoreRegions.slice(0, 5).map(async (regionId) => {
        const regionResp = await fetch(`/api/v1/regions/${regionId}`);
        return regionResp.json();
      })
    );

    return regionDetails;
  }

  return serviceData.regions;
}

// Usage
const coverage = await analyzeServiceCoverage();
console.log('Service coverage analysis:', coverage);

const vaultRegions = await getServiceRegionDetails('vdc_vault');
console.log('Veeam Data Cloud Vault Advanced-Core regions:', vaultRegions);
```

### Example 6: Building Region Selector UI

```javascript
async function buildRegionSelector(container, serviceFilter = null) {
  // Get services first
  const servicesResp = await fetch('/api/v1/services');
  const servicesData = await servicesResp.json();

  // Build URL with optional service filter
  let url = '/api/v1/regions';
  if (serviceFilter) {
    url += `?service=${serviceFilter}`;
  }

  // Get regions
  const regionsResp = await fetch(url);
  const regionsData = await regionsResp.json();

  // Group by provider
  const byProvider = regionsData.data.reduce((acc, region) => {
    if (!acc[region.provider]) acc[region.provider] = [];
    acc[region.provider].push(region);
    return acc;
  }, {});

  // Build HTML
  let html = '<select id="region-selector">';

  for (const [provider, regions] of Object.entries(byProvider)) {
    html += `<optgroup label="${provider}">`;

    regions
      .sort((a, b) => a.name.localeCompare(b.name))
      .forEach(region => {
        html += `<option value="${region.id}">${region.name}</option>`;
      });

    html += '</optgroup>';
  }

  html += '</select>';

  container.innerHTML = html;

  return {
    totalRegions: regionsData.count,
    byProvider: Object.keys(byProvider).map(provider => ({
      provider,
      count: byProvider[provider].length
    }))
  };
}

// Usage
const stats = await buildRegionSelector(
  document.getElementById('region-container'),
  'vdc_m365'
);
console.log(`Loaded ${stats.totalRegions} regions`);
```

---

## Important Notes for AI Agents

### Parsing Considerations

1. **Service Objects Are Dynamic**
   - Not all services present in all regions
   - Check for property existence before accessing
   - Absent property typically means service not available

2. **Veeam Data Cloud Vault is Special**
   - Only service with tiered availability
   - Returns array, not boolean
   - Can have 0, 1, or multiple edition/tier combinations

3. **Filter Behavior**
   - Empty result set (count: 0) is valid response
   - Don't treat as error - no regions match criteria

4. **Geographic Coordinates**
   - Approximate locations, not exact
   - Good for mapping and distance calculations
   - Not suitable for precision routing

### Best Practices for LLMs

1. **Always validate parameters** before making requests
   - Check enum values match exactly (case-sensitive)
   - Verify format of region IDs

2. **Use error messages for auto-correction**
   - Parse the `message` field for specific guidance
   - Extract valid values from error descriptions
   - Implement retry logic with corrections

3. **Leverage the /services endpoint**
   - Don't hardcode service IDs
   - Query first to understand current services
   - Use returned IDs in subsequent queries

4. **Handle empty results gracefully**
   - `count: 0` means no matches, not an error
   - Suggest broadening search criteria
   - Try removing filters one by one

5. **Combine filters strategically**
   - Start broad, add filters to narrow down
   - Test each filter individually first
   - Remember tier/edition only work with vdc_vault

6. **Cache service metadata**
   - Service list rarely changes
   - Can cache /api/v1/services response
   - Reduces API calls

### Data Freshness Expectations

- **Static data:** Region list is relatively static
- **Community maintained:** Not official Veeam data
- **Build-time compilation:** Updates require rebuild
- **No real-time updates:** Don't expect live changes
- **Verify critical data:** Cross-check with official Veeam docs for production use

### Performance Tips

1. Use `/api/v1/ping` for health checks (lightweight)
2. Use `/api/v1/health` when you need statistics
3. Filter at the API level rather than client-side
4. Cache region data when possible (1 hour is reasonable)
5. Batch lookups by using filter parameters

---

## Disclaimer

This is an unofficial, community-maintained API and is not affiliated with, endorsed by, or supported by Veeam Software. Always refer to official Veeam documentation for authoritative information about product availability and features.

## Version Information

- **API Version:** 1.0.0
- **OpenAPI Specification:** 3.1.0
- **Last Updated:** 2026-01-03
- **Total Regions:** 63 (27 AWS + 36 Azure as of 2026-01-03)

## Additional Resources

- **OpenAPI Specification:** `/api/openapi.json`
- **Interactive Documentation:** `/api/docs` (Scalar API Reference)
- **Concise Documentation:** `/llms.txt`
- **GitHub Repository:** https://github.com/comnam90/veeam-data-cloud-services-map
- **Issue Tracker:** https://github.com/comnam90/veeam-data-cloud-services-map/issues

---

End of comprehensive documentation. This file is optimized for RAG (Retrieval-Augmented Generation) systems and provides complete context for AI agents to effectively use the Veeam Data Cloud Service Availability API.