General API

The General API provides a set of infrastructure-level endpoints designed for environmental diagnostics and the retrieval of global static datasets. These tools are essential for verifying network reachability, inspecting client-server connection properties, and populating standardized geographic data across your application.

Infrastructure Health (Ping)

A high-performance heartbeat endpoint used to verify that the DonutWork API gateway is operational and to measure basic network round-trip time (RTT).

{
  "status": "success",
  "env": "production",
  "RRT": "1.42 ms"
}

Technical Implementation

curl --location --request GET \
'https://api.hub.donutwork.com/2026-02-01/ping.json' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

const heartbeat = await sdk.utils.ping();
console.log(`System Status: ${heartbeat.status} (${heartbeat.RRT})`);

Connection Diagnostics

Retrieve a detailed diagnostic profile of your current API session. This endpoint is instrumental for debugging network protocols, verifying IP whitelisting, and ensuring the correct API version is being targeted.

{
  "client": {
    "userAgent": "PostmanRuntime/7.43.0",
    "ips": {
      "ipv4": "192.168.1.1"
    }
  },
  "endpoint": {
    "apiVersion": "2026-02-01",
    "env": "production",
    "protocol": "HTTP2"
  }
}

Global Metadata (Countries)

Retrieve a comprehensive, standardized list of countries and their associated ISO 3166-1 alpha-2 codes. This dataset ensures data integrity when capturing geographic information in user profiles or billing addresses.

[
  {
    "code": "US",
    "name": "United States"
  },
  {
    "code": "GB",
    "name": "United Kingdom"
  },
  {
    "code": "IT",
    "name": "Italy"
  },
  {
    "code": "DE",
    "name": "Germany"
  },
  {
    "code": "FR",
    "name": "France"
  }
]

Technical Implementation

curl --location --request GET \
'https://api.hub.donutwork.com/2026-02-01/countries/countries.json' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

const countryList = await sdk.utils.listCountries();
const italy = countryList.find(c => c.code === 'IT');
console.log(`Country Name: ${italy.name}`);