@apifreaks/openapi-specs 0.1.0

package/specs/ip-intelligence/ip-locator.json

@@ -0,0 +1,941 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "IP Geolocation API - City, Country, Coordinates & ISP Data",
+    "version": "1.0.0",
+    "description": "Retrieve real-time geolocation and network intelligence for a single IPv4 or IPv6 address or hostname. Returns location (continent, country, region, city, coordinates, timezone), network (ASN, ISP/company, route), and currency data by default. Pass `include=security,hostname,liveHostname,hostnameFallbackLive,user_agent,abuse,dma_code,geo_accuracy` (or `include=*`) to add threat-intelligence scoring, reverse DNS resolution, parsed User-Agent details, abuse contact info, DMA code, or geolocation accuracy metadata as additional response blocks. Reserved, bogon, or unrecognized IP addresses return a `423` or `404` error instead of partial location data.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v2.0",
+      "description": "IP Locator API Server"
+    }
+  ],
+  "paths": {
+    "/geolocation/lookup": {
+      "get": {
+        "tags": ["IP Geolocation APIs"],
+        "summary": "Retrieve real-time and accurate IP geolocation and threat intelligence information for an IPv4 or IPv6 address",
+        "description": "Get detailed IP geolocation data for an IP address including country, city, timezone, currency, and optional threat intelligence and user-agent information.",
+        "operationId": "ipLookup",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "ip",
+            "in": "query",
+            "required": false,
+            "description": "IPv4, IPv6, or hostname for geolocation lookup.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "lang",
+            "in": "query",
+            "required": false,
+            "description": "Response language for location fields. Default: en.",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "en",
+                "de",
+                "ru",
+                "ja",
+                "fr",
+                "cn",
+                "es",
+                "cs",
+                "it",
+                "ko",
+                "fa",
+                "pt"
+              ],
+              "default": "en"
+            }
+          },
+          {
+            "name": "fields",
+            "in": "query",
+            "required": false,
+            "description": "Comma-separated list of fields to include in response. For example, `location` includes all location fields, `location.city` is a specific field.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "excludes",
+            "in": "query",
+            "required": false,
+            "description": "Comma-separated list of fields to exclude from response.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "include",
+            "in": "query",
+            "required": false,
+            "description": "Comma-separated list of additional data modules to include. Possible values: security (threat intelligence), hostname (IP-Hostname lookup), liveHostname (live hostname lookup), hostnameFallbackLive (hostname with live fallback), user_agent (parse User-Agent header), abuse (abuse contact info), dma_code (DMA code), geo_accuracy (accuracy_radius, confidence, locality), * (all modules).",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful geolocation response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/IpLookupResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response",
+                    "value": {
+                      "ip": "8.8.8.8",
+                      "location": {
+                        "continent_code": "NA",
+                        "continent_name": "North America",
+                        "country_code2": "US",
+                        "country_code3": "USA",
+                        "country_name": "United States",
+                        "country_name_official": "United States of America",
+                        "country_capital": "Washington, D.C.",
+                        "state_prov": "California",
+                        "state_code": "US-CA",
+                        "district": "Santa Clara",
+                        "city": "Mountain View",
+                        "zipcode": "94043-1351",
+                        "latitude": "37.42240",
+                        "longitude": "-122.08421",
+                        "is_eu": false,
+                        "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
+                        "geoname_id": "6301403",
+                        "country_emoji": "\ud83c\uddfa\ud83c\uddf8"
+                      },
+                      "country_metadata": {
+                        "calling_code": "+1",
+                        "tld": ".us",
+                        "languages": ["en-US", "es-US", "haw", "fr"]
+                      },
+                      "network": {
+                        "connection_type": "",
+                        "route": "8.8.8.0/24",
+                        "is_anycast": true
+                      },
+                      "currency": {
+                        "code": "USD",
+                        "name": "US Dollar",
+                        "symbol": "$"
+                      },
+                      "asn": {
+                        "as_number": "AS15169",
+                        "organization": "Google LLC",
+                        "country": "US",
+                        "type": "BUSINESS",
+                        "domain": "google.com",
+                        "date_allocated": "2000-03-30",
+                        "rir": "ARIN"
+                      },
+                      "company": {
+                        "name": "Google LLC",
+                        "type": "HOSTING",
+                        "domain": "google.com"
+                      },
+                      "time_zone": {
+                        "name": "America/Los_Angeles",
+                        "offset": -8,
+                        "offset_with_dst": -7,
+                        "current_time": "2026-07-08 03:03:31.835-0700",
+                        "current_time_unix": 1783505011.835,
+                        "current_tz_abbreviation": "PDT",
+                        "current_tz_full_name": "Pacific Daylight Time",
+                        "standard_tz_abbreviation": "PST",
+                        "standard_tz_full_name": "Pacific Standard Time",
+                        "is_dst": true,
+                        "dst_savings": 1,
+                        "dst_exists": true,
+                        "dst_tz_abbreviation": "PDT",
+                        "dst_tz_full_name": "Pacific Daylight Time",
+                        "dst_start": {
+                          "utc_time": "2026-03-08 TIME 10:00",
+                          "duration": "+1.00H",
+                          "gap": true,
+                          "date_time_after": "2026-03-08 TIME 03:00",
+                          "date_time_before": "2026-03-08 TIME 02:00",
+                          "overlap": false
+                        },
+                        "dst_end": {
+                          "utc_time": "2026-11-01 TIME 09:00",
+                          "duration": "-1.00H",
+                          "gap": false,
+                          "date_time_after": "2026-11-01 TIME 01:00",
+                          "date_time_before": "2026-11-01 TIME 02:00",
+                          "overlap": true
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request \u2014 Invalid or missing parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "badRequest": {
+                    "summary": "Missing or invalid parameters",
+                    "value": {
+                      "message": "The request was unacceptable. Typically due to missing or invalid parameters."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found \u2014 IP address not in database",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "notFound": {
+                    "summary": "IP address not in database",
+                    "value": {
+                      "message": "Provided IP address '255.255.255.255' doesn't exist in our database."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "423": {
+            "description": "Locked \u2014 Bogon or reserved IP address",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "locked": {
+                    "summary": "Bogon or reserved IP address",
+                    "value": {
+                      "message": "'127.0.0.1' is a bogon (Internet Assigned Numbers Authority) IP address."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "IpLookupResponse": {
+        "type": "object",
+        "required": ["ip"],
+        "properties": {
+          "ip": {
+            "type": "string",
+            "description": "The IP address used for the lookup (IPv4 or IPv6)."
+          },
+          "domain": {
+            "type": "string",
+            "description": "The input domain, returned only for domain-based lookups."
+          },
+          "hostname": {
+            "type": "string",
+            "description": "Reverse DNS hostname (PTR) for the input IP; returns the input IP if not resolvable."
+          },
+          "location": {
+            "$ref": "#/components/schemas/Location"
+          },
+          "country_metadata": {
+            "$ref": "#/components/schemas/CountryMetadata"
+          },
+          "network": {
+            "$ref": "#/components/schemas/Network"
+          },
+          "asn": {
+            "$ref": "#/components/schemas/Asn"
+          },
+          "company": {
+            "$ref": "#/components/schemas/Company"
+          },
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
+          },
+          "security": {
+            "$ref": "#/components/schemas/Security"
+          },
+          "abuse": {
+            "$ref": "#/components/schemas/Abuse"
+          },
+          "time_zone": {
+            "$ref": "#/components/schemas/TimeZone"
+          },
+          "user_agent": {
+            "$ref": "#/components/schemas/UserAgent"
+          }
+        }
+      },
+      "Location": {
+        "type": "object",
+        "description": "Geographic location information for the IP.",
+        "required": [
+          "continent_code",
+          "continent_name",
+          "country_code2",
+          "country_code3",
+          "country_name",
+          "country_name_official",
+          "country_capital",
+          "latitude",
+          "longitude",
+          "is_eu",
+          "country_flag"
+        ],
+        "properties": {
+          "continent_code": {
+            "type": "string",
+            "description": "2-letter code of the continent."
+          },
+          "continent_name": {
+            "type": "string",
+            "description": "Name of the continent."
+          },
+          "country_code2": {
+            "type": "string",
+            "description": "Country code (ISO 3166-1 alpha-2) of the country."
+          },
+          "country_code3": {
+            "type": "string",
+            "description": "Country code (ISO 3166-1 alpha-3) of the country."
+          },
+          "country_name": {
+            "type": "string",
+            "description": "Name of the country."
+          },
+          "country_name_official": {
+            "type": "string",
+            "description": "Official name (ISO 3166) of the country."
+          },
+          "country_capital": {
+            "type": "string",
+            "description": "Name of the country's capital."
+          },
+          "state_prov": {
+            "type": "string",
+            "description": "Name of the state/province/region."
+          },
+          "state_code": {
+            "type": "string",
+            "description": "Code of the state/province/region."
+          },
+          "district": {
+            "type": "string",
+            "description": "Name of the district or county."
+          },
+          "city": {
+            "type": "string",
+            "description": "Name of the city."
+          },
+          "locality": {
+            "type": "string",
+            "description": "A more specific area in city or it can be same as city."
+          },
+          "accuracy_radius": {
+            "type": "string",
+            "description": "Circular radius in Km, where the IP address location can be found."
+          },
+          "confidence": {
+            "type": "string",
+            "description": "Confidence level of the location match (e.g., low, medium, high)."
+          },
+          "dma_code": {
+            "type": ["string", "null"],
+            "description": "Designated Market Area (DMA) code used in the United States for media marketing."
+          },
+          "zipcode": {
+            "type": "string",
+            "description": "ZIP/Postal code of the place."
+          },
+          "latitude": {
+            "type": "string",
+            "description": "Latitude of the place."
+          },
+          "longitude": {
+            "type": "string",
+            "description": "Longitude of the place."
+          },
+          "is_eu": {
+            "type": "boolean",
+            "description": "Is the country belong to European Union?"
+          },
+          "country_flag": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL to get the country flag."
+          },
+          "geoname_id": {
+            "type": "string",
+            "description": "Geoname ID of the place from geonames.org."
+          },
+          "country_emoji": {
+            "type": "string",
+            "description": "Emoji of the Country flag."
+          }
+        }
+      },
+      "CountryMetadata": {
+        "type": "object",
+        "description": "Country-specific metadata.",
+        "required": ["calling_code", "tld", "languages"],
+        "properties": {
+          "calling_code": {
+            "type": "string",
+            "description": "Calling code/Dialing code of the country."
+          },
+          "tld": {
+            "type": "string",
+            "description": "Top Level Domain Name (TLD) of the country, which is also called ccTLD."
+          },
+          "languages": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "List of the languages' codes, spoken in the country."
+          }
+        }
+      },
+      "Network": {
+        "type": "object",
+        "description": "Network information for the IP.",
+        "properties": {
+          "connection_type": {
+            "type": "string",
+            "description": "Network access type classification (e.g., DSL, Cable, Mobile, 5G) when available."
+          },
+          "route": {
+            "type": "string",
+            "description": "Network prefix in CIDR notation that contains the IP."
+          },
+          "is_anycast": {
+            "type": "boolean",
+            "description": "true if the IP is anycast (same IP announced from multiple locations)."
+          }
+        }
+      },
+      "Asn": {
+        "type": "object",
+        "description": "Autonomous System details for the IP.",
+        "properties": {
+          "as_number": {
+            "type": "string",
+            "description": "ASN identifier in AS<number> format associated with the IP's network."
+          },
+          "organization": {
+            "type": "string",
+            "description": "ASN operator name."
+          },
+          "country": {
+            "type": "string",
+            "description": "ASN registration country as ISO 3166-1 alpha-2."
+          },
+          "type": {
+            "type": "string",
+            "description": "ASN category (ISP, HOSTING, BUSINESS, etc.)."
+          },
+          "domain": {
+            "type": "string",
+            "description": "ASN operator domain name."
+          },
+          "date_allocated": {
+            "type": "string",
+            "description": "ASN allocation date in YYYY-MM-DD format."
+          },
+          "rir": {
+            "type": "string",
+            "description": "Regional Internet Registry that allocated the ASN."
+          }
+        }
+      },
+      "Company": {
+        "type": "object",
+        "description": "Company or ISP information mapped to the IP address.",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Company name mapped to the IP."
+          },
+          "type": {
+            "type": "string",
+            "description": "Company category (ISP, HOSTING, BUSINESS, etc.)."
+          },
+          "domain": {
+            "type": "string",
+            "description": "Company domain name."
+          }
+        }
+      },
+      "Currency": {
+        "type": "object",
+        "description": "Currency information for the IP's country.",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Currency code (ISO 4217)."
+          },
+          "name": {
+            "type": "string",
+            "description": "Currency name (ISO 4217)."
+          },
+          "symbol": {
+            "type": "string",
+            "description": "Currency symbol."
+          }
+        }
+      },
+      "Security": {
+        "type": "object",
+        "description": "Threat intelligence and security information for the IP.",
+        "required": [
+          "threat_score",
+          "is_tor",
+          "is_proxy",
+          "proxy_confidence_score",
+          "is_residential_proxy",
+          "is_vpn",
+          "vpn_confidence_score",
+          "is_relay",
+          "is_anonymous",
+          "is_known_attacker",
+          "is_bot",
+          "is_spam",
+          "is_cloud_provider"
+        ],
+        "properties": {
+          "threat_score": {
+            "type": "number",
+            "description": "Aggregate risk score from 0 to 100."
+          },
+          "is_tor": {
+            "type": "boolean",
+            "description": "true if the IP matches a Tor exit node."
+          },
+          "is_proxy": {
+            "type": "boolean",
+            "description": "true if the IP is associated with a proxy service."
+          },
+          "proxy_provider_names": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Detected proxy provider names."
+          },
+          "proxy_confidence_score": {
+            "type": "number",
+            "description": "Proxy detection confidence from 0 to 100."
+          },
+          "proxy_last_seen": {
+            "type": "string",
+            "description": "Last observed proxy activity date in YYYY-MM-DD."
+          },
+          "is_residential_proxy": {
+            "type": "boolean",
+            "description": "true if the IP is linked to a residential proxy network."
+          },
+          "is_vpn": {
+            "type": "boolean",
+            "description": "true if the IP is associated with a VPN service."
+          },
+          "vpn_provider_names": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Detected VPN provider names."
+          },
+          "vpn_confidence_score": {
+            "type": "number",
+            "description": "VPN detection confidence from 0 to 100."
+          },
+          "vpn_last_seen": {
+            "type": "string",
+            "description": "Last observed VPN activity date in YYYY-MM-DD."
+          },
+          "is_relay": {
+            "type": "boolean",
+            "description": "true if the IP is associated with a relay network."
+          },
+          "relay_provider_name": {
+            "type": "string",
+            "description": "Relay provider name."
+          },
+          "is_anonymous": {
+            "type": "boolean",
+            "description": "true if any anonymity signal is present."
+          },
+          "is_known_attacker": {
+            "type": "boolean",
+            "description": "true if the IP is flagged for known attacker behavior."
+          },
+          "is_bot": {
+            "type": "boolean",
+            "description": "true if the IP is associated with bot activity."
+          },
+          "is_spam": {
+            "type": "boolean",
+            "description": "true if the IP is associated with spam activity."
+          },
+          "is_cloud_provider": {
+            "type": "boolean",
+            "description": "true if the IP belongs to a cloud provider range."
+          },
+          "cloud_provider_name": {
+            "type": "string",
+            "description": "Cloud provider name."
+          }
+        }
+      },
+      "Abuse": {
+        "type": "object",
+        "description": "Abuse contact information for the IP.",
+        "properties": {
+          "route": {
+            "type": "string",
+            "description": "Abuse-handling IP range in CIDR notation."
+          },
+          "country": {
+            "type": "string",
+            "description": "ISO 3166-1 alpha-2 country code of the abuse contact."
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name for the abuse contact."
+          },
+          "organization": {
+            "type": "string",
+            "description": "Organization name for the abuse contact."
+          },
+          "kind": {
+            "type": "string",
+            "description": "Contact type: group or individual."
+          },
+          "address": {
+            "type": "string",
+            "description": "Registered address of the organization owning the IP."
+          },
+          "emails": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Abuse contact email addresses."
+          },
+          "phone_numbers": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Abuse contact phone numbers."
+          }
+        }
+      },
+      "DstTransition": {
+        "type": "object",
+        "description": "DST transition details (used for both the DST start and DST end transitions).",
+        "properties": {
+          "utc_time": {
+            "type": "string",
+            "description": "DST transition moment in UTC."
+          },
+          "duration": {
+            "type": "string",
+            "description": "Clock change at the DST transition, in hours."
+          },
+          "gap": {
+            "type": "boolean",
+            "description": "true if local time jumps forward (some times do not exist)."
+          },
+          "date_time_after": {
+            "type": "string",
+            "description": "Local date/time immediately after the DST transition."
+          },
+          "date_time_before": {
+            "type": "string",
+            "description": "Local date/time immediately before the DST transition."
+          },
+          "overlap": {
+            "type": "boolean",
+            "description": "true if local times repeat around the DST transition."
+          }
+        }
+      },
+      "TimeZone": {
+        "type": "object",
+        "description": "Time zone information for the IP's location.",
+        "required": [
+          "name",
+          "offset",
+          "offset_with_dst",
+          "current_time",
+          "current_time_unix",
+          "is_dst",
+          "dst_savings",
+          "dst_exists"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Time zone in IANA TZDB format."
+          },
+          "offset": {
+            "type": "number",
+            "format": "float",
+            "description": "Standard time UTC offset in hours."
+          },
+          "offset_with_dst": {
+            "type": "number",
+            "format": "float",
+            "description": "Current effective UTC offset in hours, including DST."
+          },
+          "current_time": {
+            "type": "string",
+            "description": "Local date/time in YYYY-MM-DD HH:mm:ss.SSS\u00b1ZZZZ format."
+          },
+          "current_time_unix": {
+            "type": "number",
+            "format": "float",
+            "description": "Local time as Unix epoch seconds."
+          },
+          "current_tz_abbreviation": {
+            "type": "string",
+            "description": "Current time zone abbreviation."
+          },
+          "current_tz_full_name": {
+            "type": "string",
+            "description": "Current time zone full name."
+          },
+          "standard_tz_abbreviation": {
+            "type": "string",
+            "description": "Standard (non-DST) abbreviation."
+          },
+          "standard_tz_full_name": {
+            "type": "string",
+            "description": "Standard (non-DST) full name."
+          },
+          "is_dst": {
+            "type": "boolean",
+            "description": "true if DST is active."
+          },
+          "dst_savings": {
+            "type": "number",
+            "format": "float",
+            "description": "DST shift amount in hours."
+          },
+          "dst_exists": {
+            "type": "boolean",
+            "description": "true if the time zone observes DST."
+          },
+          "dst_tz_abbreviation": {
+            "type": "string",
+            "description": "DST abbreviation when DST is active."
+          },
+          "dst_tz_full_name": {
+            "type": "string",
+            "description": "DST full name when DST is active."
+          },
+          "dst_start": {
+            "$ref": "#/components/schemas/DstTransition"
+          },
+          "dst_end": {
+            "$ref": "#/components/schemas/DstTransition"
+          }
+        }
+      },
+      "Device": {
+        "type": "object",
+        "description": "Device details.",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Detected device label."
+          },
+          "type": {
+            "type": "string",
+            "description": "Device category (Desktop, Mobile, Tablet, Bot)."
+          },
+          "brand": {
+            "type": "string",
+            "description": "Device vendor/brand."
+          },
+          "cpu": {
+            "type": "string",
+            "description": "CPU / architecture string."
+          }
+        }
+      },
+      "Engine": {
+        "type": "object",
+        "description": "Rendering engine details.",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Rendering engine name."
+          },
+          "type": {
+            "type": "string",
+            "description": "Engine category."
+          },
+          "version": {
+            "type": "string",
+            "description": "Full engine version string."
+          },
+          "version_major": {
+            "type": "string",
+            "description": "Major engine version."
+          }
+        }
+      },
+      "OperatingSystem": {
+        "type": "object",
+        "description": "Operating system details.",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Operating system name."
+          },
+          "type": {
+            "type": "string",
+            "description": "OS category (Desktop, Mobile, Server)."
+          },
+          "version": {
+            "type": "string",
+            "description": "OS version string."
+          },
+          "version_major": {
+            "type": "string",
+            "description": "Major OS version."
+          },
+          "build": {
+            "type": "string",
+            "description": "OS build identifier."
+          }
+        }
+      },
+      "UserAgent": {
+        "type": "object",
+        "description": "Parsed User-Agent details from the request.",
+        "properties": {
+          "user_agent_string": {
+            "type": "string",
+            "description": "Raw User-Agent string used for parsing."
+          },
+          "name": {
+            "type": "string",
+            "description": "Detected user agent product name."
+          },
+          "type": {
+            "type": "string",
+            "description": "User agent category (e.g., Browser, Mobile App, Bot)."
+          },
+          "version": {
+            "type": "string",
+            "description": "Full product version string."
+          },
+          "version_major": {
+            "type": "string",
+            "description": "Major version extracted from version."
+          },
+          "device": {
+            "$ref": "#/components/schemas/Device"
+          },
+          "engine": {
+            "$ref": "#/components/schemas/Engine"
+          },
+          "operating_system": {
+            "$ref": "#/components/schemas/OperatingSystem"
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}