{
  "openapi": "3.1.0",
  "info": {
    "title": "Arrival.info Public Curb ETA",
    "version": "1.0.0",
    "description": "A deterministic, read-only flight-to-curb estimate contract. It does not create pickups, mutate HUG, consume entitlements, send notifications, or invoke an LLM. Availability through this API does not guarantee Google indexing, citation, or summary inclusion."
  },
  "servers": [
    {
      "url": "https://arrival.info"
    }
  ],
  "paths": {
    "/api/public/v1/curb-eta": {
      "get": {
        "operationId": "getPublicCurbEta",
        "summary": "Estimate when a flight passenger may reach the destination curb",
        "description": "Uses current flight data and Arrival.info's canonical curb-time engine. The response is an estimate, not a guarantee. Date and destination may be omitted only when the latest provider result is unambiguous. The route is rate-limited, budget-governed, cached briefly, and may be disabled with a runtime kill switch.",
        "parameters": [
          {
            "name": "flightNumber",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9 -]{1,8}$"
            },
            "example": "UA123"
          },
          {
            "name": "arrivalDate",
            "in": "query",
            "required": false,
            "description": "Destination-local arrival date. Required when the latest flight cannot be resolved unambiguously.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-08-19"
          },
          {
            "name": "destinationAirport",
            "in": "query",
            "required": false,
            "description": "Three-letter destination IATA code. Required when multiple destination legs match.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{3}$"
            },
            "example": "EWR"
          },
          {
            "name": "terminal",
            "in": "query",
            "required": false,
            "description": "Optional terminal hint. Provider truth takes precedence and any override is disclosed.",
            "schema": {
              "type": "string",
              "maxLength": 24
            }
          },
          {
            "name": "hasCheckedBags",
            "in": "query",
            "required": false,
            "description": "Unknown is modeled conservatively and disclosed in limitations.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false",
                "unknown"
              ],
              "default": "unknown"
            }
          },
          {
            "name": "responseMode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "const": "json",
              "default": "json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A typed ETA or a valid non-ETA state such as insufficient_data, stale, cancelled, or diverted.",
            "headers": {
              "X-Arrival-Contract-Version": {
                "schema": {
                  "type": "string",
                  "const": "1.0"
                }
              },
              "X-Arrival-Cache": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "hit",
                    "miss",
                    "coalesced",
                    "blocked"
                  ]
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCurbEtaResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed normalized input; no provider request is made.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvalidRequest"
                }
              }
            }
          },
          "404": {
            "description": "The route is disabled or the exact flight is definitively not found.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PublicCurbEtaResponse"
                    },
                    {
                      "$ref": "#/components/schemas/DisabledRoute"
                    }
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Multiple candidates remain; requiredFields identifies the necessary disambiguation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCurbEtaResponse"
                }
              }
            }
          },
          "429": {
            "description": "A request or provider ceiling was reached. Retry-After is supplied and no unguarded request is made.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCurbEtaResponse"
                }
              }
            }
          },
          "503": {
            "description": "The provider, budget governor, or fail-closed safety guard is unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicCurbEtaResponse"
                }
              }
            }
          }
        },
        "x-arrival-rate-limits": {
          "perIp": {
            "limit": 12,
            "windowSeconds": 60
          },
          "perFlight": {
            "limit": 30,
            "windowSeconds": 60
          },
          "providerDailyDefaultCap": 100,
          "behavior": "Fail closed. Cached responses do not reserve provider budget; identical misses are coalesced."
        },
        "x-arrival-no-mutation": true,
        "x-arrival-no-llm": true,
        "x-arrival-google-summary-guarantee": false
      }
    }
  },
  "components": {
    "schemas": {
      "PublicCurbEtaResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contractVersion",
          "state",
          "flight",
          "airport",
          "curb",
          "freshness",
          "components",
          "provenance",
          "limitations"
        ],
        "properties": {
          "contractVersion": {
            "type": "string",
            "const": "1.0"
          },
          "state": {
            "type": "string",
            "enum": [
              "estimated",
              "landed_estimated",
              "scheduled_only",
              "insufficient_data",
              "ambiguous_request",
              "not_found",
              "cancelled",
              "diverted",
              "stale",
              "unavailable",
              "rate_limited"
            ]
          },
          "flight": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "number",
              "status",
              "origin",
              "destination",
              "scheduledDeparture",
              "actualDeparture",
              "scheduledArrival",
              "estimatedArrival",
              "actualLanding",
              "terminal",
              "gate"
            ],
            "properties": {
              "number": {
                "type": "string"
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "origin": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "destination": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "scheduledDeparture": {
                "$ref": "#/components/schemas/NullableTimestamp"
              },
              "actualDeparture": {
                "$ref": "#/components/schemas/NullableTimestamp"
              },
              "scheduledArrival": {
                "$ref": "#/components/schemas/NullableTimestamp"
              },
              "estimatedArrival": {
                "$ref": "#/components/schemas/NullableTimestamp"
              },
              "actualLanding": {
                "$ref": "#/components/schemas/NullableTimestamp"
              },
              "terminal": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "gate": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "airport": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "iata",
              "displayName",
              "timezone"
            ],
            "properties": {
              "iata": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "displayName": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "timezone": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "curb": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "curbEtaUtc",
                  "curbEtaLocal",
                  "afterLandingMinutes",
                  "confidence",
                  "rangeMinutes"
                ],
                "properties": {
                  "curbEtaUtc": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "curbEtaLocal": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "afterLandingMinutes": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "confidence": {
                    "type": "string",
                    "enum": [
                      "low",
                      "medium",
                      "high"
                    ]
                  },
                  "rangeMinutes": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "minimum": 0
                  }
                }
              }
            ]
          },
          "freshness": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "generatedAt",
              "sourceObservedAt",
              "expiresAt",
              "ageSeconds",
              "status"
            ],
            "properties": {
              "generatedAt": {
                "type": "string",
                "format": "date-time"
              },
              "sourceObservedAt": {
                "$ref": "#/components/schemas/NullableTimestamp"
              },
              "expiresAt": {
                "$ref": "#/components/schemas/NullableTimestamp"
              },
              "ageSeconds": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0
              },
              "status": {
                "type": "string",
                "enum": [
                  "fresh",
                  "stale",
                  "unavailable"
                ]
              }
            }
          },
          "components": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "taxiInMinutes",
                  "deplaningMinutes",
                  "baggageMinutes",
                  "customsMinutes",
                  "walkingTransferMinutes",
                  "totalMinutes"
                ],
                "properties": {
                  "taxiInMinutes": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "deplaningMinutes": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "baggageMinutes": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "customsMinutes": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "walkingTransferMinutes": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "totalMinutes": {
                    "type": "integer",
                    "minimum": 0
                  }
                }
              }
            ]
          },
          "provenance": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "sourceClass",
              "modelVersion",
              "retrievedAt",
              "fieldCoverage"
            ],
            "properties": {
              "sourceClass": {
                "type": "string",
                "enum": [
                  "aerodatabox_actual",
                  "aerodatabox_estimate",
                  "aerodatabox_schedule",
                  "none"
                ]
              },
              "modelVersion": {
                "type": "string"
              },
              "retrievedAt": {
                "type": "string",
                "format": "date-time"
              },
              "fieldCoverage": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "code",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          },
          "requiredFields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "flightNumber",
                "arrivalDate",
                "destinationAirport"
              ]
            }
          },
          "retryAfterSeconds": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "NullableTimestamp": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "InvalidRequest": {
        "type": "object",
        "required": [
          "contractVersion",
          "state",
          "error",
          "issues"
        ],
        "properties": {
          "contractVersion": {
            "type": "string",
            "const": "1.0"
          },
          "state": {
            "type": "string",
            "const": "unavailable"
          },
          "error": {
            "type": "string",
            "const": "invalid_request"
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "DisabledRoute": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "const": "not_found"
          }
        }
      }
    }
  }
}