{
  "openapi": "3.1.0",
  "info": {
    "title": "LIVEUTC.AI API",
    "version": "1.0.0",
    "description": "AI-native UTC time and temporal context endpoints for LLMs and AI agents."
  },
  "servers": [
    {
      "url": "https://liveutc.ai"
    }
  ],
  "paths": {
    "/v1/time.json": {
      "get": {
        "summary": "Get live UTC time context",
        "responses": {
          "200": {
            "description": "Live UTC temporal anchor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/time": {
      "get": {
        "summary": "Get live time for a specific IANA timezone",
        "parameters": [
          {
            "name": "tz",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "Europe/Paris"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Timezone-aware temporal context",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimezoneTimeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid timezone",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/status": {
      "get": {
        "summary": "Get service status",
        "responses": {
          "200": {
            "description": "Service status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/cities": {
      "get": {
        "summary": "List supported cities and their IANA timezones",
        "responses": {
          "200": {
            "description": "Supported city list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CityListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/timezones": {
      "get": {
        "summary": "List supported IANA timezones",
        "responses": {
          "200": {
            "description": "Supported timezone list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimezoneListResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TimeResponse": {
        "type": "object",
        "required": [
          "service",
          "maintainer",
          "version",
          "type",
          "timezone",
          "utc",
          "local_time",
          "unix",
          "offset",
          "precision",
          "status",
          "generated_at"
        ],
        "properties": {
          "service": {
            "type": "string",
            "example": "LIVEUTC.AI"
          },
          "maintainer": {
            "type": "string",
            "example": "IVEON.AI"
          },
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "type": {
            "type": "string",
            "example": "temporal_anchor"
          },
          "timezone": {
            "type": "string",
            "example": "UTC"
          },
          "utc": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-23T12:04:00Z"
          },
          "local_time": {
            "type": "string",
            "example": "2026-05-23T12:04:00+00:00"
          },
          "unix": {
            "type": "integer",
            "example": 1779537840
          },
          "offset": {
            "type": "string",
            "example": "+00:00"
          },
          "precision": {
            "type": "string",
            "example": "second"
          },
          "status": {
            "type": "string",
            "example": "synchronized"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-05-23T12:04:00Z"
          },
          "ai_note": {
            "type": "string"
          }
        }
      },
      "TimezoneTimeResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TimeResponse"
          },
          {
            "type": "object",
            "properties": {
              "timezone": {
                "type": "string",
                "example": "Europe/Paris"
              },
              "type": {
                "type": "string",
                "example": "timezone_time"
              }
            }
          }
        ]
      },
      "StatusResponse": {
        "type": "object",
        "required": [
          "service",
          "maintainer",
          "version",
          "status",
          "utc",
          "unix",
          "generated_at"
        ],
        "properties": {
          "service": {
            "type": "string",
            "example": "LIVEUTC.AI"
          },
          "maintainer": {
            "type": "string",
            "example": "IVEON.AI"
          },
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "build": {
            "type": "string",
            "example": "2026-05-23-final"
          },
          "status": {
            "type": "string",
            "example": "operational"
          },
          "utc": {
            "type": "string",
            "format": "date-time"
          },
          "unix": {
            "type": "integer"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "rate_limit_policy": {
            "type": "string",
            "example": "120 requests per minute per IP, enforced at Cloudflare edge when enabled."
          }
        }
      },
      "CityListResponse": {
        "type": "object",
        "required": [
          "service",
          "maintainer",
          "version",
          "count",
          "cities"
        ],
        "properties": {
          "service": {
            "type": "string",
            "example": "LIVEUTC.AI"
          },
          "maintainer": {
            "type": "string",
            "example": "IVEON.AI"
          },
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "count": {
            "type": "integer",
            "example": 56
          },
          "cities": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "slug",
                "city",
                "country",
                "timezone",
                "page",
                "api"
              ],
              "properties": {
                "slug": {
                  "type": "string",
                  "example": "agadir"
                },
                "city": {
                  "type": "string",
                  "example": "Agadir"
                },
                "country": {
                  "type": "string",
                  "example": "Morocco"
                },
                "timezone": {
                  "type": "string",
                  "example": "Africa/Casablanca"
                },
                "page": {
                  "type": "string",
                  "example": "https://liveutc.ai/city/agadir"
                },
                "api": {
                  "type": "string",
                  "example": "https://liveutc.ai/v1/time?tz=Africa%2FCasablanca"
                }
              }
            }
          }
        }
      },
      "TimezoneListResponse": {
        "type": "object",
        "required": [
          "service",
          "maintainer",
          "version",
          "count",
          "timezones"
        ],
        "properties": {
          "service": {
            "type": "string",
            "example": "LIVEUTC.AI"
          },
          "maintainer": {
            "type": "string",
            "example": "IVEON.AI"
          },
          "version": {
            "type": "string",
            "example": "1.0"
          },
          "count": {
            "type": "integer",
            "example": 43
          },
          "timezones": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "timezone",
                "page",
                "api"
              ],
              "properties": {
                "timezone": {
                  "type": "string",
                  "example": "Africa/Casablanca"
                },
                "page": {
                  "type": "string",
                  "example": "https://liveutc.ai/timezone/africa-casablanca"
                },
                "api": {
                  "type": "string",
                  "example": "https://liveutc.ai/v1/time?tz=Africa%2FCasablanca"
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error",
          "code",
          "message",
          "documentation"
        ],
        "properties": {
          "error": {
            "type": "boolean",
            "example": true
          },
          "code": {
            "type": "string",
            "example": "INVALID_TIMEZONE"
          },
          "message": {
            "type": "string"
          },
          "documentation": {
            "type": "string"
          }
        }
      }
    }
  }
}